From ce57a766876b1251b27578aa4c06c31d4deb867d Mon Sep 17 00:00:00 2001 From: Jeromy Date: Sun, 21 Jan 2018 11:31:47 -0800 Subject: [PATCH] interface docs for pinner License: MIT Signed-off-by: Jeromy --- pin/pin.go | 33 +++++++++++++++++++++++++++++++-- 1 file changed, 31 insertions(+), 2 deletions(-) diff --git a/pin/pin.go b/pin/pin.go index dc2eee7f2..4d66408ef 100644 --- a/pin/pin.go +++ b/pin/pin.go @@ -46,11 +46,22 @@ const ( type PinMode int const ( + // Recursive pins pin the target cids along with any reachable children. Recursive PinMode = iota + + // Direct pins pin just the target cid. Direct + + // Indirect pins are cids who have some ancestor pinned recursively. Indirect + + // Internal pins are cids used to keep the internal state of the pinner. Internal + + // NotPinned NotPinned + + // Any refers to any pinned cid Any ) @@ -82,10 +93,20 @@ func StringToPinMode(s string) (PinMode, bool) { } type Pinner interface { + // IsPinned returns whether or not the given cid is pinned + // and an explanation of why its pinned IsPinned(*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. IsPinnedWithType(*cid.Cid, PinMode) (string, bool, error) - Pin(context.Context, node.Node, bool) error - Unpin(context.Context, *cid.Cid, bool) error + + // Pin the given node, optionally recursively. + Pin(ctx context.Context, node node.Node, recursive bool) error + + // Unpin the given cid. If recursive is true, removes either a recursive or + // a direct pin. If recursive is false, only removes a direct pin. + Unpin(ctx context.Context, cid *cid.Cid, recursive bool) error // Update updates a recursive pin from one cid to another // this is more efficient than simply pinning the new one and unpinning the @@ -106,9 +127,17 @@ type Pinner interface { // be successful. RemovePinWithMode(*cid.Cid, PinMode) + // Flush writes the pin state to the backing datastore Flush() error + + // DirectKeys returns all directly pinned cids DirectKeys() []*cid.Cid + + // DirectKeys returns all recursively pinned cids RecursiveKeys() []*cid.Cid + + // InternalPins returns all cids kept pinned for the internal state of the + // pinner InternalPins() []*cid.Cid }