AsynchronousAtom

java.lang.Object
- com.bluegosling.concurrent.atoms.AsynchronousAtom<T>

Type Parameters:

T - the type of the atom's value

All Implemented Interfaces:

Atom<T>
```
public class AsynchronousAtom<T>
extends Object
```
An atom that is mutated asynchronously using a thread pool. For a given atom, all mutations are applied sequentially. Multiple threads in a pool are used to process mutations on multiple such atoms. Since the actual update is applied asynchronously, mutation methods return future values, not immediate values.
If an error occurs while applying a change, the future that represents that change fails. Additionally, the atom will consult an error handler to decide what to do. There are three options:
1. Ignore: Processing continues. The failed mutation is ignored and subsequent mutations continue to be processed.
2. Block: Processing of subsequent mutations is stopped until the atom is explicitly resumed. While blocked, mutations are held in a queue instead of executed. Once the atom is resumed, the queue is processed using a thread pool thread, just as if they were submitted while the atom was processing normally.
3. Restart: The atom is restored to its most recent seeded value (set during construction or from a prior restart(Object, boolean)) and then immediately resumed. This is similar to ignoring the error, except that the value is re-seeded.
If a Transaction is in progress, then a mutation is not actually submitted to the thread pool until the transaction is committed. So, like TransactionalAtoms but unlike other types of atoms, mutations to asynchronous atoms can be rolled back. When a transaction is rolled back, all futures that correspond to rolled back asynchronous mutations are cancelled.
Ordering of operations cannot be guaranteed as asynchronous operations could be submitted and interleaved with those submitted from a given thread. Thus this form of atom is most useful when only commutative functions are applied to it.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`AsynchronousAtom.ErrorAction` One of the possible actions taken when an error occurs during a mutation operation.
`static interface`	`AsynchronousAtom.ErrorHandler<T>` Handles errors that occur during a mutation operation on an atom.

Nested classes/interfaces inherited from interface com.bluegosling.concurrent.atoms.Atom
Atom.Watcher<T>

Constructor Summary

Constructors
Constructor and Description
`AsynchronousAtom()` Constructs a new asynchronous atom with a `null` value and no validator.
`AsynchronousAtom(T value)` Constructs a new asynchronous atom with the specified value and no validator.
`AsynchronousAtom(T value, Predicate<? super T> validator)` Constructs a new asynchronous atom with the specified value and the specified validator.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`FluentFuture<T>`	`accumulateAndGet(T t, BiFunction<? super T,? super T,? extends T> function)` Submits a mutation that will combine the atom's value with the given value, using the given function, and set the atom's value to the result.
`boolean`	`addWatcher(Atom.Watcher<? super T> watcher)` Registers a watcher, which will receive notifications when the atom's value changes.
`T`	`get()` Retrieves the current value for this atom.
`FluentFuture<T>`	`getAndAccumulate(T t, BiFunction<? super T,? super T,? extends T> function)`
`FluentFuture<T>`	`getAndUpdate(Function<? super T,? extends T> function)` Applies a function to the atom's value.
`AsynchronousAtom.ErrorHandler<? super T>`	`getErrorHandler()` Returns the atom's error handler.
`FluentFuture<T>`	`getPending()` Returns a future that completes with the atom's value once all currently pending operations complete.
`int`	`getQueueLength()` Returns the number of queued mutation operations.
`Predicate<? super T>`	`getValidator()` Return the atom's validator, or `null` if there is no validator.
`boolean`	`isBlocked()` Returns true if the atom is blocked due to an earlier failure.
`protected void`	`notify(T oldValue, T newValue)` Notifies the atom's watchers that the value has changed.
`boolean`	`removeWatcher(Atom.Watcher<? super T> watcher)` Unregisters a watcher.
`boolean`	`restart()` Restarts mutation operations in a blocked atom.
`boolean`	`restart(T newSeed, boolean cancelPending)` Restarts mutation operations in a blocked atom with the given new seed value.
`void`	`resume()` Resumes mutation operations in a blocked atom.
`FluentFuture<T>`	`set(T newValue)` Submits a mutation that will set the atom to the specified value.
`void`	`setErrorHandler(AsynchronousAtom.ErrorHandler<? super T> errorHandler)` Sets the atom's error handler.
`FluentFuture<T>`	`updateAndGet(Function<? super T,? extends T> function)` Applies a function to the atom's value.
`protected void`	`validate(T value)` Validates the specified value.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - AsynchronousAtom
```
public AsynchronousAtom()
```
    Constructs a new asynchronous atom with a null value and no validator.
  - AsynchronousAtom
