Abstraction around a SpiderMonkey JS::Realm. More...

#include <ScriptInterface.h>

Collaboration diagram for ScriptInterface:

Classes
struct	CmptPrivate

struct	CustomType

Public Member Functions
	ScriptInterface (const char nativeScopeName, const char debugName, ScriptContext &context)
	Constructor. More...

template<typename Context >
	ScriptInterface (const char nativeScopeName, const char debugName, Context &&context)

	ScriptInterface (const char nativeScopeName, const char debugName, const ScriptInterface &neighbor)
	Alternate constructor. More...

	~ScriptInterface ()

void	SetCallbackData (void *pCBData)

JSContext *	GetGeneralJSContext () const
	GetGeneralJSContext returns the context without starting a GC request and without entering the ScriptInterface compartment. More...

ScriptContext &	GetContext () const

bool	LoadGlobalScripts ()
	Load global scripts that most script interfaces need, located in the /globalscripts directory. More...

bool	ReplaceNondeterministicRNG (boost::random::rand48 &rng)
	Replace the default JS random number generator with a seeded, network-synced one. More...

void	CallConstructor (JS::HandleValue ctor, JS::HandleValueArray argv, JS::MutableHandleValue out) const
	Call a constructor function, equivalent to JS "new ctor(arg)". More...

JSObject *	CreateCustomObject (const std::string &typeName) const

void	DefineCustomObjectType (JSClass clasp, JSNative constructor, uint minArgs, JSPropertySpec ps, JSFunctionSpec fs, JSPropertySpec static_ps, JSFunctionSpec *static_fs)

template<typename T >
bool	SetGlobal (const char *name, const T &value, bool replace=false, bool constant=true, bool enumerate=true)
	Set the named property on the global object. More...

bool	SetPrototype (JS::HandleValue obj, JS::HandleValue proto)

bool	LoadScript (const VfsPath &filename, const std::string &code) const
	Load and execute the given script in a new function scope. More...

bool	LoadGlobalScript (const VfsPath &filename, const std::string &code) const
	Load and execute the given script in the global scope. More...

bool	LoadGlobalScriptFile (const VfsPath &path) const
	Load and execute the given script in the global scope. More...

bool	Eval (const char *code) const
	Evaluate some JS code in the global scope. More...

bool	Eval (const char *code, JS::MutableHandleValue out) const

template<typename T >
bool	Eval (const char *code, T &out) const

bool	MathRandom (double &nbr) const
	Calls the random number generator assigned to this ScriptInterface instance and returns the generated number. More...

Static Public Member Functions
template<typename T >
static T *	ObjectFromCBData (const ScriptRequest &rq)
	Convert the CmptPrivate callback data to T*. More...

template<typename T >
static T *	ObjectFromCBData (const ScriptRequest &rq, JS::CallArgs &)
	Variant for the function wrapper. More...

static bool	GetGlobalProperty (const ScriptRequest &rq, const std::string &name, JS::MutableHandleValue out)
	Get an object from the global scope or any lexical scope. More...

static bool	Math_random (JSContext cx, uint argc, JS::Value vp)
	JSNative wrapper of the above. More...

template<typename T >
static T *	GetPrivate (const ScriptRequest &rq, JS::HandleObject thisobj, JSClass *jsClass)
	Retrieve the private data field of a JSObject that is an instance of the given JSClass. More...

template<typename T >
static T *	GetPrivate (const ScriptRequest &rq, JS::CallArgs &callArgs, JSClass *jsClass)
	Retrieve the private data field of a JS Object that is an instance of the given JSClass. More...

template<>
void *	ObjectFromCBData (const ScriptRequest &rq)

Private Member Functions
	NONCOPYABLE (ScriptInterface)

bool	SetGlobal_ (const char *name, JS::HandleValue value, bool replace, bool constant, bool enumerate)

Private Attributes
CmptPrivate	m_CmptPrivate

std::unique_ptr< ScriptInterface_impl >	m

std::map< std::string, CustomType >	m_CustomObjectTypes

Friends
class	ScriptRequest

Detailed Description

Abstraction around a SpiderMonkey JS::Realm.

Thread-safety:

May be used in non-main threads.
Each ScriptInterface must be created, used, and destroyed, all in a single thread (it must never be shared between threads).

Constructor & Destructor Documentation

◆ ScriptInterface() [1/3]

ScriptInterface::ScriptInterface	(	const char *	nativeScopeName,
		const char *	debugName,
		ScriptContext &	context
	)

Constructor.

Parameters

