From ee7a8f3482db87c824e01a68c388799b3651bce4 Mon Sep 17 00:00:00 2001 From: Hector Sanjuan Date: Tue, 13 Feb 2018 12:53:20 +0100 Subject: [PATCH 1/2] 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 From d7cd0591651583bf3af47ebbee59596f44368cfd Mon Sep 17 00:00:00 2001 From: Hector Sanjuan Date: Tue, 13 Feb 2018 13:00:48 +0100 Subject: [PATCH 2/2] Doc: golint: remove stuttering in pin package License: MIT Signed-off-by: Hector Sanjuan --- core/commands/pin.go | 2 +- pin/pin.go | 36 ++++++++++++++++++------------------ 2 files changed, 19 insertions(+), 19 deletions(-) diff --git a/core/commands/pin.go b/core/commands/pin.go index d6ef73979..078013462 100644 --- a/core/commands/pin.go +++ b/core/commands/pin.go @@ -494,7 +494,7 @@ type RefKeyList struct { func pinLsKeys(args []string, typeStr string, ctx context.Context, n *core.IpfsNode) (map[string]RefKeyObject, error) { - mode, ok := pin.StringToPinMode(typeStr) + mode, ok := pin.StringToMode(typeStr) if !ok { return nil, fmt.Errorf("invalid pin mode '%s'", typeStr) } diff --git a/pin/pin.go b/pin/pin.go index ded36900a..685f8cf65 100644 --- a/pin/pin.go +++ b/pin/pin.go @@ -43,14 +43,14 @@ const ( linkAll = "all" ) -// PinMode allows to specify different types of pin (recursive, direct etc.). +// Mode allows to specify different types of pin (recursive, direct etc.). // See the Pin Modes constants for a full list. -type PinMode int +type Mode int // Pin Modes const ( // Recursive pins pin the target cids along with any reachable children. - Recursive PinMode = iota + Recursive Mode = iota // Direct pins pin just the target cid. Direct @@ -68,9 +68,9 @@ const ( Any ) -// PinModeToString returns a human-readable name for the PinMode. -func PinModeToString(mode PinMode) (string, bool) { - m := map[PinMode]string{ +// ModeToString returns a human-readable name for the Mode. +func ModeToString(mode Mode) (string, bool) { + m := map[Mode]string{ Recursive: linkRecursive, Direct: linkDirect, Indirect: linkIndirect, @@ -82,10 +82,10 @@ func PinModeToString(mode PinMode) (string, bool) { return s, ok } -// StringToPinMode parses the result of PinModeToString() back to a PinMode. +// StringToMode parses the result of ModeToString() back to a Mode. // It returns a boolean which is set to false if the mode is unknown. -func StringToPinMode(s string) (PinMode, bool) { - m := map[string]PinMode{ +func StringToMode(s string) (Mode, bool) { + m := map[string]Mode{ linkRecursive: Recursive, linkDirect: Direct, linkIndirect: Indirect, @@ -109,7 +109,7 @@ type Pinner interface { // IsPinnedWithType returns whether or not the given cid is pinned with the // given pin type, as well as returning the type of pin its pinned with. - IsPinnedWithType(*cid.Cid, PinMode) (string, bool, error) + IsPinnedWithType(*cid.Cid, Mode) (string, bool, error) // Pin the given node, optionally recursively. Pin(ctx context.Context, node ipld.Node, recursive bool) error @@ -130,12 +130,12 @@ type Pinner interface { // PinWithMode is for manually editing the pin structure. Use with // care! If used improperly, garbage collection may not be // successful. - PinWithMode(*cid.Cid, PinMode) + PinWithMode(*cid.Cid, Mode) // RemovePinWithMode is for manually editing the pin structure. // Use with care! If used improperly, garbage collection may not // be successful. - RemovePinWithMode(*cid.Cid, PinMode) + RemovePinWithMode(*cid.Cid, Mode) // Flush writes the pin state to the backing datastore Flush() error @@ -157,7 +157,7 @@ type Pinner interface { // by some ascendant). type Pinned struct { Key *cid.Cid - Mode PinMode + Mode Mode Via *cid.Cid } @@ -174,7 +174,7 @@ func (p Pinned) String() string { case Indirect: return fmt.Sprintf("pinned via %s", p.Via) default: - modeStr, _ := PinModeToString(p.Mode) + modeStr, _ := ModeToString(p.Mode) return fmt.Sprintf("pinned: %s", modeStr) } } @@ -293,7 +293,7 @@ func (p *pinner) IsPinned(c *cid.Cid) (string, bool, error) { // IsPinnedWithType returns whether or not the given cid is pinned with the // given pin type, as well as returning the type of pin its pinned with. -func (p *pinner) IsPinnedWithType(c *cid.Cid, mode PinMode) (string, bool, error) { +func (p *pinner) IsPinnedWithType(c *cid.Cid, mode Mode) (string, bool, error) { p.lock.RLock() defer p.lock.RUnlock() return p.isPinnedWithType(c, mode) @@ -301,7 +301,7 @@ func (p *pinner) IsPinnedWithType(c *cid.Cid, mode PinMode) (string, bool, error // isPinnedWithType is the implementation of IsPinnedWithType that does not lock. // intended for use by other pinned methods that already take locks -func (p *pinner) isPinnedWithType(c *cid.Cid, mode PinMode) (string, bool, error) { +func (p *pinner) isPinnedWithType(c *cid.Cid, mode Mode) (string, bool, error) { switch mode { case Any, Direct, Indirect, Recursive, Internal: default: @@ -414,7 +414,7 @@ func (p *pinner) CheckIfPinned(cids ...*cid.Cid) ([]Pinned, error) { // RemovePinWithMode is for manually editing the pin structure. // Use with care! If used improperly, garbage collection may not // be successful. -func (p *pinner) RemovePinWithMode(c *cid.Cid, mode PinMode) { +func (p *pinner) RemovePinWithMode(c *cid.Cid, mode Mode) { p.lock.Lock() defer p.lock.Unlock() switch mode { @@ -594,7 +594,7 @@ func (p *pinner) InternalPins() []*cid.Cid { // PinWithMode allows the user to have fine grained control over pin // counts -func (p *pinner) PinWithMode(c *cid.Cid, mode PinMode) { +func (p *pinner) PinWithMode(c *cid.Cid, mode Mode) { p.lock.Lock() defer p.lock.Unlock() switch mode {