pstoreds

Documentation

Overview

Deprecated: The database-backed peerstore will be removed from go-libp2p in the future. Use the memory peerstore (pstoremem) instead. For more details see https://github.com/libp2p/go-libp2p/issues/2329 and https://github.com/libp2p/go-libp2p/issues/2355.

Index

• func NewAddrBook(ctx context.Context, store ds.Batching, opts Options) (ab *dsAddrBook, err error)
• func NewKeyBook(_ context.Context, store ds.Datastore, _ Options) (*dsKeyBook, error)
• func NewPeerMetadata(_ context.Context, store ds.Datastore, _ Options) (*dsPeerMetadata, error)
• func NewPeerstore(ctx context.Context, store ds.Batching, opts Options) (*pstoreds, error)
• func NewProtoBook(meta pstore.PeerMetadata, opts ...ProtoBookOption) (*dsProtoBook, error)
• type Options
  • func DefaultOpts() Options
• type ProtoBookOption
  • func WithMaxProtocols(num int) ProtoBookOption

Functions

func NewAddrBook

func NewAddrBook(ctx context.Context, store ds.Batching, opts Options) (ab *dsAddrBook, err error)

NewAddrBook initializes a new datastore-backed address book. It serves as a drop-in replacement for pstoremem (memory-backed peerstore), and works with any datastore implementing the ds.Batching interface.

Addresses and peer records are serialized into protobuf, storing one datastore entry per peer, along with metadata to control address expiration. To alleviate disk access and serde overhead, we internally use a read/write-through ARC cache, the size of which is adjustable via Options.CacheSize.

The user has a choice of two GC algorithms:

• lookahead GC: minimises the amount of full store traversals by maintaining a time-indexed list of entries that need to be visited within the period specified in Options.GCLookaheadInterval. This is useful in scenarios with considerable TTL variance, coupled with datastores whose native iterators return entries in lexicographical key order. Enable this mode by passing a value Options.GCLookaheadInterval > 0. Lookahead windows are jumpy, not sliding. Purges operate exclusively over the lookahead window with periodicity Options.GCPurgeInterval.

• full-purge GC (default): performs a full visit of the store with periodicity Options.GCPurgeInterval. Useful when the range of possible TTL values is small and the values themselves are also extreme, e.g. 10 minutes or permanent, popular values used in other libp2p modules. In this cited case, optimizing with lookahead windows makes little sense.

func NewKeyBook

func NewKeyBook(_ context.Context, store ds.Datastore, _ Options) (*dsKeyBook, error)

func NewPeerMetadata

func NewPeerMetadata(_ context.Context, store ds.Datastore, _ Options) (*dsPeerMetadata, error)

NewPeerMetadata creates a metadata store backed by a persistent db. It uses gob for serialisation.

See `init()` to learn which types are registered by default. Modules wishing to store values of other types will need to `gob.Register()` them explicitly, or else callers will receive runtime errors.

func NewPeerstore

func NewPeerstore(ctx context.Context, store ds.Batching, opts Options) (*pstoreds, error)

NewPeerstore creates a peerstore backed by the provided persistent datastore. It's the caller's responsibility to call RemovePeer to ensure that memory consumption of the peerstore doesn't grow unboundedly.

func NewProtoBook

func NewProtoBook(meta pstore.PeerMetadata, opts ...ProtoBookOption) (*dsProtoBook, error)

Types

type Options

type Options struct {
	// The size of the in-memory cache. A value of 0 or lower disables the cache.
	CacheSize uint

	// MaxProtocols is the maximum number of protocols we store for one peer.
	MaxProtocols int

	// Sweep interval to purge expired addresses from the datastore. If this is a zero value, GC will not run
	// automatically, but it'll be available on demand via explicit calls.
	GCPurgeInterval time.Duration

	// Interval to renew the GC lookahead window. If this is a zero value, lookahead will be disabled and we'll
	// traverse the entire datastore for every purge cycle.
	GCLookaheadInterval time.Duration

	// Initial delay before GC processes start. Intended to give the system breathing room to fully boot
	// before starting GC.
	GCInitialDelay time.Duration

	Clock clock
}

Configuration object for the peerstore.

func DefaultOpts

func DefaultOpts() Options

DefaultOpts returns the default options for a persistent peerstore, with the full-purge GC algorithm:

* Cache size: 1024. * MaxProtocols: 1024. * GC purge interval: 2 hours. * GC lookahead interval: disabled. * GC initial delay: 60 seconds.

type ProtoBookOption

type ProtoBookOption func(*dsProtoBook) error

func WithMaxProtocols

func WithMaxProtocols(num int) ProtoBookOption