water

Class DKV

java.lang.Object

water.DKV

public abstract class DKV
extends java.lang.Object

A Distributed Key/Value Store.

Functions to Get and Put Values into the K/V store by Key.

The Java Memory Model is observed for all operations. Reads/Gets will block until the data is available, and will pull from the local cache is possible.

Writes/Puts do not block directly, but take a Futures argument. Typically a Put requires some kind of coherency traffic and perhaps multiple network hops. The Futures argument can be used to tell when when a given Put (or a collection of them) has completed. Calls to Put without a Futures merely make one internally and block till completion.

Performance Concerns

Keys can be cached locally, or not. Cached reads take no more time than a NonBlockingHashMap lookup (typically a hundred nanos or so). Remote reads require the serialized POJO to pass over the network, plus a little bit of management logic; time is typically completely determined by network speeds and object size.

Local Puts (one where the Key is homed on this Node) update directly in the local K/V store, taking no more time than a NonBlockingHashMap write. Remote Puts will serialize and ship data over the wire, taking time related to object size and network speed.

Blocking for a Put to complete takes longer, requiring all invalidates to have happened and perhaps a response from the home node (multiple network-hop latencies); the invalidates and response are typically a single UDP packet, but must make a round-trip.

Puts to unrelated Keys can all proceed in parallel, and will typically be network bound, and can be blocked for in bulk by a single Futures argument.

Puts to the same Key will be serialized (the first Put will fully complete, including all invalidates, before a 2nd Put to the same Key from the same Node can proceed). Assuming no other Node does a Get on this Key, no invalidates will be required for the 2nd and later Puts and they will need only the single round-trip.

Note that this class works on one Key at a time, and does not understand composite Key structures (such as a Vec Key and all its related Chunk Keys - instead it serves as the building block for such structures.

Constructor Summary

Constructors

Constructor and Description
DKV()

Method Summary

Methods

Modifier and Type	Method and Description
static Value	DputIfMatch(Key key, Value val, Value old, Futures fs) Default caching call to DputIfMatch(Key,Value,Value,Futures,boolean)
static Value	DputIfMatch(Key key, Value val, Value old, Futures fs, boolean dontCache) Update the mapping for Key key, from Value old to Value val.
static Value	get(Key key) Return the Value mapped to Key key, or null if no mapping.
static Value	get(java.lang.String key_name) Return the Value mapped to Key formed by key_name, or null if no mapping.
static <T extends Iced> T	getGet(Key key)
static <T extends Iced> T	getGet(java.lang.String key)
static void	prefetch(Key key) Prefetch and cache the Value for Key key.
static void	prefetch(java.lang.String key_name) Prefetch and cache the Value for Key formed by key_name.
static Value	put(Keyed keyed) Make the mapping keyed._key -> keyed.
static Value	put(Keyed keyed, Futures fs) Make the mapping keyed._key -> keyed.
static Value	put(Key key, Iced v) Make the mapping key -> v.
static Value	put(Key key, Iced v, Futures fs) Make the mapping key -> v.
static Value	put(Key key, Iced v, Futures fs, boolean dontCache) Make the mapping key -> v.
static Value	put(Key key, Value val) Make the mapping key -> val.
static Value	put(Key key, Value val, Futures fs) Make the mapping key -> val.
static Value	put(Key key, Value val, Futures fs, boolean dontCache) Make the mapping key -> val.
static Value	remove(Key key) Remove any mapping for key.
static Value	remove(Key key, Futures fs) Remove any mapping for key.

Methods inherited from class java.lang.Object

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

Constructor Detail

DKV

public DKV()

Method Detail

put

public static Value put(Key key,
        Iced v)

Make the mapping key -> v. Blocking, caching.

put

public static Value put(Key key,
        Iced v,
        Futures fs)

Make the mapping key -> v. Caching.

put

public static Value put(Key key,
        Iced v,
        Futures fs,
        boolean dontCache)

Make the mapping key -> v.

put

public static Value put(Keyed keyed)

Make the mapping keyed._key -> keyed. Blocking, caching.

put

public static Value put(Keyed keyed,
        Futures fs)

Make the mapping keyed._key -> keyed. Caching.

put

public static Value put(Key key,
        Value val)

Make the mapping key -> val. Blocking, caching.

put

public static Value put(Key key,
        Value val,
        Futures fs)

Make the mapping key -> val. Caching.

put

public static Value put(Key key,
        Value val,
        Futures fs,
        boolean dontCache)

Make the mapping key -> val.

remove

public static Value remove(Key key)

Remove any mapping for key. Blocking.

remove

public static Value remove(Key key,
           Futures fs)

Remove any mapping for key.

DputIfMatch

public static Value DputIfMatch(Key key,
                Value val,
                Value old,
                Futures fs)

Default caching call to DputIfMatch(Key,Value,Value,Futures,boolean)

DputIfMatch

public static Value DputIfMatch(Key key,
                Value val,
                Value old,
                Futures fs,
                boolean dontCache)

Update the mapping for Key key, from Value old to Value val. Fails if the Key is not mapped to old, returning the Value it IS mapped to. Takes a required Futures, which can be used to note when the operation has completed globally. If the dontCache hint is passed in, the Value val is NOT cached locally, useful streaming a large dataset through and expecting most of the data to eventually be homed remotely.

Additionally, this operation locks the Cloud to the current size. No new Nodes may join after a Key is successfully entered into the DKV.

Returns:

The Value this Key used to be mapped to; if the returned Value.equals(old) then the update succeeded, else it failed.

getGet

public static <T extends Iced> T getGet(java.lang.String key)

getGet

public static <T extends Iced> T getGet(Key key)

get

public static Value get(Key key)

Return the Value mapped to Key key, or null if no mapping. Blocks till data available, always caches.

Returns:

The Value mapped to Key key, or null if no mapping.

prefetch

public static void prefetch(Key key)

Prefetch and cache the Value for Key key. Non-blocking.

get

public static Value get(java.lang.String key_name)

Return the Value mapped to Key formed by key_name, or null if no mapping. Blocks till data available, always caches.

Returns:

The Value mapped to Key formed by key_name, or null if no mapping.

prefetch

public static void prefetch(java.lang.String key_name)

Prefetch and cache the Value for Key formed by key_name. Non-blocking.