Poco::JS::Core

class 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

struct ErrorInfo

 

struct MemoryWarning

 

struct StackFrame

 

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

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.

callInContext

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

static Ptr current();

Returns the JSExecutor for the current thread.

globalContext inline

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

Returns the JSExecutor's global context.

isRunning inline

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 inline

v8::Isolate * isolate();

Returns the JSExecutor's Isolate.

run virtual

void run();

Runs the script.

scriptContext inline

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

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 inline

const Poco::URI & uri() const;

Returns the script's source URI.

attachToCurrentThread protected

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 protected

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

cleanup protected

void cleanup();

compile protected

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

handleError protected virtual

virtual void handleError(
    const ErrorInfo & errorInfo
);

Called when the JavaScript terminates with an error.

handleMemoryWarning protected virtual

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

Called when the script is near its set memory limit.

handleOutOfMemory protected virtual

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

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

importModule protected

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

Imports a JavaScript module.

importModule protected

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

Imports a native module.

include protected static

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

Implements the JavaScript include function to include another script.

includeScript protected

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

Includes another script.

reportError protected

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

reportError protected

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

require protected static

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

Implements the JavaScript require function to import a module.

resolveModule protected

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 protected

void runImpl();

scriptCompleted protected virtual

virtual void scriptCompleted();

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

setWrapperProperty protected static inline

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

setWrapperProperty protected static inline

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

setup protected

void setup();

setupGlobalObject protected virtual

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 protected virtual

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.

Variables

memoryWarning

Poco::BasicEvent < const MemoryWarning > memoryWarning;

Fired when the script is using too much memory, exceeding the set heap limit.

outOfMemory

Poco::BasicEvent < void > outOfMemory;

Fired when the script has run out of memory because the heap limit has been exceeded, and has therefore been terminated.

scriptError

Poco::BasicEvent < const ErrorInfo > scriptError;

Fired when the script terminates with an error. Reports the error message as argument.

stopped

Poco::BasicEvent < void > stopped;

Fired when the executor has been stopped.

_globalContext protected

v8::Persistent < v8::Context > _globalContext;

_globalObjectTemplate protected

v8::Persistent < v8::ObjectTemplate > _globalObjectTemplate;

_importStack protected

std::vector < Poco::URI > _importStack;

_imports protected

std::set < std::string > _imports;

_moduleRegistries protected

std::vector < ModuleRegistry::Ptr > _moduleRegistries;

_moduleSearchPaths protected

std::vector < std::string > _moduleSearchPaths;

_pCurrentExecutor protected static

static Poco::ThreadLocal < JSExecutor * > _pCurrentExecutor;

_pooledIso protected

Poco::JS::Core::PooledIsolate _pooledIso;

_running protected

Poco::AtomicCounter _running;

_script protected

v8::Persistent < v8::Script > _script;

_scriptContext protected

v8::Persistent < v8::Context > _scriptContext;

_source protected

std::string _source;

_sourceURI protected

Poco::URI _sourceURI;

_terminated protected

Poco::Event _terminated;

Securely control IoT edge devices from anywhere   Connect a Device