nativeScopeName	Name of global object that functions (via ScriptFunction::Register) will be placed into, as a scoping mechanism; typically "Engine"
debugName	Name of this interface for CScriptStats purposes.
context	ScriptContext to use when initializing this interface.

◆ ScriptInterface() [2/3]

template<typename Context >

ScriptInterface::ScriptInterface	(	const char *	nativeScopeName,
		const char *	debugName,
		Context &&	context
	)

inline

◆ ScriptInterface() [3/3]

ScriptInterface::ScriptInterface	(	const char *	nativeScopeName,
		const char *	debugName,
		const ScriptInterface &	neighbor
	)

Alternate constructor.

This creates the new Realm in the same Compartment as the neighbor scriptInterface. This means that data can be freely exchanged between these two script interfaces without cloning.

Parameters

nativeScopeName	Name of global object that functions (via ScriptFunction::Register) will be placed into, as a scoping mechanism; typically "Engine"
debugName	Name of this interface for CScriptStats purposes.
scriptInterface	'Neighbor' scriptInterface to share a compartment with.

◆ ~ScriptInterface()

ScriptInterface::~ScriptInterface ( )

Member Function Documentation

◆ CallConstructor()

void ScriptInterface::CallConstructor	(	JS::HandleValue	ctor,
		JS::HandleValueArray	argv,
		JS::MutableHandleValue	out
	)		const

Call a constructor function, equivalent to JS "new ctor(arg)".

Parameters

ctor	An object that can be used as constructor
argv	Constructor arguments
out	The new object; On error an error message gets logged and out is Null (out.isNull() == true).

◆ CreateCustomObject()

JSObject * ScriptInterface::CreateCustomObject ( const std::string & typeName ) const

◆ DefineCustomObjectType()

void ScriptInterface::DefineCustomObjectType	(	JSClass *	clasp,
		JSNative	constructor,
		uint	minArgs,
		JSPropertySpec *	ps,
		JSFunctionSpec *	fs,
		JSPropertySpec *	static_ps,
		JSFunctionSpec *	static_fs
	)

◆ Eval() [1/3]

bool ScriptInterface::Eval ( const char * code ) const

Evaluate some JS code in the global scope.

Returns: true on successful compilation and execution; false otherwise

◆ Eval() [2/3]

bool ScriptInterface::Eval	(	const char *	code,
		JS::MutableHandleValue	out
	)		const

◆ Eval() [3/3]

template<typename T >

bool ScriptInterface::Eval	(	const char *	code,
		T &	out
	)		const

◆ GetContext()

ScriptContext & ScriptInterface::GetContext ( ) const

◆ GetGeneralJSContext()

JSContext * ScriptInterface::GetGeneralJSContext ( ) const

GetGeneralJSContext returns the context without starting a GC request and without entering the ScriptInterface compartment.

It should only be used in specific situations, for instance when initializing a persistent rooted. If you need the compartmented context of the ScriptInterface, you should create a ScriptInterface::Request and use the context from that.

◆ GetGlobalProperty()

bool ScriptInterface::GetGlobalProperty	(	const ScriptRequest &	rq,
		const std::string &	name,
		JS::MutableHandleValue	out
	)

static

Get an object from the global scope or any lexical scope.

This can return globally accessible objects even if they are not properties of the global object (e.g. ES6 class definitions).

Parameters

name	- Name of the property.
out	The object or null.

◆ GetPrivate() [1/2]

template<typename T >

static T * ScriptInterface::GetPrivate	(	const ScriptRequest &	rq,
		JS::CallArgs &	callArgs,
		JSClass *	jsClass
	)

inlinestatic

Retrieve the private data field of a JS Object that is an instance of the given JSClass.

If an error occurs, GetPrivate will report it with the according stack.

◆ GetPrivate() [2/2]

template<typename T >

static T * ScriptInterface::GetPrivate	(	const ScriptRequest &	rq,
		JS::HandleObject	thisobj,
		JSClass *	jsClass
	)

inlinestatic

Retrieve the private data field of a JSObject that is an instance of the given JSClass.

◆ LoadGlobalScript()

bool ScriptInterface::LoadGlobalScript	(	const VfsPath &	filename,
		const std::string &	code
	)		const

Load and execute the given script in the global scope.

Parameters

filename	Name for debugging purposes (not used to load the file)
code	JS code to execute

Returns: true on successful compilation and execution; false otherwise

◆ LoadGlobalScriptFile()

bool ScriptInterface::LoadGlobalScriptFile ( const VfsPath & path ) const

Load and execute the given script in the global scope.

Returns: true on successful compilation and execution; false otherwise

◆ LoadGlobalScripts()

