reactor.core.publisher

Interface Sinks.Many<T>

All Superinterfaces:

Scannable

All Known Subinterfaces:

Sinks.ManyWithUpstream<T>

All Known Implementing Classes:

EmitterProcessor

Enclosing class:

Sinks

public static interface Sinks.Many<T>
extends Scannable

A base interface for standalone Sinks with Flux semantics.

The sink can be exposed to consuming code as a Flux via its asFlux() view.

Author:

Simon Baslé, Stephane Maldini

Nested Class Summary

Nested classes/interfaces inherited from interface reactor.core.Scannable

Scannable.Attr<T>

Field Summary

Fields inherited from interface reactor.core.Scannable

OPERATOR_NAME_UNRELATED_WORDS_PATTERN

Method Summary

Modifier and Type	Method and Description
Flux<T>	asFlux() Return a Flux view of this sink.
int	currentSubscriberCount() Get how many Subscribers are currently subscribed to the sink.
void	emitComplete(Sinks.EmitFailureHandler failureHandler) A simplified attempt at completing via the tryEmitComplete() API, generating an onComplete signal.
void	emitError(Throwable error, Sinks.EmitFailureHandler failureHandler) A simplified attempt at failing the sequence via the tryEmitError(Throwable) API, generating an onError signal.
void	emitNext(T t, Sinks.EmitFailureHandler failureHandler) A simplified attempt at emitting a non-null element via the tryEmitNext(Object) API, generating an onNext signal.
Sinks.EmitResult	tryEmitComplete() Try to terminate the sequence successfully, generating an onComplete signal.
Sinks.EmitResult	tryEmitError(Throwable error) Try to fail the sequence, generating an onError signal.
Sinks.EmitResult	tryEmitNext(T t) Try emitting a non-null element, generating an onNext signal.

Methods inherited from interface reactor.core.Scannable

actuals, from, inners, isScanAvailable, name, parents, scan, scanOrDefault, scanUnsafe, stepName, steps, tags

Method Detail

tryEmitNext

Sinks.EmitResult tryEmitNext(T t)

Try emitting a non-null element, generating an onNext signal. The result of the attempt is represented as an Sinks.EmitResult, which possibly indicates error cases.

See the list of failure Sinks.EmitResult in #emitNext(Object, EmitFailureHandler) javadoc for an example of how each of these can be dealt with, to decide if the emit API would be a good enough fit instead.

Might throw an unchecked exception as a last resort (eg. in case of a fatal error downstream which cannot be propagated to any asynchronous handler, a bubbling exception, ...).

Parameters:

t - the value to emit, not null

Returns:

an Sinks.EmitResult, which should be checked to distinguish different possible failures

See Also:

Subscriber.onNext(Object)

tryEmitComplete

Sinks.EmitResult tryEmitComplete()

Try to terminate the sequence successfully, generating an onComplete signal. The result of the attempt is represented as an Sinks.EmitResult, which possibly indicates error cases.

See the list of failure Sinks.EmitResult in #emitComplete(EmitFailureHandler) javadoc for an example of how each of these can be dealt with, to decide if the emit API would be a good enough fit instead.

Returns:

an Sinks.EmitResult, which should be checked to distinguish different possible failures

See Also:

Subscriber.onComplete()

tryEmitError

Sinks.EmitResult tryEmitError(Throwable error)

Try to fail the sequence, generating an onError signal. The result of the attempt is represented as an Sinks.EmitResult, which possibly indicates error cases.

See the list of failure Sinks.EmitResult in #emitError(Throwable, EmitFailureHandler) javadoc for an example of how each of these can be dealt with, to decide if the emit API would be a good enough fit instead.

Parameters:

error - the exception to signal, not null

Returns:

an Sinks.EmitResult, which should be checked to distinguish different possible failures

See Also:

Subscriber.onError(Throwable)

emitNext

void emitNext(T t,
              Sinks.EmitFailureHandler failureHandler)

A simplified attempt at emitting a non-null element via the tryEmitNext(Object) API, generating an onNext signal. If the result of the attempt is not a success, implementations SHOULD retry the tryEmitNext(Object) call IF the provided Sinks.EmitFailureHandler returns true. Otherwise, failures are dealt with in a predefined way that might depend on the actual sink implementation (see below for the vanilla reactor-core behavior).

Generally, tryEmitNext(Object) is preferable since it allows a custom handling of error cases, although this implies checking the returned Sinks.EmitResult and correctly acting on it. This API is intended as a good default for convenience.

When the Sinks.EmitResult is not a success, vanilla reactor-core operators have the following behavior:

• Sinks.EmitResult.FAIL_ZERO_SUBSCRIBER: no particular handling. should ideally discard the value but at that point there's no Subscriber from which to get a contextual discard handler.
• Sinks.EmitResult.FAIL_OVERFLOW: discard the value (Operators.onDiscard(Object, Context)) then call emitError(Throwable, Sinks.EmitFailureHandler) with a Exceptions.failWithOverflow(String) exception.
• Sinks.EmitResult.FAIL_CANCELLED: discard the value (Operators.onDiscard(Object, Context)).
• Sinks.EmitResult.FAIL_TERMINATED: drop the value (Operators.onNextDropped(Object, Context)).
• Sinks.EmitResult.FAIL_NON_SERIALIZED: throw an Sinks.EmissionException mentioning RS spec rule 1.3. Note that Sinks.unsafe() never trigger this result. It would be possible for an Sinks.EmitFailureHandler to busy-loop and optimistically wait for the contention to disappear to avoid this case for safe sinks...

