io.permazen.kv.mvcc

Class MutableView

java.lang.Object

io.permazen.kv.AbstractKVStore

io.permazen.kv.mvcc.MutableView

All Implemented Interfaces:

KVStore, Cloneable

Direct Known Subclasses:

ReadWriteSpannerView

@ThreadSafe
public class MutableView
extends AbstractKVStore
implements Cloneable

Provides a mutable view of an underlying, read-only KVStore.

Instances intercept all operations to the underlying KVStore, recording mutations in a Writes instance instead of applying them to the KVStore. Instances then provide a view of the mutated KVStore based those mutations. Mutations that overwrite previous mutations are consolidated.

Unlike writes, reads are passed through to the underlying KVStore, except where they intersect a previous write.

In all cases, the underlying KVStore is never modified.

Instances ensure that counter adjustment mutations never overlap put or remove mutations.

Read Tracking

During construction, instances may be configured to record all keys read into a Reads object (this is typically used for MVCC conflict detection). When reads are being tracked, tracking may temporarily be paused and resumed via setReadTrackingPaused(boolean). Read tracking may be permanently disabled (and any recorded reads discarded) via disableReadTracking().

Instances are thread safe; however, directly accessing the associated Reads or Writes is not thread safe without first locking the containing instance.

Constructor Summary

Constructors

Constructor and Description
MutableView(KVStore kv) Constructor.
MutableView(KVStore kv, Reads reads, Writes writes) Constructor using caller-provided Reads (optional) and Writes.

Method Summary

Modifier and Type	Method and Description
void	adjustCounter(byte[] key, long amount) Adjust the counter at the given key by the given amount.
void	apply(Mutations mutations) Apply all the given Mutations to this instance.
MutableView	clone() Clone this instance.
long	decodeCounter(byte[] bytes) Decode a counter value previously encoded by encodeCounter().
void	disableReadTracking() Permanently disable read tracking and discard the Reads associated with this instance.
byte[]	encodeCounter(long value) Encode a counter value into a byte[] value suitable for use with decodeCounter() and/or adjustCounter().
byte[]	get(byte[] key) Get the value associated with the given key, if any.
KVStore	getKVStore() Get the underlying KVStore associated with this instance.
CloseableIterator<KVPair>	getRange(byte[] minKey, byte[] maxKey, boolean reverse) Iterate the key/value pairs in the specified range.
Reads	getReads() Get the Reads associated with this instance.
Writes	getWrites() Get the Writes associated with this instance.
void	put(byte[] key, byte[] value) Set the value associated with the given key.
void	remove(byte[] key) Remove the key/value pair with the given key, if it exists.
void	removeRange(byte[] minKey, byte[] maxKey) Remove all key/value pairs whose keys are in a given range.
void	setKVStore(KVStore kv) Swap out the underlying KVStore associated with this instance.
void	setReadOnly() Configure this instance as read-only.
void	setReadTrackingPaused(boolean readTrackingPaused) Temporarily disable or re-enable read tracking.
String	toString()

Methods inherited from class io.permazen.kv.AbstractKVStore

getAtLeast, getAtMost

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface io.permazen.kv.KVStore

getRange, getRange, removeRange

Constructor Detail

MutableView

public MutableView(KVStore kv)

Constructor.

The instance will use a new, empty Reads instance for read tracking.

Parameters:

kv - underlying KVStore

Throws:

IllegalArgumentException - if kv is null

MutableView

public MutableView(KVStore kv,
                   Reads reads,
                   Writes writes)

Constructor using caller-provided Reads (optional) and Writes.

Parameters:

kv - underlying KVStore

reads - recorded reads, or null for none

writes - recorded writes

Throws:

IllegalArgumentException - if kv is null

IllegalArgumentException - if writes is null

Method Detail

getKVStore

public KVStore getKVStore()

Get the underlying KVStore associated with this instance.

Returns:

underlying KVStore

setKVStore

public void setKVStore(KVStore kv)

Swap out the underlying KVStore associated with this instance.

Note: the new KVStore should have a consistent encoding of counter values as the previous KVStore, otherwise a concurrent thread may read previously written counter values back incorrectly.

Parameters:

kv - new underlying KVStore

Throws:

IllegalArgumentException - if kv is null

getReads

public Reads getReads()

Get the Reads associated with this instance.

This includes all keys explicitly or implicitly read by calls to get(), getAtLeast(), getAtMost(), and getRange().

The returned object should only be accessed while synchronized on this instance.

Returns:

reads recorded, or null if this instance is not configured to record reads

getWrites

public Writes getWrites()

Get the Writes associated with this instance.

The returned object should only be accessed while synchronized on this instance.

Returns:

writes recorded

disableReadTracking

public void disableReadTracking()

Permanently disable read tracking and discard the Reads associated with this instance.

Can be used to save some memory when read tracking information is no longer needed.

setReadTrackingPaused

public void setReadTrackingPaused(boolean readTrackingPaused)

Temporarily disable or re-enable read tracking.

Ignored if there is no (longer any) associated Reads instance.

Parameters:

readTrackingPaused - true to disable read tracking, false to enable

setReadOnly

