ptolemy.actor.lib.jjs

Class VertxHelperBase

java.lang.Object

ptolemy.actor.lib.jjs.HelperBase

ptolemy.actor.lib.jjs.VertxHelperBase

Direct Known Subclasses:

AudioHelper, EventBusHelper, HttpClientHelper, HttpServerHelper, SocketHelper, UDPSocketHelper, WebSocketHelper, WebSocketServerHelper, XBeeHelper

public class VertxHelperBase
extends HelperBase

A base class for helper classes that use an embedded Vert.x core. This creates only one static Vert.x core that is accessible to its subclasses. It also keeps track of helpers that have been created for a particular actor, and provides a static method to obtain those helpers. Generally we will want no more than one such helper per actor. The references to the helpers are weak so that if the actor is garbage collected, the reference can be too.

This class also provides utilities for submitting jobs to be executed in an associated verticle. This is useful for jobs that trigger future callbacks, because the verticle will ensure that all callbacks are called in the same thread.

Moreover, this class provides utilities for ensuring that a requested job has been completed, including all expected callbacks, before the next job is initiated. This is useful for ensuring that responses to requests occur in the same order as the requests themselves. To use this, when you make a request (e.g. using submit(Runnable), the subclass can call the protected method _setBusy(boolean) with argument true, and subsequent requests will simply be queued until the subclass calls _setBusy(boolean) with argument false.

This class also provides utilities for a subclass to issue asynchronous requests in order, and when callbacks occur, to execute those callbacks in the same order as the submitted requests. To use this, the subclass should assign consecutive increasing integers, starting with zero, to each request, and then wrap responses to that request in a Runnable and pass that Runnable to the protected method _issueOrDeferResponse(long, boolean, Runnable). That method will execute the Runnable only when all previous requests (ones with earlier sequence numbers) have had a response executed that indicated (with the second argument) that the request has been fully handled. This facility must be used with care: the subclass must ensure that every request results in at least one call to _issueOrDeferResponse(long, boolean, Runnable) with the second argument being true; failing to do so will result in all future responses being queued and never executing. Using a timeout, for example, can ensure this. Note also that the specified Runnable will execute in the director thread (via a timeout mechanism with timeout equal to zero), not in the Verticle. Thus, subclasses that use should not directly invoke Vert.x functions that need to be run in the verticle in the Runnable that they pass. They should instead use submit(Runnable).

Since:

Ptolemy II 11.0

Version:

$Id$

Author:

Hokeun Kim and Edward A. Lee

Pt.AcceptedRating:

Red (bilung)

Pt.ProposedRating:

Yellow (eal)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	VertxHelperBase.AccessorVerticle Verticle to handle requests.

Nested classes/interfaces inherited from class ptolemy.actor.lib.jjs.HelperBase

HelperBase.DATA_TYPE

Field Summary

Fields

Modifier and Type	Field and Description
protected VertxHelperBase.AccessorVerticle	_verticle Verticle supporting this helper.
protected static io.vertx.core.Vertx	_vertx Global (unclustered) instance of Vert.x core.

Fields inherited from class ptolemy.actor.lib.jjs.HelperBase

_actor, _currentObj

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	VertxHelperBase(java.lang.Object actor, jdk.nashorn.api.scripting.ScriptObjectMirror helping) Construct a helper for the specified JavaScript actor and create a verticle that can execute submitted jobs atomically.
protected	VertxHelperBase(java.lang.Object actor, jdk.nashorn.api.scripting.ScriptObjectMirror helping, VertxHelperBase helper) Construct a helper for the specified JavaScript actor and create a verticle that can execute submitted jobs atomically.

Method Summary

Modifier and Type	Method and Description
protected void	_issueOrDeferResponse(long requestNumber, boolean done, java.lang.Runnable response) Execute the specified response in the same order as the request that triggered the response.
protected void	_processPendingJob() If the verticle is not busy, process the next pending job.
protected void	_setBusy(boolean busy) Specify whether this helper is currently processing a previous request.
static void	closeVertx() Stop the global (unclustered instance of Vert.x.
static VertxHelperBase	getHelper(java.lang.Object actor) Return an instance of this helper for the specified actor, if one has been created and not garbage collected.
static java.util.Set<java.lang.String>	getImageTypes() Return a set of informal image type names that can be sent.
void	reset() Reset this helper.
void	submit(java.lang.Runnable job) Submit a job to be executed by the associated verticle.
static java.lang.String[]	supportedReceiveTypes() Return an array of the types supported by the current host for receiveType arguments, which are the types that can be extracted from buffers.
static java.lang.String[]	supportedSendTypes() Return an array of the types supported by the current host for sendType arguments, which are the types that can be written to buffers.
void	undeploy() Undeploy the associated verticle.

Methods inherited from class ptolemy.actor.lib.jjs.HelperBase

_appendNumericToBuffer, _appendToBuffer, _error, _error, _error, _error, _extractFromBuffer, _issueResponse, _removeDuplicates, _sizeOfType, _toJavaBytes, _toJSArray, getHelping

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_verticle

protected VertxHelperBase.AccessorVerticle _verticle

Verticle supporting this helper.

_vertx

protected static io.vertx.core.Vertx _vertx

Global (unclustered) instance of Vert.x core.

Constructor Detail

VertxHelperBase

protected VertxHelperBase(java.lang.Object actor,
                          jdk.nashorn.api.scripting.ScriptObjectMirror helping)

Construct a helper for the specified JavaScript actor and create a verticle that can execute submitted jobs atomically. This is protected to help prevent applications from creating more than one instance per actor.

Parameters:

actor - The JavaScript actor that this is helping, or a RestrictedJavaScriptInterface proxy for that actor.

helping - The JavaScript object that this is helping.

VertxHelperBase

protected VertxHelperBase(java.lang.Object actor,
                          jdk.nashorn.api.scripting.ScriptObjectMirror helping,
                          VertxHelperBase helper)

Construct a helper for the specified JavaScript actor and create a verticle that can execute submitted jobs atomically. This is protected to help prevent applications from creating more than one instance per actor.

Parameters:

actor - The JavaScript actor that this is helping, or a RestrictedJavaScriptInterface proxy for that actor.

helping - The JavaScript object that this is helping.

helper - The helper providing the verticle and event handler, or null to create a new verticle and event handler.

Method Detail

closeVertx

public static void closeVertx()

Stop the global (unclustered instance of Vert.x. This method is typically called before exiting the JVM.

getHelper

public static VertxHelperBase getHelper(java.lang.Object actor)

Return an instance of this helper for the specified actor, if one has been created and not garbage collected. Return null otherwise. If this returns null, the client should create an instance of the appropriate subclass. That instance will deploy a verticle that will execute jobs submitted through the submit(Runnable) method.

Parameters:

actor - Either a JavaScript actor or a RestrictedJavaScriptInterface.

Returns:

An instance of this helper for the specified actor.

reset

public void reset()

Reset this helper. This method discards any pending submitted jobs and marks the helper not busy.

submit

public void submit(java.lang.Runnable job)

Submit a job to be executed by the associated verticle. The job can invoke Vert.x functionality, specifying callbacks, and those callbacks will be ensured of running in the same thread as the job itself. This can be called from any thread.

Parameters:

job - The job to execute.

getImageTypes

public static java.util.Set<java.lang.String> getImageTypes()

Return a set of informal image type names that can be sent.

Returns:

A set of image type names.

supportedReceiveTypes

public static java.lang.String[] supportedReceiveTypes()

Return an array of the types supported by the current host for receiveType arguments, which are the types that can be extracted from buffers.

Returns:

An array of types.

supportedSendTypes

public static java.lang.String[] supportedSendTypes()

Return an array of the types supported by the current host for sendType arguments, which are the types that can be written to buffers.

Returns:

An array of types.

undeploy

public void undeploy()

Undeploy the associated verticle. Note that jobs that are submitted after this is called will never be executed.

_issueOrDeferResponse

protected void _issueOrDeferResponse(long requestNumber,
                                     boolean done,
                                     java.lang.Runnable response)

Execute the specified response in the same order as the request that triggered the response. The execution will be done in the director thread, not in the verticle, so that it is executed atomically with respect to the swarmlet execution. This ensures, for example, that if the response produces multiple output events or errors, that all those output events and errors are simultaneous. It also prevents threading issues from having the response execute concurrently with the swarmlet execution. Specifically, if the specified request number matches the next expected response, then execute the specified response. Otherwise, if there is an earlier expected response, then defer this one, and if a response has already been issued for this request, then discard this response. This must be called in a vert.x event loop; i.e., it should be called only within handlers for vert.x objects. Specifically: If the requestNumber matches the _nextResponse number, then execute the specified response. If the requestNumber is less than _nextResponse, then queue the response for later execution. If the requestNumber is greater than _nextResponse, then discard the response. If the done argument is true, then after this response is executed, increment the _nextResponse number and check for any deferred requests that match that new number, and execute that one.

Parameters:

requestNumber - The number of the request.

done - True to indicate that this request is complete.

response - The response to execute.

_processPendingJob

protected void _processPendingJob()

If the verticle is not busy, process the next pending job. This method should be called only by the verticle.

See Also:

_setBusy(boolean)

_setBusy

protected void _setBusy(boolean busy)

Specify whether this helper is currently processing a previous request. After this is called with argument true, any subsequent calls to submit(Runnable) will defer execution of the job until this is later called with argument false. If you call this with argument true, please be sure you later call it with argument false. The purpose of this method is to ensure that if a job involves some callbacks, that those callbacks are processed before the next job is executed. Normally, you would call this with argument true when requesting a service, and call it with argument false when the service has been completely provided. If you do not call this at all, then jobs and callbacks may be arbitrarily interleaved (though they will all execute in the same thread).

Parameters:

busy - True to defer jobs, false to stop deferring.