Might throw an unchecked exception as a last resort (eg. in case of a fatal error downstream which cannot be propagated to any asynchronous handler, a bubbling exception, a Sinks.EmitResult.FAIL_NON_SERIALIZED as described above, ...).

Parameters:

t - the value to emit, not null

failureHandler - the failure handler that allows retrying failed Sinks.EmitResult.

Throws:

Sinks.EmissionException - on non-serialized access

See Also:

tryEmitNext(Object), Subscriber.onNext(Object)

emitComplete

void emitComplete(Sinks.EmitFailureHandler failureHandler)

A simplified attempt at completing via the tryEmitComplete() API, generating an onComplete signal. If the result of the attempt is not a success, implementations SHOULD retry the tryEmitComplete() call IF the provided Sinks.EmitFailureHandler returns true. Otherwise, failures are dealt with in a predefined way that might depend on the actual sink implementation (see below for the vanilla reactor-core behavior).

Generally, tryEmitComplete() is preferable since it allows a custom handling of error cases, although this implies checking the returned Sinks.EmitResult and correctly acting on it. This API is intended as a good default for convenience.

When the Sinks.EmitResult is not a success, vanilla reactor-core operators have the following behavior:

• Sinks.EmitResult.FAIL_OVERFLOW: irrelevant as onComplete is not driven by backpressure.
• Sinks.EmitResult.FAIL_ZERO_SUBSCRIBER: the completion can be ignored since nobody is listening. Note that most vanilla reactor sinks never trigger this result for onComplete, replaying the terminal signal to later subscribers instead (to the exception of Sinks.UnicastSpec.onBackpressureError()).
• Sinks.EmitResult.FAIL_CANCELLED: the completion can be ignored since nobody is interested.
• Sinks.EmitResult.FAIL_TERMINATED: the extra completion is basically ignored since there was a previous termination signal, but there is nothing interesting to log.
• Sinks.EmitResult.FAIL_NON_SERIALIZED: throw an Sinks.EmissionException mentioning RS spec rule 1.3. Note that Sinks.unsafe() never trigger this result. It would be possible for an Sinks.EmitFailureHandler to busy-loop and optimistically wait for the contention to disappear to avoid this case in safe sinks...

Might throw an unchecked exception as a last resort (eg. in case of a fatal error downstream which cannot be propagated to any asynchronous handler, a bubbling exception, a Sinks.EmitResult.FAIL_NON_SERIALIZED as described above, ...).

Parameters:

failureHandler - the failure handler that allows retrying failed Sinks.EmitResult.

Throws:

Sinks.EmissionException - on non-serialized access

See Also:

tryEmitComplete(), Subscriber.onComplete()

emitError

void emitError(Throwable error,
               Sinks.EmitFailureHandler failureHandler)

A simplified attempt at failing the sequence via the tryEmitError(Throwable) API, generating an onError signal. If the result of the attempt is not a success, implementations SHOULD retry the tryEmitError(Throwable) call IF the provided Sinks.EmitFailureHandler returns true. Otherwise, failures are dealt with in a predefined way that might depend on the actual sink implementation (see below for the vanilla reactor-core behavior).

Generally, tryEmitError(Throwable) is preferable since it allows a custom handling of error cases, although this implies checking the returned Sinks.EmitResult and correctly acting on it. This API is intended as a good default for convenience.

When the Sinks.EmitResult is not a success, vanilla reactor-core operators have the following behavior:

• Sinks.EmitResult.FAIL_OVERFLOW: irrelevant as onError is not driven by backpressure.
• Sinks.EmitResult.FAIL_ZERO_SUBSCRIBER: the error is ignored since nobody is listening. Note that most vanilla reactor sinks never trigger this result for onError, replaying the terminal signal to later subscribers instead (to the exception of Sinks.UnicastSpec.onBackpressureError()).
• Sinks.EmitResult.FAIL_CANCELLED: the error can be ignored since nobody is interested.
• Sinks.EmitResult.FAIL_TERMINATED: the error unexpectedly follows another terminal signal, so it is dropped via Operators.onErrorDropped(Throwable, Context).
• Sinks.EmitResult.FAIL_NON_SERIALIZED: throw an Sinks.EmissionException mentioning RS spec rule 1.3. Note that Sinks.unsafe() never trigger this result. It would be possible for an Sinks.EmitFailureHandler to busy-loop and optimistically wait for the contention to disappear to avoid this case in safe sinks...

Might throw an unchecked exception as a last resort (eg. in case of a fatal error downstream which cannot be propagated to any asynchronous handler, a bubbling exception, a Sinks.EmitResult.FAIL_NON_SERIALIZED as described above, ...).

Parameters:

error - the exception to signal, not null

failureHandler - the failure handler that allows retrying failed Sinks.EmitResult.

Throws:

Sinks.EmissionException - on non-serialized access

See Also:

tryEmitError(Throwable), Subscriber.onError(Throwable)

currentSubscriberCount

int currentSubscriberCount()

Get how many Subscribers are currently subscribed to the sink.

This is a best effort peek at the sink state, and a subsequent attempt at emitting to the sink might still return Sinks.EmitResult.FAIL_ZERO_SUBSCRIBER where relevant. (generally in tryEmitNext(Object)). Request (and lack thereof) isn't taken into account, all registered subscribers are counted.

Returns:

the number of subscribers at the time of invocation

asFlux

Flux<T> asFlux()

Return a Flux view of this sink. Every call returns the same instance.

Returns:

the Flux view associated to this Sinks.Many