Package io.permazen.kv.mvcc

Interface AtomicKVStore

All Superinterfaces:
KVStore
All Known Implementing Classes:
AtomicArrayKVStore, AtomicKVDatabase, LevelDBAtomicKVStore, MemoryAtomicKVStore, MVStoreAtomicKVStore
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 readOnlySnapshot(), which returns a consistent point-in-time views of the KVStore. Atomic batch writes are available via apply(), which applies a set of mutations in an "all or none" fashion.

  • Method Details

    • 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 readOnlySnapshot()'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.

    • readOnlySnapshot

      CloseableKVStore readOnlySnapshot()
      Create a read-only "snapshot" view of this instance equal to its current state.

      The returned CloseableKVStore should be treated as read-only. It may not actually be read-only, but if it's not, then any changes should have no effect on this instance. The returned CloseableKVStore must be completely independent from this instance (subsequent changes to either one do not affect the other).

      The returned CloseableKVStore should be promply close()'d when no longer needed to release any underlying resources.

      Returns:
      read-only, snapshot view of this instance
      Throws:
      StaleKVTransactionException - if an underlying transaction is no longer usable
      RetryKVTransactionException - if an underlying transaction must be retried and is no longer usable
      IllegalStateException - if this instance is not start()ed

    • apply

      void apply(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:
      StaleKVTransactionException - if an underlying transaction is no longer usable
      RetryKVTransactionException - 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

    • apply

      default void apply(Mutations mutations)
      Apply all the given Mutations to this instance.

      Equivalent to: apply(mutations, false).

      Specified by:
      apply in interface KVStore
      Parameters:
      mutations - mutations to apply