```
public AsynchronousAtom(T value)
```
    Constructs a new asynchronous atom with the specified value and no validator.
  - AsynchronousAtom
```
public AsynchronousAtom(T value,
                        Predicate<? super T> validator)
```
    Constructs a new asynchronous atom with the specified value and the specified validator.
- Method Detail
  - getErrorHandler
```
public AsynchronousAtom.ErrorHandler<? super T> getErrorHandler()
```
    Returns the atom's error handler. The default handler always ignores errors.
    
    Returns:
    
    this atom's error handler
  - setErrorHandler
```
public void setErrorHandler(AsynchronousAtom.ErrorHandler<? super T> errorHandler)
```
    Sets the atom's error handler.
    
    Parameters:
    
    errorHandler - the error handler that this atom should use
    
    Throws:
    
    NullPointerException - if the specified handler is null
  - isBlocked
```
public boolean isBlocked()
```
    Returns true if the atom is blocked due to an earlier failure.
    
    Returns:
    
    true if the atom is blocked
  - resume
```
public void resume()
```
    Resumes mutation operations in a blocked atom. If the atom is not blocked, this effectively does nothing. Upon becoming unblocked, any queued mutations will be processed in the order that they were submitted.
  - restart
```
public boolean restart()
```
    Restarts mutation operations in a blocked atom. Any queued operations will be applied after the atom is restarted. The atom will be reset to its seed value, which is the value used during construction of the atom or the seed value specified by the most recent successful restart(Object, boolean) operation.
    
    Returns:
    
    true if the atom was restarted or false if it was not because the atom wasn't actually blocked
  - restart
```
public boolean restart(T newSeed,
                       boolean cancelPending)
```
    Restarts mutation operations in a blocked atom with the given new seed value. The caller can indicate whether the restart operation should discard all pending mutations or if they should be retained and applied to the new restarted value.
    
    Parameters:
    
    newSeed - the new value with which to seed the restarted atom
    
    cancelPending - if true, any queued mutations will be discarded; otherwise, queued mutations will be applied to the new seeded value
    
    Returns:
    
    true if the atom was restarted or false if it was not because the atom wasn't actually blocked
    
    Throws:
    
    IllegalArgumentException - if the given restart value is invalid according to the atom's current validator
  - getQueueLength
```
public int getQueueLength()
```
    Returns the number of queued mutation operations. Operations are queued only when an error causes the atom to become blocked. Resuming the atom will drain the queue and process pending operations.
    
    Returns:
    
    the length of the queue of pending mutations
  - get
```
public T get()
```
    Retrieves the current value for this atom.
    This is a volatile read of the atom's value. There may be pending and/or concurrently executing operations that will change and/or are changing this value. To get the value of this atom after all such pending operations are complete, use getPending() instead.
    
    Returns:
    
    the current value for the atom
  - getPending
```
public FluentFuture<T> getPending()
```
    Returns a future that completes with the atom's value once all currently pending operations complete. If this atom is blocked or becomes blocked while processing currently pending operations, the returned future will not complete until the atom is unblocked. If the atom is unblocked via a restart() that cancels pending operations, then this future will be cancelled.
    
    Returns:
    
    a future that completes with the atom's value once all currently pending operations complete
  - set
```
public FluentFuture<T> set(T newValue)
```
    Submits a mutation that will set the atom to the specified value. The value will be validated immediately, before it is submitted.
    
    Parameters:
    
    newValue - the new value for the atom
    
    Returns:
    
    a future result that will be the atom's previous value at the time this mutation is applied
    
    Throws:
    
    IllegalArgumentException - if the specified value is not valid for this atom
  - updateAndGet
