Class LinearizableAtomicReference<T>

java.lang.Object

com.loomcache.server.cp.LinearizableAtomicReference<T>

Type Parameters:

T - the type of the reference

public final class LinearizableAtomicReference<T>
extends Object

Linearizable distributed atomic reference with strong consistency via Raft.

Purpose: Provides linearizable atomic access to an object reference. All operations go through Raft consensus to ensure global ordering and consistency.

Operations:

• get() — read current reference
• set(value) — write new reference
• compareAndSet(expect, update) — atomic CAS operation
• getAndSet(newValue) — return current, then set new value
• isNull() — check if current reference is null
• clear() — set reference to null

Consistency Guarantee: All operations are linearizable. The reference is globally visible across all cluster members. In case of network partitions, operations may block until the cluster recovers.

Thread Safety: This class is thread-safe. Multiple threads can safely perform concurrent operations without external synchronization.

Generic Type: The type parameter T allows type-safe access to the reference. The actual value is stored in an underlying atomic reference and replicated via Raft.

Since:

1.0

Constructor Summary

Constructors

Constructor	Description
LinearizableAtomicReference(String refName, @Nullable T initialValue)	Creates a new LinearizableAtomicReference with the given name and initial value.

Method Summary

Modifier and Type	Method	Description
@Nullable Object	applyCommand(byte[] command)	Applies a Raft-committed command to the local state machine.
boolean	applyCommittedCompareAndSet(@Nullable T expect, @Nullable T update)	Applies an already-committed CP protocol CAS operation to local state.
@Nullable Object	applyCommittedSet(@Nullable T newValue)	Applies an already-committed CP protocol set operation to local state.
void	clear()	Clears the reference by setting it to null.
boolean	compareAndSet(@Nullable T expect, @Nullable T update)	Atomically sets the reference to the given value if the current reference equals the expected value.
@Nullable T	get()	Gets the current reference value.
@Nullable T	getAndSet(@Nullable T newValue)	Atomically gets the current reference and sets a new value.
boolean	isNull()	Checks if the current reference is null.
void	set(@Nullable T newValue)	Sets the reference to the given value.
void	setKryoSerializer(KryoSerializer kryoSerializer)	Provide the shared KryoSerializer used to encode and decode atomic reference values on the Raft command/apply paths.
void	setRaftNode(@Nullable RaftNodeApi raftNode)	Sets the Raft node for cluster-mode consensus replication.
void	setReadRaftNode(@Nullable RaftNodeApi readRaftNode)
String	toString()	Returns a string representation of this atomic reference.

Methods inherited from class Object

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

Constructor Details

LinearizableAtomicReference

public LinearizableAtomicReference(String refName,
 @Nullable T initialValue)

Creates a new LinearizableAtomicReference with the given name and initial value.

Parameters:

refName - the name of this atomic reference (must not be null or empty)

initialValue - the initial value (can be null)

Throws:

NullPointerException - if refName is null

IllegalArgumentException - if refName is empty

Method Details

setRaftNode

public void setRaftNode(@Nullable RaftNodeApi raftNode)

Sets the Raft node for cluster-mode consensus replication.

Parameters:

raftNode - the RaftNode to route operations through (may be null for standalone mode)

setReadRaftNode

public void setReadRaftNode(@Nullable RaftNodeApi readRaftNode)

setKryoSerializer

public void setKryoSerializer(KryoSerializer kryoSerializer)

Provide the shared KryoSerializer used to encode and decode atomic reference values on the Raft command/apply paths. Callers that want to store custom value types must register them on this serializer before submitting any write.

get

public @Nullable T get()

Gets the current reference value.

In cluster mode, issues a linearizable read via Raft to ensure the local state machine is caught up before returning the value.

Returns:

the current reference value, or null if not set

set

public void set(@Nullable T newValue)

Sets the reference to the given value.

In cluster mode, replicated via Raft consensus.

Parameters:

newValue - the new reference value (can be null)

compareAndSet

public boolean compareAndSet(@Nullable T expect,
 @Nullable T update)

Atomically sets the reference to the given value if the current reference equals the expected value.

Uses value equality (via Object.equals(Object)) for comparison, not reference equality. This means two distinct objects that are equals() will match. Null is considered equal only to null.

Parameters:

expect - the expected current reference (compared via equals)

update - the new reference to set if the expectation is met

Returns:

true if the update succeeded, false if the current reference did not equal expect

getAndSet

public @Nullable T getAndSet(@Nullable T newValue)

Atomically gets the current reference and sets a new value.

Parameters:

newValue - the new reference to set

Returns:

the previous reference value

isNull

public boolean isNull()

Checks if the current reference is null.

Returns:

true if the current reference is null

clear

public void clear()

Clears the reference by setting it to null.

applyCommittedSet

public @Nullable Object applyCommittedSet(@Nullable T newValue)

Applies an already-committed CP protocol set operation to local state.

This bypasses the cluster-write guard because the caller has already sequenced the mutation through the enclosing CacheNode Raft log.

applyCommittedCompareAndSet

public boolean applyCommittedCompareAndSet(@Nullable T expect,
 @Nullable T update)

Applies an already-committed CP protocol CAS operation to local state.

This bypasses the cluster-write guard because the caller has already sequenced the mutation through the enclosing CacheNode Raft log.

applyCommand

public @Nullable Object applyCommand(byte[] command)

Applies a Raft-committed command to the local state machine. Called by the Raft state-machine apply callback when a log entry is committed.

Parameters:

command - the serialized command bytes

Returns:

the result of the operation

toString

public String toString()

Returns a string representation of this atomic reference.

Overrides:

toString in class Object

Returns:

string representation