KVStore

lightning::util::persist

Trait KVStore 

Source 
pub trait KVStore {
    // Required methods
    fn read(
        &self,
        primary_namespace: &str,
        secondary_namespace: &str,
        key: &str,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<u8>, Error>> + Send + 'static>>;
    fn write(
        &self,
        primary_namespace: &str,
        secondary_namespace: &str,
        key: &str,
        buf: Vec<u8>,
    ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'static>>;
    fn remove(
        &self,
        primary_namespace: &str,
        secondary_namespace: &str,
        key: &str,
    ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'static>>;
    fn list(
        &self,
        primary_namespace: &str,
        secondary_namespace: &str,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<String>, Error>> + Send + 'static>>;
}
Expand description

Provides an interface that allows storage and retrieval of persisted values that are associated with given keys.

In order to avoid collisions the key space is segmented based on the given primary_namespaces and secondary_namespaces. Implementations of this trait are free to handle them in different ways, as long as per-namespace key uniqueness is asserted.

Keys and namespaces are required to be valid ASCII strings in the range of KVSTORE_NAMESPACE_KEY_ALPHABET and no longer than KVSTORE_NAMESPACE_KEY_MAX_LEN. Empty primary namespaces and secondary namespaces ("") are assumed to be a valid, however, if primary_namespace is empty, secondary_namespace is required to be empty, too. This means that concerns should always be separated by primary namespace first, before secondary namespaces are used. While the number of primary namespaces will be relatively small and is determined at compile time, there may be many secondary namespaces per primary namespace. Note that per-namespace uniqueness needs to also hold for keys and namespaces in any given namespace, i.e., conflicts between keys and equally named primary namespaces/secondary namespaces must be avoided.

Note: Users migrating custom persistence backends from the pre-v0.0.117 KVStorePersister interface can use a concatenation of [{primary_namespace}/[{secondary_namespace}/]]{key} to recover a key compatible with the data model previously assumed by KVStorePersister::persist.

Required Methods§

Source

fn read( &self, primary_namespace: &str, secondary_namespace: &str, key: &str, ) -> Pin<Box<dyn Future<Output = Result<Vec<u8>, Error>> + Send + 'static>>

Returns the data stored for the given primary_namespace, secondary_namespace, and key.

Returns an ErrorKind::NotFound if the given key could not be found in the given primary_namespace and secondary_namespace.

Source

fn write( &self, primary_namespace: &str, secondary_namespace: &str, key: &str, buf: Vec<u8>, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'static>>

Persists the given data under the given key.

The order of multiple writes to the same key needs to be retained while persisting asynchronously. In other words, if two writes to the same key occur, the state (as seen by Self::read) must either see the first write then the second, or only ever the second, no matter when the futures complete (and must always contain the second write once the second future completes). The state should never contain the first write after the second write’s future completes, nor should it contain the second write, then contain the first write at any point thereafter (even if the second write’s future hasn’t yet completed).

One way to ensure this requirement is met is by assigning a version number to each write before returning the future, and then during asynchronous execution, ensuring that the writes are executed in the correct order.

Note that no ordering requirements exist for writes to different keys.

Will create the given primary_namespace and secondary_namespace if not already present in the store.

Source

fn remove( &self, primary_namespace: &str, secondary_namespace: &str, key: &str, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'static>>

Removes any data that had previously been persisted under the given key.

Returns successfully if no data will be stored for the given primary_namespace, secondary_namespace, and key, independently of whether it was present before its invokation or not.

Source

fn list( &self, primary_namespace: &str, secondary_namespace: &str, ) -> Pin<Box<dyn Future<Output = Result<Vec<String>, Error>> + Send + 'static>>

Returns a list of keys that are stored under the given secondary_namespace in primary_namespace.

Returns the keys in arbitrary order, so users requiring a particular order need to sort the returned keys. Returns an empty list if primary_namespace or secondary_namespace is unknown.

Implementors§