public abstract class GraphStageLogic
extends java.lang.Object
GraphStage
. Roughly speaking, a subclass of GraphStageLogic
is a
collection of the following parts:
* A set of InHandler
and OutHandler
instances and their assignments to the Inlet
s and Outlet
s
of the enclosing GraphStage
* Possible mutable state, accessible from the InHandler
and OutHandler
callbacks, but not from anywhere
else (as such access would not be thread-safe)
* The lifecycle hooks preStart()
and postStop()
* Methods for performing stream processing actions, like pulling or pushing elements
The stage logic is completed once all its input and output ports have been closed. This can be changed by
setting setKeepGoing
to true.
The postStop
lifecycle hook on the logic itself is called once all ports are closed. This is the only tear down
callback that is guaranteed to happen, if the actor system or the materializer is terminated the handlers may never
see any callbacks to onUpstreamFailure
, onUpstreamFinish
or onDownstreamFinish
. Therefore stage resource
cleanup should always be done in postStop
.
Modifier and Type | Class and Description |
---|---|
static class |
GraphStageLogic.ConditionalTerminateInput
Input handler that terminates the state upon receiving completion if the
given condition holds at that time.
|
static class |
GraphStageLogic.ConditionalTerminateOutput
Output handler that terminates the state upon receiving completion if the
given condition holds at that time.
|
static class |
GraphStageLogic.EagerTerminateInput$
Input handler that terminates the stage upon receiving completion.
|
static class |
GraphStageLogic.EagerTerminateOutput$
Output handler that terminates the stage upon cancellation.
|
static class |
GraphStageLogic.IgnoreTerminateInput$
Input handler that does not terminate the stage upon receiving completion.
|
static class |
GraphStageLogic.IgnoreTerminateOutput$
Output handler that does not terminate the stage upon cancellation.
|
static class |
GraphStageLogic.StageActor
Minimal actor to work with other actors and watch them in a synchronous ways
|
static class |
GraphStageLogic.StageActorRef$ |
static class |
GraphStageLogic.StageActorRefNotInitializedException |
static class |
GraphStageLogic.StageActorRefNotInitializedException$ |
class |
GraphStageLogic.SubSinkInlet<T>
INTERNAL API
|
class |
GraphStageLogic.SubSourceOutlet<T>
INTERNAL API
|
static class |
GraphStageLogic.TotallyIgnorantInput$
Input handler that does not terminate the stage upon receiving completion
nor failure.
|
Constructor and Description |
---|
GraphStageLogic(int inCount,
int outCount) |
GraphStageLogic(Shape shape) |
Modifier and Type | Method and Description |
---|---|
protected void |
abortEmitting(Outlet<?> out)
Abort outstanding (suspended) emissions for the given outlet, if there are any.
|
protected void |
abortReading(Inlet<?> in)
Abort outstanding (suspended) reading for the given inlet, if there is any.
|
protected void |
afterPostStop()
INTERNAL API
|
protected void |
beforePreStart()
INTERNAL API
|
protected <T> void |
cancel(Inlet<T> in)
Requests to stop receiving events from a given input port.
|
protected <T> void |
complete(Outlet<T> out)
Signals that there will be no more elements emitted on the given port.
|
void |
completeStage()
Automatically invokes
cancel() or complete() on all the input or output ports that have been called,
then marks the stage as stopped. |
protected InHandler |
conditionalTerminateInput(scala.Function0<java.lang.Object> predicate)
Input handler that terminates the state upon receiving completion if the
given condition holds at that time.
|
protected OutHandler |
conditionalTerminateOutput(scala.Function0<java.lang.Object> predicate)
Output handler that terminates the state upon receiving completion if the
given condition holds at that time.
|
protected <T> AsyncCallback<T> |
createAsyncCallback(Procedure<T> handler)
Java API: Obtain a callback object that can be used asynchronously to re-enter the
current
GraphStage with an asynchronous notification. |
protected InHandler |
eagerTerminateInput()
Input handler that terminates the stage upon receiving completion.
|
protected OutHandler |
eagerTerminateOutput()
Output handler that terminates the stage upon cancellation.
|
protected <T> void |
emit(Outlet<T> out,
T elem)
Emit an element through the given outlet, suspending execution if necessary.
|
protected <T> void |
emit(Outlet<T> out,
T elem,
Effect andThen) |
protected <T> void |
emit(Outlet<T> out,
T elem,
scala.Function0<scala.runtime.BoxedUnit> andThen)
Emit an element through the given outlet and continue with the given thunk
afterwards, suspending execution if necessary.
|
protected <T> void |
emitMultiple(Outlet<T> out,
scala.collection.immutable.Iterable<T> elems)
Emit a sequence of elements through the given outlet, suspending execution if necessary.
|
protected <T> void |
emitMultiple(Outlet<T> out,
scala.collection.immutable.Iterable<T> elems,
scala.Function0<scala.runtime.BoxedUnit> andThen)
Emit a sequence of elements through the given outlet and continue with the given thunk
afterwards, suspending execution if necessary.
|
protected <T> void |
emitMultiple(Outlet<T> out,
java.util.Iterator<T> elems)
Java API
|
protected <T> void |
emitMultiple(Outlet<T> out,
scala.collection.Iterator<T> elems)
Emit a sequence of elements through the given outlet, suspending execution if necessary.
|
protected <T> void |
emitMultiple(Outlet<T> out,
java.util.Iterator<T> elems,
Effect andThen)
Java API
|
protected <T> void |
emitMultiple(Outlet<T> out,
scala.collection.Iterator<T> elems,
scala.Function0<scala.runtime.BoxedUnit> andThen)
Emit a sequence of elements through the given outlet and continue with the given thunk
afterwards, suspending execution if necessary.
|
protected <T> void |
fail(Outlet<T> out,
java.lang.Throwable ex)
Signals failure through the given port.
|
void |
failStage(java.lang.Throwable ex)
Automatically invokes
cancel() or fail() on all the input or output ports that have been called,
then marks the stage as stopped. |
<T> AsyncCallback<T> |
getAsyncCallback(scala.Function1<T,scala.runtime.BoxedUnit> handler)
Obtain a callback object that can be used asynchronously to re-enter the
current
GraphStage with an asynchronous notification. |
protected InHandler |
getHandler(Inlet<?> in)
Retrieves the current callback for the events on the given
Inlet |
protected OutHandler |
getHandler(Outlet<?> out)
Retrieves the current callback for the events on the given
Outlet |
protected GraphStageLogic.StageActor |
getStageActor(scala.Function1<scala.Tuple2<ActorRef,java.lang.Object>,scala.runtime.BoxedUnit> receive)
Initialize a
StageActorRef which can be used to interact with from the outside world "as-if" an Actor . |
protected <T> T |
grab(Inlet<T> in)
Once the callback
InHandler.onPush() for an input port has been invoked, the element that has been pushed
can be retrieved via this method. |
java.lang.Object[] |
handlers()
INTERNAL API
|
protected <T> boolean |
hasBeenPulled(Inlet<T> in)
Indicates whether there is already a pending pull for the given input port.
|
protected InHandler |
ignoreTerminateInput()
Input handler that does not terminate the stage upon receiving completion.
|
protected OutHandler |
ignoreTerminateOutput()
Output handler that does not terminate the stage upon cancellation.
|
int |
inCount() |
GraphInterpreter |
interpreter()
INTERNAL API
|
protected <T> boolean |
isAvailable(Inlet<T> in)
Indicates whether there is an element waiting at the given input port.
|
<T> boolean |
isAvailable(Outlet<T> out)
Return true if the given output port is ready to be pushed.
|
protected <T> boolean |
isClosed(Inlet<T> in)
Indicates whether the port has been closed.
|
protected <T> boolean |
isClosed(Outlet<T> out)
Indicates whether the port has been closed.
|
protected Materializer |
materializer()
The
Materializer that has set this GraphStage in motion. |
int |
outCount() |
protected <Out,In extends Out> |
passAlong(Inlet<In> from,
Outlet<Out> to,
boolean doFinish,
boolean doFail,
boolean doPull)
Install a handler on the given inlet that emits received elements on the
given outlet before pulling for more data.
|
GraphInterpreter.Connection[] |
portToConn()
INTERNAL API
|
void |
postStop()
Invoked after processing of external events stopped because the stage is about to stop or fail.
|
void |
preStart()
Invoked before any external events are processed, at the startup of the stage.
|
protected <T> void |
pull(Inlet<T> in)
Requests an element on the given port.
|
protected <T> void |
push(Outlet<T> out,
T elem)
Emits an element through the given output port.
|
protected <T> void |
read(Inlet<T> in,
scala.Function1<T,scala.runtime.BoxedUnit> andThen,
scala.Function0<scala.runtime.BoxedUnit> onClose)
Read an element from the given inlet and continue with the given function,
suspending execution if necessary.
|
protected <T> void |
read(Inlet<T> in,
Procedure<T> andThen,
Effect onClose)
Java API: Read an element from the given inlet and continue with the given function,
suspending execution if necessary.
|
protected <T> void |
readN(Inlet<T> in,
int n,
scala.Function1<scala.collection.Seq<T>,scala.runtime.BoxedUnit> andThen,
scala.Function1<scala.collection.Seq<T>,scala.runtime.BoxedUnit> onClose)
Read a number of elements from the given inlet and continue with the given function,
suspending execution if necessary.
|
protected <T> void |
readN(Inlet<T> in,
int n,
Procedure<java.util.List<T>> andThen,
Procedure<java.util.List<T>> onClose)
Java API: Read a number of elements from the given inlet and continue with the given function,
suspending execution if necessary.
|
protected void |
setHandler(Inlet<?> in,
InHandler handler)
Assigns callbacks for the events for an
Inlet |
protected void |
setHandler(Outlet<?> out,
OutHandler handler)
Assigns callbacks for the events for an
Outlet |
protected void |
setHandlers(Inlet<?> in,
Outlet<?> out,
InHandler handler)
Assign callbacks for linear stage for both
Inlet and Outlet |
protected void |
setKeepGoing(boolean enabled)
Controls whether this stage shall shut down when all its ports are closed, which
is the default.
|
GraphStageLogic.StageActor |
stageActor() |
int |
stageId()
INTERNAL API
|
protected Materializer |
subFusingMaterializer()
An
Materializer that may run fusable parts of the graphs
that it materializes within the same actor as the current GraphStage (if
fusing is available). |
protected InHandler |
totallyIgnorantInput()
Input handler that does not terminate the stage upon receiving completion
nor failure.
|
protected <T> void |
tryPull(Inlet<T> in)
Requests an element on the given port unless the port is already closed.
|
public GraphStageLogic(int inCount, int outCount)
public GraphStageLogic(Shape shape)
public int inCount()
public int outCount()
public int stageId()
public java.lang.Object[] handlers()
public GraphInterpreter.Connection[] portToConn()
public GraphInterpreter interpreter()
protected Materializer materializer()
Materializer
that has set this GraphStage in motion.protected Materializer subFusingMaterializer()
Materializer
that may run fusable parts of the graphs
that it materializes within the same actor as the current GraphStage (if
fusing is available). This materializer must not be shared outside of the
GraphStage.protected final InHandler eagerTerminateInput()
protected final InHandler ignoreTerminateInput()
protected final InHandler conditionalTerminateInput(scala.Function0<java.lang.Object> predicate)
predicate
- (undocumented)protected final InHandler totallyIgnorantInput()
protected final OutHandler eagerTerminateOutput()
protected final OutHandler ignoreTerminateOutput()
protected final OutHandler conditionalTerminateOutput(scala.Function0<java.lang.Object> predicate)
predicate
- (undocumented)protected final void setHandler(Inlet<?> in, InHandler handler)
Inlet
in
- (undocumented)handler
- (undocumented)protected final void setHandlers(Inlet<?> in, Outlet<?> out, InHandler handler)
Inlet
and Outlet
in
- (undocumented)out
- (undocumented)handler
- (undocumented)protected final InHandler getHandler(Inlet<?> in)
Inlet
in
- (undocumented)protected final void setHandler(Outlet<?> out, OutHandler handler)
Outlet
out
- (undocumented)handler
- (undocumented)protected final OutHandler getHandler(Outlet<?> out)
Outlet
out
- (undocumented)protected final <T> void pull(Inlet<T> in)
hasBeenPulled()
can be used
query whether pull is allowed to be called or not. This method will also fail if the port is already closed.in
- (undocumented)protected final <T> void tryPull(Inlet<T> in)
hasBeenPulled()
can be used
query whether pull is allowed to be called or not.in
- (undocumented)protected final <T> void cancel(Inlet<T> in)
in
- (undocumented)protected final <T> T grab(Inlet<T> in)
InHandler.onPush()
for an input port has been invoked, the element that has been pushed
can be retrieved via this method. After grab()
has been called the port is considered to be empty, and further
calls to grab()
will fail until the port is pulled again and a new element is pushed as a response.
The method isAvailable()
can be used to query if the port has an element that can be grabbed or not.
in
- (undocumented)protected final <T> boolean hasBeenPulled(Inlet<T> in)
isAvailable()
must return false for that same port.in
- (undocumented)protected final <T> boolean isAvailable(Inlet<T> in)
grab()
can be used to retrieve the
element. After calling grab()
this method will return false.
If this method returns true then hasBeenPulled()
will return false for that same port.
in
- (undocumented)protected final <T> boolean isClosed(Inlet<T> in)
in
- (undocumented)protected final <T> void push(Outlet<T> out, T elem)
pull()
has been arrived
will fail. There can be only one outstanding push request at any given time. The method isAvailable()
can be
used to check if the port is ready to be pushed or not.out
- (undocumented)elem
- (undocumented)protected final void setKeepGoing(boolean enabled)
true
argument before all ports are closed, and afterwards
it will not be closed until this method is called with a false
argument or the
stage is terminated via completeStage()
or failStage()
.enabled
- (undocumented)protected final <T> void complete(Outlet<T> out)
out
- (undocumented)protected final <T> void fail(Outlet<T> out, java.lang.Throwable ex)
out
- (undocumented)ex
- (undocumented)public final void completeStage()
cancel()
or complete()
on all the input or output ports that have been called,
then marks the stage as stopped.public final void failStage(java.lang.Throwable ex)
cancel()
or fail()
on all the input or output ports that have been called,
then marks the stage as stopped.ex
- (undocumented)public final <T> boolean isAvailable(Outlet<T> out)
out
- (undocumented)protected final <T> boolean isClosed(Outlet<T> out)
out
- (undocumented)protected final <T> void readN(Inlet<T> in, int n, scala.Function1<scala.collection.Seq<T>,scala.runtime.BoxedUnit> andThen, scala.Function1<scala.collection.Seq<T>,scala.runtime.BoxedUnit> onClose)
InHandler
for the given inlet if suspension is needed and reinstalls the current
handler upon receiving the last onPush()
signal.
If upstream closes before N elements have been read,
the onClose
function is invoked with the elements which were read.
in
- (undocumented)n
- (undocumented)andThen
- (undocumented)onClose
- (undocumented)protected final <T> void readN(Inlet<T> in, int n, Procedure<java.util.List<T>> andThen, Procedure<java.util.List<T>> onClose)
InHandler
for the given inlet if suspension is needed and reinstalls the current
handler upon receiving the last onPush()
signal (before invoking the andThen
function).in
- (undocumented)n
- (undocumented)andThen
- (undocumented)onClose
- (undocumented)protected final <T> void read(Inlet<T> in, scala.Function1<T,scala.runtime.BoxedUnit> andThen, scala.Function0<scala.runtime.BoxedUnit> onClose)
InHandler
for the given inlet if suspension is needed and reinstalls the current
handler upon receiving the onPush()
signal (before invoking the andThen
function).in
- (undocumented)andThen
- (undocumented)onClose
- (undocumented)protected final <T> void read(Inlet<T> in, Procedure<T> andThen, Effect onClose)
InHandler
for the given inlet if suspension is needed and reinstalls the current
handler upon receiving the onPush()
signal (before invoking the andThen
function).in
- (undocumented)andThen
- (undocumented)onClose
- (undocumented)protected final void abortReading(Inlet<?> in)
read
call.in
- (undocumented)protected final <T> void emitMultiple(Outlet<T> out, scala.collection.immutable.Iterable<T> elems, scala.Function0<scala.runtime.BoxedUnit> andThen)
OutHandler
for the given outlet if suspension
is needed and reinstalls the current handler upon receiving an onPull()
signal (before invoking the andThen
function).out
- (undocumented)elems
- (undocumented)andThen
- (undocumented)protected final <T> void emitMultiple(Outlet<T> out, scala.collection.immutable.Iterable<T> elems)
OutHandler
for the given outlet if suspension
is needed and reinstalls the current handler upon receiving an onPull()
signal.out
- (undocumented)elems
- (undocumented)protected final <T> void emitMultiple(Outlet<T> out, java.util.Iterator<T> elems)
Emit a sequence of elements through the given outlet, suspending execution if necessary.
This action replaces the AbstractOutHandler
for the given outlet if suspension
is needed and reinstalls the current handler upon receiving an onPull()
signal.
out
- (undocumented)elems
- (undocumented)protected final <T> void emitMultiple(Outlet<T> out, java.util.Iterator<T> elems, Effect andThen)
Emit a sequence of elements through the given outlet, suspending execution if necessary.
This action replaces the AbstractOutHandler
for the given outlet if suspension
is needed and reinstalls the current handler upon receiving an onPull()
signal.
out
- (undocumented)elems
- (undocumented)andThen
- (undocumented)protected final <T> void emitMultiple(Outlet<T> out, scala.collection.Iterator<T> elems, scala.Function0<scala.runtime.BoxedUnit> andThen)
OutHandler
for the given outlet if suspension
is needed and reinstalls the current handler upon receiving an onPull()
signal (before invoking the andThen
function).out
- (undocumented)elems
- (undocumented)andThen
- (undocumented)protected final <T> void emitMultiple(Outlet<T> out, scala.collection.Iterator<T> elems)
OutHandler
for the given outlet if suspension
is needed and reinstalls the current handler upon receiving an onPull()
signal.out
- (undocumented)elems
- (undocumented)protected final <T> void emit(Outlet<T> out, T elem, scala.Function0<scala.runtime.BoxedUnit> andThen)
OutHandler
for the given outlet if suspension
is needed and reinstalls the current handler upon receiving an onPull()
signal (before invoking the andThen
function).out
- (undocumented)elem
- (undocumented)andThen
- (undocumented)protected final <T> void emit(Outlet<T> out, T elem)
OutHandler
for the given outlet if suspension
is needed and reinstalls the current handler upon receiving an onPull()
signal.out
- (undocumented)elem
- (undocumented)protected final void abortEmitting(Outlet<?> out)
emit
call.out
- (undocumented)protected final <Out,In extends Out> void passAlong(Inlet<In> from, Outlet<Out> to, boolean doFinish, boolean doFail, boolean doPull)
doFinish
and doFail
control whether
completion or failure of the given inlet shall lead to stage termination or not.
doPull
instructs to perform one initial pull on the from
port.from
- (undocumented)to
- (undocumented)doFinish
- (undocumented)doFail
- (undocumented)doPull
- (undocumented)public final <T> AsyncCallback<T> getAsyncCallback(scala.Function1<T,scala.runtime.BoxedUnit> handler)
GraphStage
with an asynchronous notification. The invoke()
method of the returned
AsyncCallback
is safe to be called from other threads and it will in the background thread-safely
delegate to the passed callback function. I.e. invoke()
will be called by the external world and
the passed handler will be invoked eventually in a thread-safe way by the execution environment.
This object can be cached and reused within the same GraphStageLogic
.
handler
- (undocumented)protected final <T> AsyncCallback<T> createAsyncCallback(Procedure<T> handler)
GraphStage
with an asynchronous notification. The invoke()
method of the returned
AsyncCallback
is safe to be called from other threads and it will in the background thread-safely
delegate to the passed callback function. I.e. invoke()
will be called by the external world and
the passed handler will be invoked eventually in a thread-safe way by the execution environment.
This object can be cached and reused within the same GraphStageLogic
.
handler
- (undocumented)public final GraphStageLogic.StageActor stageActor()
protected final GraphStageLogic.StageActor getStageActor(scala.Function1<scala.Tuple2<ActorRef,java.lang.Object>,scala.runtime.BoxedUnit> receive)
StageActorRef
which can be used to interact with from the outside world "as-if" an Actor
.
The messages are looped through the getAsyncCallback
mechanism of GraphStage
so they are safe to modify
internal state of this stage.
This method must (the earliest) be called after the GraphStageLogic
constructor has finished running,
for example from the preStart
callback the graph stage logic provides.
Created StageActorRef
to get messages and watch other actors in synchronous way.
The StageActorRef
's lifecycle is bound to the Stage, in other words when the Stage is finished,
the Actor will be terminated as well. The entity backing the StageActorRef
is not a real Actor,
but the GraphStageLogic
itself, therefore it does not react to PoisonPill
.
receive
- callback that will be called upon receiving of a message by this special Actorprotected void beforePreStart()
protected void afterPostStop()
public void preStart() throws java.lang.Exception
java.lang.Exception
public void postStop() throws java.lang.Exception
java.lang.Exception