bool ScriptInterface::LoadGlobalScripts ( )

Load global scripts that most script interfaces need, located in the /globalscripts directory.

VFS must be initialized.

◆ LoadScript()

bool ScriptInterface::LoadScript	(	const VfsPath &	filename,
		const std::string &	code
	)		const

Load and execute the given script in a new function scope.

Parameters

filename	Name for debugging purposes (not used to load the file)
code	JS code to execute

Returns: true on successful compilation and execution; false otherwise

◆ Math_random()

bool ScriptInterface::Math_random	(	JSContext *	cx,
		uint	argc,
		JS::Value *	vp
	)

static

JSNative wrapper of the above.

◆ MathRandom()

bool ScriptInterface::MathRandom ( double & nbr ) const

Calls the random number generator assigned to this ScriptInterface instance and returns the generated number.

◆ NONCOPYABLE()

ScriptInterface::NONCOPYABLE ( ScriptInterface )

private

◆ ObjectFromCBData() [1/3]

template<>

void * ScriptInterface::ObjectFromCBData ( const ScriptRequest & rq )

static

◆ ObjectFromCBData() [2/3]

template<typename T >

static T * ScriptInterface::ObjectFromCBData ( const ScriptRequest & rq )

inlinestatic

Convert the CmptPrivate callback data to T*.

◆ ObjectFromCBData() [3/3]

template<typename T >

static T * ScriptInterface::ObjectFromCBData	(	const ScriptRequest &	rq,
		JS::CallArgs &
	)

inlinestatic

Variant for the function wrapper.

◆ ReplaceNondeterministicRNG()

bool ScriptInterface::ReplaceNondeterministicRNG ( boost::random::rand48 & rng )

Replace the default JS random number generator with a seeded, network-synced one.

◆ SetCallbackData()

void ScriptInterface::SetCallbackData ( void * pCBData )

◆ SetGlobal()

template<typename T >

bool ScriptInterface::SetGlobal	(	const char *	name,
		const T &	value,
		bool	replace = `false`,
		bool	constant = `true`,
		bool	enumerate = `true`
	)

Set the named property on the global object.

Optionally makes it {ReadOnly, DontEnum}. We do not allow to make it DontDelete, so that it can be hotloaded by deleting it and re-creating it, which is done by setting replace to true.

◆ SetGlobal_()

bool ScriptInterface::SetGlobal_	(	const char *	name,
		JS::HandleValue	value,
		bool	replace,
		bool	constant,
		bool	enumerate
	)

private

◆ SetPrototype()

bool ScriptInterface::SetPrototype	(	JS::HandleValue	obj,
		JS::HandleValue	proto
	)

Friends And Related Function Documentation

◆ ScriptRequest

friend class ScriptRequest

friend

Member Data Documentation

◆ m

std::unique_ptr<ScriptInterface_impl> ScriptInterface::m

private

◆ m_CmptPrivate

CmptPrivate ScriptInterface::m_CmptPrivate

private

◆ m_CustomObjectTypes

std::map<std::string, CustomType> ScriptInterface::m_CustomObjectTypes

private

The documentation for this class was generated from the following files:

/home/docker/jenkins/workspace/technical-docs/source/scriptinterface/ScriptInterface.h
/home/docker/jenkins/workspace/technical-docs/source/scriptinterface/ScriptInterface.cpp

Classes

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ ScriptInterface() [1/3]

◆ ScriptInterface() [2/3]

◆ ScriptInterface() [3/3]

◆ ~ScriptInterface()

Member Function Documentation

◆ CallConstructor()

◆ CreateCustomObject()

◆ DefineCustomObjectType()

◆ Eval() [1/3]

◆ Eval() [2/3]

◆ Eval() [3/3]

◆ GetContext()

◆ GetGeneralJSContext()

◆ GetGlobalProperty()

◆ GetPrivate() [1/2]

◆ GetPrivate() [2/2]

◆ LoadGlobalScript()

◆ LoadGlobalScriptFile()

◆ LoadGlobalScripts()

◆ LoadScript()

◆ Math_random()

◆ MathRandom()

◆ NONCOPYABLE()

◆ ObjectFromCBData() [1/3]

◆ ObjectFromCBData() [2/3]

◆ ObjectFromCBData() [3/3]

◆ ReplaceNondeterministicRNG()

◆ SetCallbackData()

◆ SetGlobal()

◆ SetGlobal_()

◆ SetPrototype()

Friends And Related Function Documentation

◆ ScriptRequest

Member Data Documentation

◆ m

◆ m_CmptPrivate

◆ m_CustomObjectTypes