Package com.hazelcast.cp

Interface IAtomicReference<E>

Type Parameters:
E - the type of object referred to by this reference
All Superinterfaces:
DistributedObject
public interface IAtomicReference<E> extends DistributedObject
IAtomicReference is a redundant and highly available distributed alternative to the AtomicReference.

Asynchronous variants have been introduced in version 3.7. Async methods immediately return a CompletionStage from which the operation's result can be obtained either in a blocking manner or by registering a callback to be executed upon completion. For example: 

 CompletionStage<E> future = atomicRef.getAsync();
 future.whenCompleteAsync((v, throwable) -> {
     if (throwable == null) {
         // do something with the old value returned by put operation
     } else {
         // handle failure
     }
 });

Actions supplied for dependent completions of default non-async methods and async methods without an explicit Executor argument are performed by the ForkJoinPool.commonPool() (unless it does not support a parallelism level of at least 2, in which case a new Thread is created per task).

IAtomicReference is accessed via CPSubsystem.getAtomicReference(String). It works on top of the Raft consensus algorithm. It 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.

IAtomicReference impl 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.

Since:
3.2
See Also:

  • Method Details

    • compareAndSet

      boolean compareAndSet(E expect, E update)
      Atomically sets the value to the given updated value only if the current value == 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

      E get()
      Gets the current value.
      Returns:
      the current value

    • set

      void set(E newValue)
      Atomically sets the given value.
      Parameters:
      newValue - the new value

    • getAndSet

      E getAndSet(E newValue)
      Gets the old value and sets the new value.
      Parameters:
      newValue - the new value
      Returns:
      the old value

    • isNull

      boolean isNull()
      Checks if the stored reference is null.
      Returns:
      true if null, false otherwise

    • clear

      void clear()
      Clears the current stored reference.

    • contains

      boolean contains(E value)
      Checks if the reference contains the value.
      Parameters:
      value - the value to check (is allowed to be null)
      Returns:
      true if the value is found, false otherwise

    • alter

      void alter(IFunction<E,E> function)
      Alters the currently stored reference by applying a function on it.
      Parameters:
      function - the function that alters the currently stored reference
      Throws:
      IllegalArgumentException - if function is null

    • alterAndGet

      E alterAndGet(IFunction<E,E> function)
      Alters the currently stored reference by applying a function on it and gets the result.
      Parameters:
      function - the function that alters the currently stored reference
      Returns:
      the new value, the result of the applied function
      Throws:
      IllegalArgumentException - if function is null

    • getAndAlter

      E getAndAlter(IFunction<E,E> function)
      Alters the currently stored reference by applying a function on it on and gets the old value.
      Parameters:
      function - the function that alters the currently stored reference
      Returns:
      the old value, the value before the function is applied
      Throws:
      IllegalArgumentException - if function is null

    • apply

      <R> R apply(IFunction<E,R> function)
      Applies a function on the value, the actual stored value will not change.
      Type Parameters:
      R - the result type of the function
      Parameters:
      function - the function applied on the value, the stored value does not change
      Returns:
      the result of the function application
      Throws:
      IllegalArgumentException - if function is null

    • compareAndSetAsync

      CompletionStage<Boolean> compareAndSetAsync(E expect, E update)
      Atomically sets the value to the given updated value only if the current value == 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

    • getAsync

      CompletionStage<E> getAsync()
      Gets the current value.
      Returns:
      the current value

    • setAsync

      CompletionStage<Void> setAsync(E newValue)
      Atomically sets the given value.
      Parameters:
      newValue - the new value

    • getAndSetAsync

      CompletionStage<E> getAndSetAsync(E newValue)
      Gets the value and sets the new value.
      Parameters:
      newValue - the new value
      Returns:
      the old value

    • isNullAsync

      CompletionStage<Boolean> isNullAsync()
      Checks if the stored reference is null.
      Returns:
      true if null, false otherwise

    • clearAsync

      CompletionStage<Void> clearAsync()
      Clears the current stored reference.

    • containsAsync

      CompletionStage<Boolean> containsAsync(E expected)
      Checks if the reference contains the value.
      Parameters:
      expected - the value to check (is allowed to be null)
      Returns:
      true if the value is found, false otherwise

    • alterAsync

      CompletionStage<Void> alterAsync(IFunction<E,E> function)
      Alters the currently stored reference by applying a function on it.
      Parameters:
      function - the function
      Throws:
      IllegalArgumentException - if function is null

    • alterAndGetAsync

      CompletionStage<E> alterAndGetAsync(IFunction<E,E> function)
      Alters the currently stored reference by applying a function on it and gets the result.
      Parameters:
      function - the function
      Returns:
      the new value
      Throws:
      IllegalArgumentException - if function is null

    • getAndAlterAsync

      CompletionStage<E> getAndAlterAsync(IFunction<E,E> function)
      Alters the currently stored reference by applying a function on it on and gets the old value.
      Parameters:
      function - the function
      Returns:
      the old value
      Throws:
      IllegalArgumentException - if function is null

    • applyAsync

      <R> CompletionStage<R> applyAsync(IFunction<E,R> function)
      Applies a function on the value, the actual stored value will not change.
      Type Parameters:
      R - the result type of the function
      Parameters:
      function - the function
      Returns:
      the result of the function application
      Throws:
      IllegalArgumentException - if function is null