From ee7a8f3482db87c824e01a68c388799b3651bce4 Mon Sep 17 00:00:00 2001 From: Hector Sanjuan Date: Tue, 13 Feb 2018 12:53:20 +0100 Subject: [PATCH] Docs: golint-ify pin package License: MIT Signed-off-by: Hector Sanjuan --- pin/gc/gc.go | 19 ++++++++++++++++++- pin/pin.go | 26 ++++++++++++++++++-------- 2 files changed, 36 insertions(+), 9 deletions(-) diff --git a/pin/gc/gc.go b/pin/gc/gc.go index 92c8cb52a..1ed5f1672 100644 --- a/pin/gc/gc.go +++ b/pin/gc/gc.go @@ -1,3 +1,4 @@ +// Package gc provides garbage collection for go-ipfs. package gc import ( @@ -35,7 +36,6 @@ type Result struct { // // The routine then iterates over every block in the blockstore and // deletes any block that is not found in the marked set. -// func GC(ctx context.Context, bs bstore.GCBlockstore, dstor dstore.Datastore, pn pin.Pinner, bestEffortRoots []*cid.Cid) <-chan Result { elock := log.EventBegin(ctx, "GC.lockWait") @@ -125,6 +125,9 @@ func GC(ctx context.Context, bs bstore.GCBlockstore, dstor dstore.Datastore, pn return output } +// Descendants recursively finds all the descendants of the given roots and +// adds them to the given cid.Set, using the provided dag.GetLinks function +// to walk the tree. func Descendants(ctx context.Context, getLinks dag.GetLinks, set *cid.Set, roots []*cid.Cid) error { for _, c := range roots { set.Add(c) @@ -191,24 +194,38 @@ func ColoredSet(ctx context.Context, pn pin.Pinner, ng ipld.NodeGetter, bestEffo return gcs, nil } +// ErrCannotFetchAllLinks is returned as the last Result in the GC output +// channel when there was a error creating the marked set because of a +// problem when finding descendants. var ErrCannotFetchAllLinks = errors.New("garbage collection aborted: could not retrieve some links") +// ErrCannotDeleteSomeBlocks is returned when removing blocks marked for +// deletion fails as the last Result in GC output channel. var ErrCannotDeleteSomeBlocks = errors.New("garbage collection incomplete: could not delete some blocks") +// CannotFetchLinksError provides detailed information about which links +// could not be fetched and can appear as a Result in the GC output channel. type CannotFetchLinksError struct { Key *cid.Cid Err error } +// Error implements the error interface for this type with a useful +// message. func (e *CannotFetchLinksError) Error() string { return fmt.Sprintf("could not retrieve links for %s: %s", e.Key, e.Err) } +// CannotDeleteBlockError provides detailed information about which +// blocks could not be deleted and can appear as a Result in the GC output +// channel. type CannotDeleteBlockError struct { Key *cid.Cid Err error } +// Error implements the error interface for this type with a +// useful message. func (e *CannotDeleteBlockError) Error() string { return fmt.Sprintf("could not remove %s: %s", e.Key, e.Err) } diff --git a/pin/pin.go b/pin/pin.go index 07cda7cd0..ded36900a 100644 --- a/pin/pin.go +++ b/pin/pin.go @@ -1,4 +1,4 @@ -// package pin implements structures and methods to keep track of +// Package pin implements structures and methods to keep track of // which objects a user wants to keep stored locally. package pin @@ -43,8 +43,11 @@ const ( linkAll = "all" ) +// PinMode allows to specify different types of pin (recursive, direct etc.). +// See the Pin Modes constants for a full list. type PinMode int +// Pin Modes const ( // Recursive pins pin the target cids along with any reachable children. Recursive PinMode = iota @@ -65,6 +68,7 @@ const ( Any ) +// PinModeToString returns a human-readable name for the PinMode. func PinModeToString(mode PinMode) (string, bool) { m := map[PinMode]string{ Recursive: linkRecursive, @@ -78,6 +82,8 @@ func PinModeToString(mode PinMode) (string, bool) { return s, ok } +// StringToPinMode parses the result of PinModeToString() back to a PinMode. +// It returns a boolean which is set to false if the mode is unknown. func StringToPinMode(s string) (PinMode, bool) { m := map[string]PinMode{ linkRecursive: Recursive, @@ -92,6 +98,10 @@ func StringToPinMode(s string) (PinMode, bool) { return mode, ok } +// A Pinner provides the necessary methods to keep track of Nodes which are +// to be kept locally, according to a pin mode. In practice, a Pinner is in +// in charge of keeping the list of items from the local storage that should +// not be garbaged-collected. type Pinner interface { // IsPinned returns whether or not the given cid is pinned // and an explanation of why its pinned @@ -141,6 +151,10 @@ type Pinner interface { InternalPins() []*cid.Cid } +// Pinned represents CID which has been pinned with a pinning strategy. +// The Via field allows to identify the pinning parent of this CID, in the +// case that the item is not pinned directly (but rather pinned recursively +// by some ascendant). type Pinned struct { Key *cid.Cid Mode PinMode @@ -149,11 +163,7 @@ type Pinned struct { // Pinned returns whether or not the given cid is pinned func (p Pinned) Pinned() bool { - if p.Mode == NotPinned { - return false - } else { - return true - } + return p.Mode != NotPinned } // String Returns pin status as string @@ -240,6 +250,7 @@ func (p *pinner) Pin(ctx context.Context, node ipld.Node, recurse bool) error { return nil } +// ErrNotPinned is returned when trying to unpin items which are not pinned. var ErrNotPinned = fmt.Errorf("not pinned") // Unpin a given key @@ -258,9 +269,8 @@ func (p *pinner) Unpin(ctx context.Context, c *cid.Cid, recursive bool) error { if recursive { p.recursePin.Remove(c) return nil - } else { - return fmt.Errorf("%s is pinned recursively", c) } + return fmt.Errorf("%s is pinned recursively", c) case "direct": p.directPin.Remove(c) return nil