Interface IAtomicLong

All Superinterfaces:
DistributedObject

public interface IAtomicLong extends DistributedObject
IAtomicLong is a redundant and highly available distributed alternative to the AtomicLong.

Asynchronous variants of all methods have been introduced in version 3.7. Async methods immediately return a CompletionStage which can be used to chain further computation stages or can be converted to a CompletableFuture from which the operation's result can be obtained in a blocking manner. For example:

 CompletionStage<Long> stage = atomicLong.addAndGetAsync(13);
 stage.whenCompleteAsync((response, t) -> {
     if (t == null) {
         // do something with the result
     } 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).

IAtomicLong is accessed via CPSubsystem.getAtomicLong(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.

IAtomicLong 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)

See Also:
  • Method Details

    • getName

      String getName()
      Returns the name of this IAtomicLong instance.
      Specified by:
      getName in interface DistributedObject
      Returns:
      the name of this IAtomicLong instance
    • addAndGet

      long addAndGet(long delta)
      Atomically adds the given value to the current value.
      Parameters:
      delta - the value to add to the current value
      Returns:
      the updated value, the given value added to the current value
    • compareAndSet

      boolean compareAndSet(long expect, long 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.
    • decrementAndGet

      long decrementAndGet()
      Atomically decrements the current value by one.
      Returns:
      the updated value, the current value decremented by one
    • getAndDecrement

      long getAndDecrement()
      Atomically decrements the current value by one.
      Returns:
      the old value
    • get

      long get()
      Gets the current value.
      Returns:
      the current value
    • getAndAdd

      long getAndAdd(long delta)
      Atomically adds the given value to the current value.
      Parameters:
      delta - the value to add to the current value
      Returns:
      the old value before the add
    • getAndSet

      long getAndSet(long newValue)
      Atomically sets the given value and returns the old value.
      Parameters:
      newValue - the new value
      Returns:
      the old value
    • incrementAndGet

      long incrementAndGet()
      Atomically increments the current value by one.
      Returns:
      the updated value, the current value incremented by one
    • getAndIncrement

      long getAndIncrement()
      Atomically increments the current value by one.
      Returns:
      the old value
    • set

      void set(long newValue)
      Atomically sets the given value.
      Parameters:
      newValue - the new value
    • alter

      void alter(IFunction<Long,Long> function)
      Alters the currently stored value by applying a function on it.
      Parameters:
      function - the function applied to the currently stored value
      Throws:
      IllegalArgumentException - if function is null
      Since:
      3.2
    • alterAndGet

      long alterAndGet(IFunction<Long,Long> function)
      Alters the currently stored value by applying a function on it and gets the result.
      Parameters:
      function - the function applied to the currently stored value
      Returns:
      the new value
      Throws:
      IllegalArgumentException - if function is null
      Since:
      3.2
    • getAndAlter

      long getAndAlter(IFunction<Long,Long> function)
      Alters the currently stored value by applying a function on it on and gets the old value.
      Parameters:
      function - the function applied to the currently stored value
      Returns:
      the old value
      Throws:
      IllegalArgumentException - if function is null
      Since:
      3.2
    • apply

      <R> R apply(IFunction<Long,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 to the value, the value is not changed
      Returns:
      the result of the function application
      Throws:
      IllegalArgumentException - if function is null
      Since:
      3.2
    • addAndGetAsync

      CompletionStage<Long> addAndGetAsync(long delta)
      Atomically adds the given value to the current value.

      This method will dispatch a request and return immediately a CompletionStage.

      The operations result can be obtained in a blocking way, or a callback can be provided for execution upon completion, as demonstrated in the following examples:

       CompletionStage<Long> stage = atomicLong.addAndGetAsync(13);
       // do something else, then read the result
      
       // this method will block until the result is available
       Long result = stage.toCompletableFuture().get();
       
       CompletionStage<Long> stage = atomicLong.addAndGetAsync(13);
       stage.whenCompleteAsync((response, t) -> {
           if (t == null) {
               // do something with the result
           } else {
               // handle failure
           }
       });
       
      Parameters:
      delta - the value to add
      Returns:
      a CompletionStage bearing the response
      Since:
      3.7
    • compareAndSetAsync

      CompletionStage<Boolean> compareAndSetAsync(long expect, long update)
      Atomically sets the value to the given updated value only if the current value == the expected value.

      This method will dispatch a request and return immediately a CompletionStage.

      Parameters:
      expect - the expected value
      update - the new value
      Returns:
      an CompletionStage with value true if successful; or false if the actual value was not equal to the expected value
      Since:
      3.7
    • decrementAndGetAsync

      CompletionStage<Long> decrementAndGetAsync()
      Atomically decrements the current value by one.

      This method will dispatch a request and return immediately a CompletionStage.

      Returns:
      a CompletionStage with the updated value
      Since:
      3.7
    • getAndDecrementAsync

      CompletionStage<Long> getAndDecrementAsync()
      Atomically decrements the current value by one.

      This method will dispatch a request and return immediately a CompletionStage.

      Returns:
      a CompletionStage with the old value
      Since:
      4.1
    • getAsync

      CompletionStage<Long> getAsync()
      Gets the current value. This method will dispatch a request and return immediately a CompletionStage.
      Returns:
      a CompletionStage with the current value
      Since:
      3.7
    • getAndAddAsync

      CompletionStage<Long> getAndAddAsync(long delta)
      Atomically adds the given value to the current value.

      This method will dispatch a request and return immediately a CompletionStage.

      Parameters:
      delta - the value to add
      Returns:
      a CompletionStage with the old value before the addition
      Since:
      3.7
    • getAndSetAsync

      CompletionStage<Long> getAndSetAsync(long newValue)
      Atomically sets the given value and returns the old value.

      This method will dispatch a request and return immediately a CompletionStage.

      Parameters:
      newValue - the new value
      Returns:
      a CompletionStage with the old value
      Since:
      3.7
    • incrementAndGetAsync

      CompletionStage<Long> incrementAndGetAsync()
      Atomically increments the current value by one.

      This method will dispatch a request and return immediately a CompletionStage.

      Returns:
      a CompletionStage with the updated value
      Since:
      3.7
    • getAndIncrementAsync

      CompletionStage<Long> getAndIncrementAsync()
      Atomically increments the current value by one.

      This method will dispatch a request and return immediately a CompletionStage.

      Returns:
      a CompletionStage with the old value
      Since:
      3.7
    • setAsync

      CompletionStage<Void> setAsync(long newValue)
      Atomically sets the given value.

      This method will dispatch a request and return immediately a CompletionStage.

      Parameters:
      newValue - the new value
      Returns:
      a CompletionStage
      Since:
      3.7
    • alterAsync

      CompletionStage<Void> alterAsync(IFunction<Long,Long> function)
      Alters the currently stored value by applying a function on it.

      This method will dispatch a request and return immediately a CompletionStage.

      Parameters:
      function - the function
      Returns:
      a CompletionStage with the new value
      Throws:
      IllegalArgumentException - if function is null
      Since:
      3.7
    • alterAndGetAsync

      CompletionStage<Long> alterAndGetAsync(IFunction<Long,Long> function)
      Alters the currently stored value by applying a function on it and gets the result.

      This method will dispatch a request and return immediately a CompletionStage.

      Parameters:
      function - the function
      Returns:
      a CompletionStage with the new value
      Throws:
      IllegalArgumentException - if function is null
      Since:
      3.7
    • getAndAlterAsync

      CompletionStage<Long> getAndAlterAsync(IFunction<Long,Long> function)
      Alters the currently stored value by applying a function on it on and gets the old value.

      This method will dispatch a request and return immediately a CompletionStage.

      Parameters:
      function - the function
      Returns:
      a CompletionStage with the old value
      Throws:
      IllegalArgumentException - if function is null
      Since:
      3.7
    • applyAsync

      <R> CompletionStage<R> applyAsync(IFunction<Long,R> function)
      Applies a function on the value, the actual stored value will not change.

      This method will dispatch a request and return immediately a CompletionStage. For example:

       class IsOneFunction implements IFunction<Long, Boolean> {
           @Override
           public Boolean apply(Long input) {
               return input.equals(1L);
           }
       }
      
       CompletionStage<Boolean> stage = atomicLong.applyAsync(new IsOneFunction());
       stage.whenCompleteAsync((response, t) -> {
          if (t == null) {
              // do something with the response
          } else {
             // handle failure
          }
       });
       
      Type Parameters:
      R - the result type of the function
      Parameters:
      function - the function
      Returns:
      a CompletionStage with the result of the function application
      Throws:
      IllegalArgumentException - if function is null
      Since:
      3.7