AtomicReference

class AtomicReference(context, group_id, service_name, proxy_name, object_name)

Bases: BaseCPProxy[BlockingAtomicReference], Generic[ElementType]

A distributed, highly available object reference with atomic operations.

AtomicReference offers linearizability during crash failures and network partitions. It is CP with respect to the CAP principle. If a network partition occurs, it remains available on at most one side of the partition.

The following are some considerations you need to know when you use AtomicReference:

• AtomicReference works based on the byte-content and not on the object-reference. If you use the compare_and_set() method, do not change the original value because its serialized content will then be different.

• All methods returning an object return a private copy. You can modify the private copy, but the rest of the world is shielded from your changes. If you want these changes to be visible to the rest of the world, you need to write the change back to the AtomicReference; but be careful about introducing a data-race.

• The in-memory format of an AtomicReference is binary. The receiving side does not need to have the class definition available unless it needs to be deserialized on the other side., e.g., because a method like alter() is executed. This deserialization is done for every call that needs to have the object instead of the binary content, so be careful with expensive object graphs that need to be deserialized.

• If you have an object with many fields or an object graph, and you only need to calculate some information or need a subset of fields, you can use the apply() method. With the apply() method, the whole object does not need to be sent over the line; only the information that is relevant is sent.

IAtomicReference does not offer exactly-once / effectively-once execution semantics. It goes with at-least-once execution semantics by default and can cause an API call to be committed multiple times in case of CP member failures. It can be tuned to offer at-most-once execution semantics. Please see fail-on-indeterminate-operation-state server-side setting.

compare_and_set(expect: Optional[ElementType], update: Optional[ElementType]) → Future[bool]

Atomically sets the value to the given updated value only if the current value is equal to the expected value.

Parameters:

• expect – The expected value.

• update – The new value.

Returns:

True if successful, or False if the actual value was not equal to the expected value.

get() → Future[Optional[ElementType]]

Gets the current value.

Returns:

The current value.

set(new_value: Optional[ElementType]) → Future[None]

Atomically sets the given value.

Parameters:

new_value – The new value.

get_and_set(new_value: Optional[ElementType]) → Future[Optional[ElementType]]

Gets the old value and sets the new value.

Parameters:

new_value – The new value.

Returns:

The old value.

is_none() → Future[bool]

Checks if the stored reference is None.

Returns:

True if the stored reference is None, False otherwise.

clear() → Future[None]

Clears the current stored reference, so it becomes None.

contains(value: Optional[ElementType]) → Future[bool]

Checks if the reference contains the value.

Parameters:

value – The value to check (is allowed to be None).

Returns:

True if the value is found, False otherwise.

alter(function: Any) → Future[None]

Alters the currently stored reference by applying a function on it.

Notes

function must be an instance of Hazelcast serializable type. It must have a counterpart registered in the server-side that implements the com.hazelcast.core.IFunction interface with the actual logic of the function to be applied.

Parameters:

function – The function that alters the currently stored reference.

alter_and_get(function: Any) → Future[Optional[ElementType]]

Alters the currently stored reference by applying a function on it and gets the result.

Notes

function must be an instance of Hazelcast serializable type. It must have a counterpart registered in the server-side that implements the com.hazelcast.core.IFunction interface with the actual logic of the function to be applied.

Parameters:

function – The function that alters the currently stored reference.

Returns:

The new value, the result of the applied function.

get_and_alter(function: Any) → Future[Optional[ElementType]]

Alters the currently stored reference by applying a function on it on and gets the old value.

Notes

function must be an instance of Hazelcast serializable type. It must have a counterpart registered in the server-side that implements the com.hazelcast.core.IFunction interface with the actual logic of the function to be applied.

Parameters:

function – The function that alters the currently stored reference.

Returns:

The old value, the value before the function is applied.

apply(function: Any) → Future[Optional[ElementType]]

Applies a function on the value, the actual stored value will not change.

Notes

function must be an instance of Hazelcast serializable type. It must have a counterpart registered in the server-side that implements the com.hazelcast.core.IFunction interface with the actual logic of the function to be applied.

Parameters:

function – The function applied on the currently stored reference.

Returns:

The result of the function application.

blocking() → BlockingAtomicReference[ElementType]

Returns a version of this proxy with only blocking method calls.

class BlockingAtomicReference(wrapped: AtomicReference[ElementType])

Bases: AtomicReference[ElementType]

compare_and_set(expect: Optional[ElementType], update: Optional[ElementType]) → bool

Atomically sets the value to the given updated value only if the current value is equal to the expected value.

Parameters:

• expect – The expected value.

• update – The new value.

Returns:

True if successful, or False if the actual value was not equal to the expected value.

get() → Optional[ElementType]

Gets the current value.

Returns:

The current value.

set(new_value: Optional[ElementType]) → None

Atomically sets the given value.

Parameters:

new_value – The new value.

get_and_set(new_value: Optional[ElementType]) → Optional[ElementType]

Gets the old value and sets the new value.

Parameters:

new_value – The new value.

Returns:

The old value.

is_none() → bool

Checks if the stored reference is None.

Returns:

True if the stored reference is None, False otherwise.

clear() → None

Clears the current stored reference, so it becomes None.

contains(value: Optional[ElementType]) → bool

Checks if the reference contains the value.

Parameters:

value – The value to check (is allowed to be None).

Returns:

True if the value is found, False otherwise.

alter(function: Any) → None

Alters the currently stored reference by applying a function on it.

Notes

function must be an instance of Hazelcast serializable type. It must have a counterpart registered in the server-side that implements the com.hazelcast.core.IFunction interface with the actual logic of the function to be applied.

Parameters:

function – The function that alters the currently stored reference.

alter_and_get(function: Any) → Optional[ElementType]

Alters the currently stored reference by applying a function on it and gets the result.

Notes

function must be an instance of Hazelcast serializable type. It must have a counterpart registered in the server-side that implements the com.hazelcast.core.IFunction interface with the actual logic of the function to be applied.

Parameters:

function – The function that alters the currently stored reference.

Returns:

The new value, the result of the applied function.

get_and_alter(function: Any) → Optional[ElementType]

Alters the currently stored reference by applying a function on it on and gets the old value.

Notes

function must be an instance of Hazelcast serializable type. It must have a counterpart registered in the server-side that implements the com.hazelcast.core.IFunction interface with the actual logic of the function to be applied.

Parameters:

function – The function that alters the currently stored reference.

Returns:

The old value, the value before the function is applied.

apply(function: Any) → Optional[ElementType]

Applies a function on the value, the actual stored value will not change.

Notes

function must be an instance of Hazelcast serializable type. It must have a counterpart registered in the server-side that implements the com.hazelcast.core.IFunction interface with the actual logic of the function to be applied.

Parameters:

function – The function applied on the currently stored reference.

Returns:

The result of the function application.

destroy() → None

Destroys this proxy.

blocking() → BlockingAtomicReference[ElementType]

Returns a version of this proxy with only blocking method calls.