Class Poco::JS::Core::JSExecutor

File Information

Library: JS/Core
Package: Execution
Header: Poco/JS/Core/JSExecutor.h

Description

The JSExecutor class executes JavaScript code in a controlled environment (i.e., with a specific set of global JavaScript objects set).

Inheritance

Direct Base Classes: Poco::Runnable, Poco::RefCountedObject

All Base Classes: Poco::RefCountedObject, Poco::Runnable

Known Derived Classes: Poco::OSP::JS::JSExecutor, Poco::OSP::JS::TimedJSExecutor, TimedJSExecutor

Member Summary

Member Functions: addModuleRegistry, addModuleSearchPath, attachToCurrentThread, buildStackTrace, call, callInContext, cancelTerminate, cleanup, compile, current, globalContext, handleError, handleMemoryWarning, handleOutOfMemory, importModule, include, includeScript, isRunning, isTerminating, isolate, reportError, require, resolveModule, run, runImpl, scriptCompleted, scriptContext, setWrapperProperty, setup, setupGlobalObject, setupGlobalObjectTemplate, sleep, stop, terminate, uri

Inherited Functions: duplicate, referenceCount, release, run

Nested Classes

Types Aliases

Ptr

using Ptr = Poco::AutoPtr < JSExecutor >;

Enumerations

Anonymous

DEFAULT_MEMORY_LIMIT = 64 * 1024 * 1024

Constructors

JSExecutor

JSExecutor(
    const std::string & source,
    const Poco::URI & sourceURI,
    Poco::UInt64 memoryLimit = DEFAULT_MEMORY_LIMIT
);

Creates the JSExecutor with the given JavaScript source, sourceURI and memoryLimit.

JSExecutor

JSExecutor(
    const std::string & source,
    const Poco::URI & sourceURI,
    const std::vector < std::string > & moduleSearchPaths,
    Poco::UInt64 memoryLimit = DEFAULT_MEMORY_LIMIT
);

Creates the JSExecutor with the given JavaScript source, sourceURI, module search paths and memoryLimit.

Destructor

~JSExecutor

virtual ~JSExecutor();

Destroys the JSExecutor.

Member Functions

addModuleRegistry

void addModuleRegistry(
ModuleRegistry::Ptr pRegistry
);

Adds a module registry to the collection of registries.

Module registries must be added before the script is executed.

addModuleSearchPath

void addModuleSearchPath(
const std::string & path
);

Adds a search path to the internal list of search paths.

Module search paths must be added before the script is executed.

call

void call(
    v8::Handle < v8::Function > & function,
    v8::Handle < v8::Value > & receiver,
    int argc,
    v8::Handle < v8::Value > argv[]
);

Calls a specific function defined in the script, using the given arguments.

Sets up a script context scope for the call.

call

void call(
    v8::Persistent < v8::Object > & jsObject,
    const std::string & method,
    const std::string & args
);

Calls a specific method defined in the given object with the given arguments, which must be given as a JSON string.

Sets up a script context scope for the call.

call

void call(
v8::Persistent < v8::Function > & function
);

Calls a specific function defined in the script, without arguments.

Sets up a script context scope for the call.

call

void call(
v8::Persistent < v8::Function > & function,
v8::Persistent < v8::Array > & args
);

Calls a specific function defined in the script, with the given arguments, which must be in a JavaScript Array.

Sets up a script context scope for the call.

void callInContext(
    v8::Isolate * pIsolate,
    v8::Local < v8::Context > & context,
    v8::Handle < v8::Function > & function,
    v8::Handle < v8::Value > & receiver,
    int argc,
    v8::Handle < v8::Value > argv[]
);

Calls a specific function defined in the script, using the given arguments.

A script context scope for the call must have been set up by the caller.

callInContext

void callInContext(
    v8::Isolate * pIsolate,
    v8::Local < v8::Context > & context,
    v8::Persistent < v8::Object > & jsObject,
    const std::string & method,
    int argc,
    v8::Handle < v8::Value > argv[]
);

Calls a specific method defined in the given object with the given arguments.

A script context scope for the call must have been set up by the caller.

cancelTerminate

void cancelTerminate();

Cancels a previous terminate() call.

current

static Ptr current();

Returns the JSExecutor for the current thread.

globalContext

v8::Persistent < v8::Context > & globalContext();

Returns the JSExecutor's global context.

isRunning

bool isRunning() const;

Returns true if the JSExecutor is currently executing a script.

isTerminating

bool isTerminating() const;

Returns true if the script is currently terminating due to a call to terminate().

isolate

v8::Isolate * isolate();

Returns the JSExecutor's Isolate.

