From c3d04570c091366a0b75a32df96daa9d923c309c Mon Sep 17 00:00:00 2001 From: Jeromy Date: Mon, 3 Nov 2014 03:53:16 +0000 Subject: [PATCH] a few more comments --- blocks/blocks.go | 3 +++ merkledag/merkledag.go | 7 +++++++ namesys/publisher.go | 1 + peer/peer.go | 1 + pin/pin.go | 15 +++++++++++---- 5 files changed, 23 insertions(+), 4 deletions(-) diff --git a/blocks/blocks.go b/blocks/blocks.go index b87cf5a32..1a94ee499 100644 --- a/blocks/blocks.go +++ b/blocks/blocks.go @@ -19,6 +19,9 @@ func NewBlock(data []byte) *Block { return &Block{Data: data, Multihash: u.Hash(data)} } +// NewBlockWithHash creates a new block when the hash of the data +// is already known, this is used to save time in situations where +// we are able to be confident that the data is correct func NewBlockWithHash(data []byte, h mh.Multihash) (*Block, error) { if u.Debug { chk := u.Hash(data) diff --git a/merkledag/merkledag.go b/merkledag/merkledag.go index 26431dea2..79709392e 100644 --- a/merkledag/merkledag.go +++ b/merkledag/merkledag.go @@ -48,6 +48,7 @@ type Link struct { Node *Node } +// MakeLink creates a link to the given node func MakeLink(n *Node) (*Link, error) { s, err := n.Size() if err != nil { @@ -64,6 +65,7 @@ func MakeLink(n *Node) (*Link, error) { }, nil } +// GetNode returns the MDAG Node that this link points to func (l *Link) GetNode(serv DAGService) (*Node, error) { if l.Node != nil { return l.Node, nil @@ -98,6 +100,7 @@ func (n *Node) AddNodeLinkClean(name string, that *Node) error { return nil } +// Remove a link on this node by the given name func (n *Node) RemoveNodeLink(name string) error { for i, l := range n.Links { if l.Name == name { @@ -196,6 +199,7 @@ func (n *dagService) Add(nd *Node) (u.Key, error) { return n.Blocks.AddBlock(b) } +// AddRecursive adds the given node and all child nodes to the BlockService func (n *dagService) AddRecursive(nd *Node) error { _, err := n.Add(nd) if err != nil { @@ -230,6 +234,7 @@ func (n *dagService) Get(k u.Key) (*Node, error) { return Decoded(b.Data) } +// Remove deletes the given node and all of its children from the BlockService func (n *dagService) Remove(nd *Node) error { for _, l := range nd.Links { if l.Node != nil { @@ -243,6 +248,8 @@ func (n *dagService) Remove(nd *Node) error { return n.Blocks.DeleteBlock(k) } +// FetchGraph asynchronously fetches all nodes that are children of the given +// node, and returns a channel that may be waited upon for the fetch to complete func FetchGraph(ctx context.Context, root *Node, serv DAGService) chan struct{} { var wg sync.WaitGroup done := make(chan struct{}) diff --git a/namesys/publisher.go b/namesys/publisher.go index d95f1cbbc..f7bf508b6 100644 --- a/namesys/publisher.go +++ b/namesys/publisher.go @@ -26,6 +26,7 @@ func NewRoutingPublisher(route routing.IpfsRouting) Publisher { } // Publish implements Publisher. Accepts a keypair and a value, +// and publishes it out to the routing system func (p *ipnsPublisher) Publish(k ci.PrivKey, value string) error { log.Debugf("namesys: Publish %s", value) diff --git a/peer/peer.go b/peer/peer.go index 9455f038f..fbea65fd1 100644 --- a/peer/peer.go +++ b/peer/peer.go @@ -274,6 +274,7 @@ func (p *peer) VerifyAndSetPubKey(pk ic.PubKey) error { panic("invariant violated: unexpected key mismatch") } +// Updates this peer with information from another peer instance func (p *peer) Update(other Peer) error { if !p.ID().Equal(other.ID()) { return errors.New("peer ids do not match") diff --git a/pin/pin.go b/pin/pin.go index dba14a977..cdd40c450 100644 --- a/pin/pin.go +++ b/pin/pin.go @@ -1,9 +1,6 @@ package pin import ( - - //ds "github.com/jbenet/go-ipfs/Godeps/_workspace/src/github.com/jbenet/datastore.go" - "encoding/json" "errors" "sync" @@ -36,12 +33,14 @@ type Pinner interface { } // ManualPinner is for manually editing the pin structure -// Use with care +// Use with care! If used improperly, garbage collection +// may not be successful type ManualPinner interface { PinWithMode(util.Key, PinMode) Pinner } +// pinner implements the Pinner interface type pinner struct { lock sync.RWMutex recursePin set.BlockSet @@ -51,6 +50,7 @@ type pinner struct { dstore ds.Datastore } +// NewPinner creates a new pinner using the given datastore as a backend func NewPinner(dstore ds.Datastore, serv mdag.DAGService) Pinner { // Load set from given datastore... @@ -70,6 +70,7 @@ func NewPinner(dstore ds.Datastore, serv mdag.DAGService) Pinner { } } +// Pin the given node, optionally recursive func (p *pinner) Pin(node *mdag.Node, recurse bool) error { p.lock.Lock() defer p.lock.Unlock() @@ -95,6 +96,7 @@ func (p *pinner) Pin(node *mdag.Node, recurse bool) error { return nil } +// Unpin a given key with optional recursive unpinning func (p *pinner) Unpin(k util.Key, recurse bool) error { p.lock.Lock() defer p.lock.Unlock() @@ -158,6 +160,7 @@ func (p *pinner) pinLinks(node *mdag.Node) error { return nil } +// IsPinned returns whether or not the given key is pinned func (p *pinner) IsPinned(key util.Key) bool { p.lock.RLock() defer p.lock.RUnlock() @@ -166,6 +169,7 @@ func (p *pinner) IsPinned(key util.Key) bool { p.indirPin.HasKey(key) } +// LoadPinner loads a pinner and its keysets from the given datastore func LoadPinner(d ds.Datastore, dserv mdag.DAGService) (Pinner, error) { p := new(pinner) @@ -200,6 +204,7 @@ func LoadPinner(d ds.Datastore, dserv mdag.DAGService) (Pinner, error) { return p, nil } +// Flush encodes and writes pinner keysets to the datastore func (p *pinner) Flush() error { p.lock.RLock() defer p.lock.RUnlock() @@ -244,6 +249,8 @@ func loadSet(d ds.Datastore, k ds.Key, val interface{}) error { return json.Unmarshal(bf, val) } +// PinWithMode is a method on ManualPinners, allowing the user to have fine +// grained control over pin counts func (p *pinner) PinWithMode(k util.Key, mode PinMode) { switch mode { case Recursive: