io.permazen.kv.mvcc

Interface AtomicKVStore

All Superinterfaces:

KVStore

All Known Implementing Classes:

AtomicArrayKVStore, AtomicKVDatabase, LevelDBAtomicKVStore, RocksDBAtomicKVStore

public interface AtomicKVStore
extends KVStore

Extension of the KVStore interface for implementations that support atomic, batched reads and writes.

Atomic batch reads are available via snapshot(), which returns a consistent point-in-time views of the KVStore. Atomic batch writes are available via mutate(), which applies a set of mutations in an "all or none" fashion.

Method Summary

Modifier and Type	Method and Description
void	mutate(Mutations mutations, boolean sync) Apply a set of mutations to this instance atomically.
CloseableKVStore	snapshot() Acquire a read-only, snapshot view of this instance based on the current state.
void	start() Start this instance.
void	stop() Stop this instance.

Methods inherited from interface io.permazen.kv.KVStore

adjustCounter, apply, decodeCounter, encodeCounter, get, getAtLeast, getAtMost, getRange, getRange, getRange, put, remove, removeRange, removeRange

Method Detail

start

void start()

Start this instance. This method must be called prior to creating any transactions.

This method is idempotent: if this instance is already started, nothing happens.

Whether an instance that has been started and stopped can be restarted is implementation-dependent.

Throws:

IllegalStateException - if this instance is not properly configured

stop

void stop()

Stop this instance.

Any open snapshot()'s should be close()'d before invoking this method; the behavior of those that are not is undefined.

This method is idempotent: if this instance has not been started, or is already stopped, nothing happens.

snapshot

CloseableKVStore snapshot()

Acquire a read-only, snapshot view of this instance based on the current state.

The returned KVStore view should remain constant even if this instance is subsequently mutated.

Note: callers are required to close the returned instance when no longer in use.

Returns:

read-only, snapshot view of this instance

Throws:

StaleTransactionException - if an underlying transaction is no longer usable

RetryTransactionException - if an underlying transaction must be retried and is no longer usable

IllegalStateException - if this instance is not start()ed

mutate

void mutate(Mutations mutations,
            boolean sync)

Apply a set of mutations to this instance atomically.

If this method returns normally, all of the given mutations will have been applied. If this method returns abnormally, then none of the given mutations will have been applied.

In any case, other threads observing this instance will never see a partial application of the given mutations.

This method is required to apply the mutations in this order: removes, puts, adjusts.

If sync is true, the implementation must durably persist the changes before returning.

Parameters:

mutations - the mutations to apply

sync - if true, caller requires that the changes be durably persisted

Throws:

StaleTransactionException - if an underlying transaction is no longer usable

RetryTransactionException - if an underlying transaction must be retried and is no longer usable

UnsupportedOperationException - if sync is true and this implementation cannot guarantee durability

IllegalArgumentException - if mutations is null

IllegalStateException - if this instance is not start()ed