io.engineblock.activityapi.core

Interface AsyncAction

All Superinterfaces:

Action

public interface AsyncAction
extends Action

An AsyncAction allows an activity type to implement asynchronous operations within each thread.

An action that does not have the ability to asynchronously submit work in an unblocking fashion should not use this AsyncAction API. In other words, the action should not defer work for which is needed before an operation is effectively submitted or offloaded to the target system. This would degrade the accuracy of timing metrics. In such cases, the action should implement the SyncAction API instead.

Method Summary

Modifier and Type	Method and Description
OpContext	dequeue() Dequeue a finished unit of work from the action.
boolean	enqueue(OpContext unprocessed) Enqueue a cycle to be processed by the action.

Methods inherited from interface io.engineblock.activityapi.core.Action

init

Method Detail

enqueue

boolean enqueue(OpContext unprocessed)

Enqueue a cycle to be processed by the action. As long as this method signals more work is being accepted, the calling motor should enqueue more work. An action is never allowed to reject work. It is only allowed to signal whether or not the caller should continue to submit more work. Once the async action signals that the internal buffer is full, it should not be called again until dequeue() is called at least once. The enqueued cycle should be processed by the AsyncAction as a nonblocking call before returning.

If the method implementation is not able to accept another request for any reason, it MUST throw an exception instead of returning null.

Parameters:

unprocessed - contain the cycle number which is the basis for the action

Returns:

true, if the action is accepting more work.

dequeue

OpContext dequeue()

Dequeue a finished unit of work from the action. This method should be called only once before attempting to enqueue again. The AsyncAction is required to block when this method is called until it can produce a cycle result corresponding to one of the enqueued cycles via enqueue(OpContext)}. If there are no remaining results to be returned, then null will be returned. This will remain the case unless or untill the caller submits further work to the AsyncAction. Once the caller is done calling enqueue(OpContext), this method should be called to drain all pending results.*

Before an OpContext is returned by this method is is expected that the implementor call OpContext.setResult(int). This causes the status to be propagated to the owning stride as well as for any downstream outputs. If the implementation has a source of external task completion that may occur before the motor calls this method, then the result should be set via callback whenever possible. This will keep op service times accurate in spite of any queueing delays between the motor and the action implementation.

Design note: A mutable return type is used here that is the same as the enqueued carrier type to allow for recycling of the carrier object. If the implementing Action simply sets state on the provided type on enqueue(OpContext), rather than creating new instances, then heap pressure will be reduced.

Returns:

a CycleResult, or null signifying no further results are available unless or until enqueue(OpContext) is called again.