org.apache.cassandra.db.context

Class CounterContext

java.lang.Object

org.apache.cassandra.db.context.CounterContext

All Implemented Interfaces:

IContext

public class CounterContext
extends java.lang.Object
implements IContext

An implementation of a partitioned counter context. A context is primarily a list of tuples (counter id, clock, count) -- called shard in the following. But with some shard are flagged as delta (with special resolution rules in merge()). The data structure has two parts: a) a header containing the lists of "delta" (a list of references to the second parts) b) a list of shard -- (counter id, logical clock, count) tuples -- (the so-called 'body' below) The exact layout is: | header | body | context : |--|------|----------| ^ ^ | list of indices in the body list (2*#elt bytes) #elt in rest of header (2 bytes) The body layout being: body: |----|----|----|----|----|----|.... ^ ^ ^ ^ ^ ^ | | count_1 | | count_2 | clock_1 | clock_2 counterid_1 counterid_2 The rules when merging two shard with the same counterid are: - delta + delta = sum counts (and logical clock) - delta + other = keep the delta one - other + other = keep the shard with highest logical clock For a detailed description of the meaning of a delta and why the merging rules work this way, see CASSANDRA-1938 - specifically the 1938_discussion attachment.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CounterContext.ContextState Helper class to work on contexts (works by iterating over them).

Nested classes/interfaces inherited from interface org.apache.cassandra.db.context.IContext

IContext.ContextRelationship

Constructor Summary

Constructors

Constructor and Description
CounterContext()

Method Summary

Methods

Modifier and Type	Method and Description
java.nio.ByteBuffer	clearAllDelta(java.nio.ByteBuffer context) Remove all the delta of a context (i.e, set an empty header).
java.nio.ByteBuffer	computeOldShardMerger(java.nio.ByteBuffer context, java.util.List<CounterId.CounterIdRecord> oldIds, long mergeBefore) Compute a new context such that if applied to context yields the same total but with old local counter ids nulified and there content merged to the current localCounterId.
java.nio.ByteBuffer	create(CounterId id, long clock, long value, boolean isDelta)
java.nio.ByteBuffer	create(long value, Allocator allocator) Creates an initial counter context with an initial value for the local node.
IContext.ContextRelationship	diff(java.nio.ByteBuffer left, java.nio.ByteBuffer right) Determine the count relationship between two contexts.
boolean	hasCounterId(java.nio.ByteBuffer context, CounterId id) Checks whether the provided context has a count for the provided CounterId.
static CounterContext	instance()
java.nio.ByteBuffer	markDeltaToBeCleared(java.nio.ByteBuffer context) Mark context to delete delta afterward.
java.nio.ByteBuffer	merge(java.nio.ByteBuffer left, java.nio.ByteBuffer right, Allocator allocator) Return a context w/ an aggregated count for each counter id.
java.nio.ByteBuffer	removeOldShards(java.nio.ByteBuffer context, int gcBefore) Remove shards that have been canceled through computeOldShardMerger since a time older than gcBefore.
java.lang.String	toString(java.nio.ByteBuffer context) Human-readable String from context.
long	total(java.nio.ByteBuffer context) Returns the aggregated count across all counter ids.
void	updateDigest(java.security.MessageDigest message, java.nio.ByteBuffer context) Update a MessageDigest with the content of a context.
void	validateContext(java.nio.ByteBuffer context)

Methods inherited from class java.lang.Object

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

Constructor Detail

CounterContext

public CounterContext()

Method Detail

instance

public static CounterContext instance()

create

public java.nio.ByteBuffer create(long value,
                         Allocator allocator)

Creates an initial counter context with an initial value for the local node.

Parameters:

value - the value for this initial update

allocator -

Returns:

an empty counter context.

create

public java.nio.ByteBuffer create(CounterId id,
                         long clock,
                         long value,
                         boolean isDelta)

diff

public IContext.ContextRelationship diff(java.nio.ByteBuffer left,
                                java.nio.ByteBuffer right)

Determine the count relationship between two contexts. EQUAL: Equal set of nodes and every count is equal. GREATER_THAN: Superset of nodes and every count is equal or greater than its corollary. LESS_THAN: Subset of nodes and every count is equal or less than its corollary. DISJOINT: Node sets are not equal and/or counts are not all greater or less than. Strategy: compare node logical clocks (like a version vector).

Specified by:

diff in interface IContext

Parameters:

left - counter context.

right - counter context.

Returns:

the ContextRelationship between the contexts.

merge

public java.nio.ByteBuffer merge(java.nio.ByteBuffer left,
                        java.nio.ByteBuffer right,
                        Allocator allocator)

Return a context w/ an aggregated count for each counter id.

Specified by:

merge in interface IContext

Parameters:

left - counter context.

right - counter context.

allocator - An allocator for the merged value.

toString

public java.lang.String toString(java.nio.ByteBuffer context)

Human-readable String from context.

Specified by:

toString in interface IContext

Parameters:

context - counter context.

Returns:

a human-readable String of the context.

total

public long total(java.nio.ByteBuffer context)

Returns the aggregated count across all counter ids.

Parameters:

context - a counter context

Returns:

the aggregated count represented by context

markDeltaToBeCleared

public java.nio.ByteBuffer markDeltaToBeCleared(java.nio.ByteBuffer context)

Mark context to delete delta afterward. Marking is done by multiply #elt by -1 to preserve header length and #elt count in order to clear all delta later.

Parameters:

context - a counter context

Returns:

context that marked to delete delta

clearAllDelta

public java.nio.ByteBuffer clearAllDelta(java.nio.ByteBuffer context)

Remove all the delta of a context (i.e, set an empty header).

Parameters:

context - a counter context

Returns:

a version of context where no count are a delta.

validateContext

public void validateContext(java.nio.ByteBuffer context)
                     throws MarshalException

Throws:

MarshalException

updateDigest

public void updateDigest(java.security.MessageDigest message,
                java.nio.ByteBuffer context)

Update a MessageDigest with the content of a context. Note that this skips the header entirely since the header information has local meaning only, while digests a meant for comparison across nodes. This means in particular that we always have: updateDigest(ctx) == updateDigest(clearAllDelta(ctx))

hasCounterId

public boolean hasCounterId(java.nio.ByteBuffer context,
                   CounterId id)

Checks whether the provided context has a count for the provided CounterId. TODO: since the context is sorted, we could implement a binary search. This is however not called in any critical path and contexts will be fairly small so it doesn't matter much.

computeOldShardMerger

public java.nio.ByteBuffer computeOldShardMerger(java.nio.ByteBuffer context,
                                        java.util.List<CounterId.CounterIdRecord> oldIds,
                                        long mergeBefore)

Compute a new context such that if applied to context yields the same total but with old local counter ids nulified and there content merged to the current localCounterId.

removeOldShards

public java.nio.ByteBuffer removeOldShards(java.nio.ByteBuffer context,
                                  int gcBefore)

Remove shards that have been canceled through computeOldShardMerger since a time older than gcBefore. Used by compaction to strip context of unecessary information, shrinking them.