```
public FluentFuture<T> updateAndGet(Function<? super T,? extends T> function)
```
    Applies a function to the atom's value. The atom's new value will be the result of applying the specified function to the atom's current value. Watchers are notified when the value is changed.
    Since validation cannot be done immediately, validation failure manifests as a failed future. Depending on the atom's error handler, a validation failure could block subsequent mutations.
    
    Parameters:
    
    function - the function to apply
    
    Returns:
    
    a future result that will be the atom's new value after the function is applied
  - getAndUpdate
```
public FluentFuture<T> getAndUpdate(Function<? super T,? extends T> function)
```
    Applies a function to the atom's value. The atom's new value will be the result of applying the specified function to the atom's current value. Watchers are notified when the value is changed.
    Since validation cannot be done immediately, validation failure manifests as a failed future. Depending on the atom's error handler, a validation failure could block subsequent mutations.
    
    Parameters:
    
    function - the function to apply
    
    Returns:
    
    a future result that will be the atom's initial value (before function is applied) but that won't complete until after the function is applied
  - accumulateAndGet
```
public FluentFuture<T> accumulateAndGet(T t,
                                        BiFunction<? super T,? super T,? extends T> function)
```
    Submits a mutation that will combine the atom's value with the given value, using the given function, and set the atom's value to the result. Validation cannot be done immediately, so a validation failure manifests as a failed future. Depending on the atom's error handler, a validation failure could block subsequent mutations.
    
    Parameters:
    
    t - the value to combine
    
    function - the function to apply
    
    Returns:
    
    a future result that will be the atom's new value after the function is applied
  - getAndAccumulate
```
public FluentFuture<T> getAndAccumulate(T t,
                                        BiFunction<? super T,? super T,? extends T> function)
```
  - validate
```
protected void validate(T value)
```
    Validates the specified value. If this atom has a validator, it will be invoked and an exception is thrown if the value is not valid (e.g. the validator predicate returns false).
    
    Parameters:
    
    value - the value to validate
    
    Throws:
    
    IllegalArgumentException - if the specified value is invalid
  - getValidator
```
public Predicate<? super T> getValidator()
```
    Return the atom's validator, or null if there is no validator. The validator is a predicate that returns true when invoked on valid values for the item and false otherwise.
    
    Returns:
    
    the atom's validator
  - notify
```
protected void notify(T oldValue,
                      T newValue)
```
    Notifies the atom's watchers that the value has changed.
    
    Parameters:
    
    oldValue - the atom's old value
    
    newValue - the atom's new value
  - addWatcher
```
public boolean addWatcher(Atom.Watcher<? super T> watcher)
```
    Description copied from interface: Atom
    
    Registers a watcher, which will receive notifications when the atom's value changes.
    
    Specified by:
    
    addWatcher in interface Atom<T>
    
    Parameters:
    
    watcher - the watcher
    
    Returns:
    
    true if the watcher was registered; false if no change occurred because the watcher was already registered
  - removeWatcher
```
public boolean removeWatcher(Atom.Watcher<? super T> watcher)
```
    Description copied from interface: Atom
    
    Unregisters a watcher.
    
    Specified by:
    
    removeWatcher in interface Atom<T>
    
    Parameters:
    
    watcher - the watcher
    
    Returns:
    
    true if the watcher was unregistered; false if no change occurred because the watcher was never registered to begin with

Class AsynchronousAtom<T>

Nested Class Summary

Nested classes/interfaces inherited from interface com.bluegosling.concurrent.atoms.Atom

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

AsynchronousAtom

AsynchronousAtom

AsynchronousAtom

Method Detail

getErrorHandler

setErrorHandler

isBlocked

resume

restart

restart

getQueueLength

get

getPending

set

updateAndGet

getAndUpdate

accumulateAndGet

getAndAccumulate

validate

getValidator

notify

addWatcher

removeWatcher