run

void run();

Runs the script.

See also: Poco::Runnable::run()

scriptContext

v8::Persistent < v8::Context > & scriptContext();

Returns the JSExecutor's script context.

sleep

bool sleep(
long milliseconds
);

Sleeps execution for the given number of milliseconds.

Sleep can be interrupted by calling terminate().

Returns true if sleep() was interrupted, otherwise false.

stop

virtual void stop();

Stops the script's execution.

After calling stop(), the JSExecutor can no longer be used to execute a script by calling run() or call().

Will also fire the stopped event.

terminate

void terminate();

Terminate the currently running script.

Note that termination is asynchronous. The script may continue to run for some time before actually terminating.

After calling terminate(), the JSExecutor is still usable and execution can be resumed at a later time by calling run() or call().

uri

const Poco::URI & uri() const;

Returns the script's source URI.

attachToCurrentThread

void attachToCurrentThread();

Attaches the JSExecutor to the current thread. Must be called before any JavaScript code is executed if the JSExecutor is invoked from a different thread it was created in.

buildStackTrace

std::vector < StackFrame > buildStackTrace(
v8::Isolate * pIsolate,
v8::Local < v8::StackTrace > & stackTrace
);

cleanup

void cleanup();

compile

void compile(
v8::Local < v8::Context > & context
);

handleError

virtual void handleError(
const ErrorInfo & errorInfo
);

Called when the JavaScript terminates with an error.

handleMemoryWarning

virtual void handleMemoryWarning(
std::size_t currentHeapLimit,
std::size_t initialHeapLimit
);

Called when the script is near its set memory limit.

handleOutOfMemory

virtual void handleOutOfMemory(
std::size_t currentHeapLimit,
std::size_t initialHeapLimit
);

Called when the script has exhausted its memory limit and is terminated.

importModule

void importModule(
const v8::FunctionCallbackInfo < v8::Value > & args,
const std::string & uri
);

Imports a JavaScript module.

importModule

void importModule(
    const v8::FunctionCallbackInfo < v8::Value > & args,
    const std::string & uri,
    Module::Ptr pModule
);

Imports a native module.

include

static void include(
const v8::FunctionCallbackInfo < v8::Value > & args
);

Implements the JavaScript include function to include another script.

includeScript

void includeScript(
v8::Isolate * pIsolate,
const std::string & uri
);

Includes another script.

reportError

void reportError(
v8::Isolate * pIsolate,
v8::TryCatch & tryCatch
);

reportError

void reportError(
v8::Isolate * pIsolate,
const ErrorInfo & errorInfo
);

require

static void require(
const v8::FunctionCallbackInfo < v8::Value > & args
);

Implements the JavaScript require function to import a module.

resolveModule

Poco::SharedPtr < std::istream > resolveModule(
const std::string & uri,
Poco::URI & resolvedURI
);

Tries to locate the script identified by uri (which may be a relative, partial URI), and returns a stream for reading the script source if the module has not been imported yet, or null if the module has already been imported. If the module URI has been successfully resolved, resolvedURI will contain the fully-qualified URI. If the module URI cannot be successfully resolved, a Poco::NotFoundException will be thrown.

runImpl

void runImpl();

scriptCompleted

virtual void scriptCompleted();

Called after the script has completed, while still within the scope.

setWrapperProperty

template < typename W > static void setWrapperProperty(
    v8::Local < v8::Object > & object,
    v8::Isolate * pIsolate,
    const std::string & name
);

setWrapperProperty

template < typename W, typename N > static void setWrapperProperty(
    v8::Local < v8::Object > & object,
    v8::Isolate * pIsolate,
    const std::string & name,
    N * pNative
);

setup

void setup();

setupGlobalObject

virtual void setupGlobalObject(
v8::Local < v8::Object > & global,
v8::Isolate * pIsolate
);

Sets up the script's global object by adding properties to it. Can be overridded by subclasses, but overrides must call the base class method.

Called before initial compilation of the script, after setupGlobalObjectTemplate().

setupGlobalObjectTemplate

virtual void setupGlobalObjectTemplate(
v8::Local < v8::ObjectTemplate > & global,
v8::Isolate * pIsolate
);

Set up global JavaScript objects in the global object template. Can be overridded by subclasses, but overrides must call the base class method.

Note that only other object templates or function templates, as well as primitive values may be added to the global object template. Non-primitive types such as objects or arrays must be registered in setupGlobalObject().

Called before initial compilation of the script.

File Information

Description

Inheritance

Member Summary

Nested Classes

Types Aliases

Enumerations

Anonymous

Constructors

Destructor

Member Functions

Variables