@Internal public class MailboxProcessor extends Object implements Closeable
runMailboxLoop()
that continuously executes the provided MailboxDefaultAction
in
a loop. On each iteration, the method also checks if there are pending actions in the mailbox and
executes such actions. This model ensures single-threaded execution between the default action
(e.g. record processing) and mailbox actions (e.g. checkpoint trigger, timer firing, ...).
The MailboxDefaultAction
interacts with this class through the MailboxProcessor.MailboxController
to communicate control flow changes to the mailbox loop, e.g. that invocations
of the default action are temporarily or permanently exhausted.
The design of runMailboxLoop()
is centered around the idea of keeping the expected
hot path (default action, no mail) as fast as possible. This means that all checking of mail and
other control flags (mailboxLoopRunning, suspendedDefaultAction) are always connected to #hasMail
indicating true. This means that control flag changes in the mailbox thread can be done directly,
but we must ensure that there is at least one action in the mailbox so that the change is picked
up. For control flag changes by all other threads, that must happen through mailbox actions, this
is automatically the case.
This class has an open-prepareClose-close lifecycle that is connected with and maps to the
lifecycle of the encapsulated TaskMailbox
(which is open-quiesce-close).
Modifier and Type | Class and Description |
---|---|
protected static class |
MailboxProcessor.MailboxController
Implementation of
MailboxDefaultAction.Controller that is connected to a MailboxProcessor instance. |
Modifier and Type | Field and Description |
---|---|
protected TaskMailbox |
mailbox
The mailbox data-structure that manages request for special actions, like timers,
checkpoints, ...
|
protected MailboxDefaultAction |
mailboxDefaultAction
Action that is repeatedly executed if no action request is in the mailbox.
|
Constructor and Description |
---|
MailboxProcessor() |
MailboxProcessor(MailboxDefaultAction mailboxDefaultAction) |
MailboxProcessor(MailboxDefaultAction mailboxDefaultAction,
StreamTaskActionExecutor actionExecutor) |
MailboxProcessor(MailboxDefaultAction mailboxDefaultAction,
TaskMailbox mailbox,
StreamTaskActionExecutor actionExecutor) |
MailboxProcessor(MailboxDefaultAction mailboxDefaultAction,
TaskMailbox mailbox,
StreamTaskActionExecutor actionExecutor,
MailboxMetricsController mailboxMetricsControl) |
Modifier and Type | Method and Description |
---|---|
void |
allActionsCompleted()
This method must be called to end the stream task when all actions for the tasks have been
performed.
|
void |
close()
Lifecycle method to close the mailbox for action submission/retrieval.
|
void |
drain()
Finishes running all mails in the mailbox.
|
MailboxExecutor |
getMailboxExecutor(int priority)
Returns an executor service facade to submit actions to the mailbox.
|
MailboxMetricsController |
getMailboxMetricsControl()
Gets
MailboxMetricsController for control and access to mailbox metrics. |
MailboxExecutor |
getMainMailboxExecutor() |
boolean |
hasMail() |
boolean |
isDefaultActionAvailable() |
boolean |
isMailboxLoopRunning() |
boolean |
isMailboxThread()
Check if the current thread is the mailbox thread.
|
void |
prepareClose()
Lifecycle method to close the mailbox for action submission.
|
void |
reportThrowable(Throwable throwable)
Reports a throwable for rethrowing from the mailbox thread.
|
void |
runMailboxLoop()
Runs the mailbox processing loop.
|
boolean |
runMailboxStep()
Execute a single (as small as possible) step of the mailbox.
|
void |
suspend()
Suspend the running of the loop which was started by
runMailboxLoop() }. |
protected final TaskMailbox mailbox
protected final MailboxDefaultAction mailboxDefaultAction
@VisibleForTesting public MailboxProcessor()
public MailboxProcessor(MailboxDefaultAction mailboxDefaultAction)
public MailboxProcessor(MailboxDefaultAction mailboxDefaultAction, StreamTaskActionExecutor actionExecutor)
public MailboxProcessor(MailboxDefaultAction mailboxDefaultAction, TaskMailbox mailbox, StreamTaskActionExecutor actionExecutor)
public MailboxProcessor(MailboxDefaultAction mailboxDefaultAction, TaskMailbox mailbox, StreamTaskActionExecutor actionExecutor, MailboxMetricsController mailboxMetricsControl)
public MailboxExecutor getMainMailboxExecutor()
public MailboxExecutor getMailboxExecutor(int priority)
priority
- the priority of the MailboxExecutor
.@VisibleForTesting public MailboxMetricsController getMailboxMetricsControl()
MailboxMetricsController
for control and access to mailbox metrics.MailboxMetricsController
.public void prepareClose()
public void close()
RunnableFuture
that are still contained in the
mailbox.close
in interface Closeable
close
in interface AutoCloseable
public void drain() throws Exception
Exception
public void runMailboxLoop() throws Exception
suspend()
. For resuming the loop this method should
be called again.Exception
public void suspend()
runMailboxLoop()
}.@VisibleForTesting public boolean runMailboxStep() throws Exception
Exception
public boolean isMailboxThread()
public void reportThrowable(Throwable throwable)
throwable
- to report by rethrowing from the mailbox loop.public void allActionsCompleted()
@VisibleForTesting public boolean isDefaultActionAvailable()
@VisibleForTesting public boolean isMailboxLoopRunning()
public boolean hasMail()
Copyright © 2014–2024 The Apache Software Foundation. All rights reserved.