public void setReadOnly()

Configure this instance as read-only.

Any subsequent invocations of put(), remove(), removeRange(), or adjustCounter() will result in an IllegalStateException.

get

public byte[] get(byte[] key)

Description copied from interface: KVStore

Get the value associated with the given key, if any.

Modifications to the returned byte[] array do not affect this instance.

Specified by:

get in interface KVStore

Overrides:

get in class AbstractKVStore

Parameters:

key - key

Returns:

value associated with key, or null if not found

getRange

public CloseableIterator<KVPair> getRange(byte[] minKey,
                                          byte[] maxKey,
                                          boolean reverse)

Description copied from interface: KVStore

Iterate the key/value pairs in the specified range. The returned Iterator's remove() method must be supported and should have the same effect as invoking remove() on the corresponding key.

If keys starting with 0xff are not supported by this instance, and minKey starts with 0xff, then this method returns an empty iteration.

If keys starting with 0xff are not supported by this instance, and maxKey starts with 0xff, then this method behaves as if maxKey were null.

The returned Iterator must not throw ConcurrentModificationException; however, whether or not a "live" Iterator reflects any modifications made after its creation is implementation dependent. Implementations that do make post-creation updates visible in the Iterator, even if the update occurs after some delay, must preserve the order in which the modifications actually occurred.

The returned Iterator itself is not guaranteed to be thread safe.

Invokers of this method are encouraged to close() the returned iterators, though this is not required for correct behavior.

Modifications to the returned KVPair key and value byte[] arrays do not affect this instance.

Specified by:

getRange in interface KVStore

Parameters:

minKey - minimum key (inclusive), or null for no minimum (start at the smallest key)

maxKey - maximum key (exclusive), or null for no maximum (end at the largest key)

reverse - true to return key/value pairs in reverse order (i.e., keys descending)

Returns:

iteration of key/value pairs in the range minKey (inclusive) to maxKey (exclusive)

put

public void put(byte[] key,
                byte[] value)

Description copied from interface: KVStore

Set the value associated with the given key.

Specified by:

put in interface KVStore

Overrides:

put in class AbstractKVStore

Parameters:

key - key

value - value

remove

public void remove(byte[] key)

Description copied from interface: KVStore

Remove the key/value pair with the given key, if it exists.

Specified by:

remove in interface KVStore

Overrides:

remove in class AbstractKVStore

Parameters:

key - key

removeRange

public void removeRange(byte[] minKey,
                        byte[] maxKey)

Description copied from interface: KVStore

Remove all key/value pairs whose keys are in a given range.

The minKey must be less than or equal to maxKey; if they equal (and not null) then nothing happens; if they are both null then all entries are deleted.

If keys starting with 0xff are not supported by this instance, then:

• If minKey starts with 0xff, then no change occurs
• If maxKey starts with 0xff, then this method behaves as if maxKey were null

Specified by:

removeRange in interface KVStore

Overrides:

removeRange in class AbstractKVStore

Parameters:

minKey - minimum key (inclusive), or null for no minimum

maxKey - maximum key (exclusive), or null for no maximum

encodeCounter

public byte[] encodeCounter(long value)

Description copied from interface: KVStore

Encode a counter value into a byte[] value suitable for use with decodeCounter() and/or adjustCounter().

Specified by:

encodeCounter in interface KVStore

Overrides:

encodeCounter in class AbstractKVStore

Parameters:

value - desired counter value

Returns:

encoded counter value

decodeCounter

public long decodeCounter(byte[] bytes)

Description copied from interface: KVStore

Decode a counter value previously encoded by encodeCounter().

Specified by:

decodeCounter in interface KVStore

Overrides:

decodeCounter in class AbstractKVStore

Parameters:

bytes - encoded counter value

Returns:

decoded counter value

adjustCounter

public void adjustCounter(byte[] key,
                          long amount)

Description copied from interface: KVStore

Adjust the counter at the given key by the given amount.

Ideally this operation should behave in a lock-free manner, so that concurrent transactions can invoke it without conflict. However, when lock-free behavior occurs (if at all) depends on the implementation.

If there is no value associated with key, or key's value is not a valid counter encoding as would be acceptable to decodeCounter(), then how this operation affects key's value is undefined.

Specified by:

adjustCounter in interface KVStore

Overrides:

adjustCounter in class AbstractKVStore

Parameters:

key - key

amount - amount to adjust counter value by

apply

public void apply(Mutations mutations)

Description copied from interface: KVStore

Apply all the given Mutations to this instance.

Mutations are always to be applied in this order: removes, puts, counter adjustments.

The implementation in KVStore simply iterates over the individual changes and applies them via remove() (for removals of a single key), removeRange(), put(), and/or adjustCounter(). Implementations that can process batch updates more efficiently are encouraged to override this method.

Specified by:

apply in interface KVStore

Parameters:

mutations - mutations to apply

clone

public MutableView clone()

Clone this instance.

The clone will have the same underlying KVStore, but its own Reads and Writes, which will themselves be cloned from this instance's copies.

Overrides:

clone in class Object

Returns:

clone of this instance

toString

public String toString()

Overrides:

toString in class Object