github-mirrors/elasticsearch
1
0
Fork 0
mirror of https://github.com/elastic/elasticsearch.git synced 2025-06-27 17:10:22 -04:00
Code Issues Projects Releases Packages Wiki Activity

Note in Javadocs that SubscribableListener fires once (#128131)

Browse source 
Spell out that multiple completions of a `SubscribableListener` race to
be chosen as the winner that is passed to subscribed listeners, such
that the subscribed listeners all fire at most once.
This commit is contained in:
David Turner 2025-05-27 15:33:07 +01:00 • committed by GitHub
parent 9e57f1471b
commit cdc74748dc
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 9 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

16
server/src/main/java/org/elasticsearch/action/support/SubscribableListener.java
View file

@ -32,15 +32,17 @@ import java.util.concurrent.ExecutionException;
import java.util.concurrent.Executor;
/**
* An {@link ActionListener} to which other {@link ActionListener} instances can subscribe, such that when this listener is
* completed it fans-out its result to the subscribed listeners.
* An {@link ActionListener} to which other {@link ActionListener} instances can subscribe, such that when this listener is completed it
* fans-out its result to the subscribed listeners.
* <p>
* If this listener is complete, {@link #addListener} completes the subscribing listener immediately
* with the result with which this listener was completed. Otherwise, the subscribing listener is retained
* and completed when this listener is completed.
* If this listener is complete, {@link #addListener} completes the subscribing listener immediately with the result with which this
* listener was completed. Otherwise, the subscribing listener is retained and completed when this listener is completed.
* <p>
* Exceptions are passed to subscribed listeners without modification. {@link ListenableActionFuture} and {@link ListenableFuture} are child
* classes that provide additional exception handling.
* Exceptions are passed to subscribed listeners without modification. {@link ListenableActionFuture} and {@link ListenableFuture} are
* subclasses which modify the exceptions passed to subscribed listeners.
* <p>
* If this listener is completed more than once then all results other than the first (whether successful or otherwise) are silently
* discarded. All subscribed listeners will be notified of the same result, exactly once, even if several completions occur concurrently.
* <p>
* A sequence of async steps can be chained together using a series of {@link SubscribableListener}s, similar to {@link CompletionStage}
* (without the {@code catch (Throwable t)}). Listeners can be created for each step, where the next step subscribes to the result of the