Crate ipfs_sqlite_block_store[][src]

Expand description

IPFS sqlite block store

A block store for a rust implementation of ipfs.

Concepts

Aliases

An alias is a named pin of a root. When a root is aliased, none of the leaves of the dag pointed to by the root will be collected by gc. However, a root being aliased does not mean that the dag must be complete.

Temporary aliases

A temporary alias is an unnamed alias that is just for the purpose of protecting blocks from gc while a large tree is being constructed. While an alias maps a single name to a single root, a temporary alias can be assigned to an arbitary number of blocks before the dag is finished.

A temporary alias will be deleted as soon as the handle goes out of scope.

Garbage Collection (GC)

GC refers to the process of removing unpinned blocks. It runs only when the configured size targets are exceeded. Size targets contain both the total size of the store and the number of blocks.

GC will run incrementally, deleting blocks until the size targets are no longer exceeded. The order in which unpinned blocks will be deleted can be customized.

Caching

For unpinned blocks, it is possible to customize which blocks have the highest value using a CacheTracker. The default is to do nothing and has no performance overhead.

The most elaborate implemented strategy is to keep track of access times in a separate database, via the SqliteCacheTracker, which has a slight performance overhead.

The performance overhead of writing to an access tracking database on each block read can be mitigated by using the AsyncCacheTracker wrapper to perform the database writes on a different thread.

Usage

Blocking

For blocking usage, use BlockStore. This is the most low level interface.

Non-blocking

For non-blocking usage, use AsyncBlockStore. This is a wrapper that is meant to be used from async rust. In addition to wrapping most methods of BlockStore, it provides a method gc_loop to run gc continuously.

Major differences to the go-ipfs pinning concept

  • Pinning/aliasing a root does not require that the dag is complete
  • Aliases/named pins as opposed to unnamed and non-reference-counted pins
  • Temporary pins as a mechanism to keep blocks safe from gc while a tree is being constructed

Modules

cache

Structs

BlockStore
Config
SizeTargets

Size targets for a store. Gc of non-pinned blocks will start once one of the size targets is exceeded.

StoreStats
TempPin

a handle that contains a temporary pin

Enums

BlockStoreError
DbPath
Synchronous

Type Definitions

Result