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. Please see CPSubsystemConfig.setFailOnIndeterminateOperationState(boolean)

    Since:
    3.2
    See Also:
    IAtomicLong
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void alter​(IFunction<E,​E> function)
      Alters the currently stored reference by applying a function on it.
      E alterAndGet​(IFunction<E,​E> function)
      Alters the currently stored reference by applying a function on it and gets the result.
      java.util.concurrent.CompletionStage<E> alterAndGetAsync​(IFunction<E,​E> function)
      Alters the currently stored reference by applying a function on it and gets the result.
      java.util.concurrent.CompletionStage<java.lang.Void> alterAsync​(IFunction<E,​E> function)
      Alters the currently stored reference by applying a function on it.
      <R> R apply​(IFunction<E,​R> function)
      Applies a function on the value, the actual stored value will not change.
      <R> java.util.concurrent.CompletionStage<R> applyAsync​(IFunction<E,​R> function)
      Applies a function on the value, the actual stored value will not change.
      void clear()
      Clears the current stored reference.
      java.util.concurrent.CompletionStage<java.lang.Void> clearAsync()
      Clears the current stored reference.
      boolean compareAndSet​(E expect, E update)
      Atomically sets the value to the given updated value only if the current value == the expected value.
      java.util.concurrent.CompletionStage<java.lang.Boolean> compareAndSetAsync​(E expect, E update)
      Atomically sets the value to the given updated value only if the current value == the expected value.
      boolean contains​(E value)
      Checks if the reference contains the value.
      java.util.concurrent.CompletionStage<java.lang.Boolean> containsAsync​(E expected)
      Checks if the reference contains the value.
      E get()
      Gets the current value.
      E getAndAlter​(IFunction<E,​E> function)
      Alters the currently stored reference by applying a function on it on and gets the old value.
      java.util.concurrent.CompletionStage<E> getAndAlterAsync​(IFunction<E,​E> function)
      Alters the currently stored reference by applying a function on it on and gets the old value.
      E getAndSet​(E newValue)
      Gets the old value and sets the new value.
      java.util.concurrent.CompletionStage<E> getAndSetAsync​(E newValue)
      Gets the value and sets the new value.
      java.util.concurrent.CompletionStage<E> getAsync()
      Gets the current value.
      boolean isNull()
      Checks if the stored reference is null.
      java.util.concurrent.CompletionStage<java.lang.Boolean> isNullAsync()
      Checks if the stored reference is null.
      void set​(E newValue)
      Atomically sets the given value.
      java.util.concurrent.CompletionStage<java.lang.Void> setAsync​(E newValue)
      Atomically sets the given value.
    • Method Detail

      • 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:
        java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.IllegalArgumentException - if function is null
      • compareAndSetAsync

        java.util.concurrent.CompletionStage<java.lang.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

        java.util.concurrent.CompletionStage<E> getAsync()
        Gets the current value.
        Returns:
        the current value
      • setAsync

        java.util.concurrent.CompletionStage<java.lang.Void> setAsync​(E newValue)
        Atomically sets the given value.
        Parameters:
        newValue - the new value
      • getAndSetAsync

        java.util.concurrent.CompletionStage<E> getAndSetAsync​(E newValue)
        Gets the value and sets the new value.
        Parameters:
        newValue - the new value
        Returns:
        the old value
      • isNullAsync

        java.util.concurrent.CompletionStage<java.lang.Boolean> isNullAsync()
        Checks if the stored reference is null.
        Returns:
        true if null, false otherwise
      • clearAsync

        java.util.concurrent.CompletionStage<java.lang.Void> clearAsync()
        Clears the current stored reference.
      • containsAsync

        java.util.concurrent.CompletionStage<java.lang.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

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

        java.util.concurrent.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:
        java.lang.IllegalArgumentException - if function is null
      • getAndAlterAsync

        java.util.concurrent.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:
        java.lang.IllegalArgumentException - if function is null
      • applyAsync

        <R> java.util.concurrent.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:
        java.lang.IllegalArgumentException - if function is null