A thread class to support Zuble's background Javascript processing. More...

#include <ZScriptThread.h>

Inheritance diagram for Zbl::ZScriptThread:

Collaboration diagram for Zbl::ZScriptThread:

Public Types
enum	alertConversion { UNDEFINED, INTEGER, DOUBLE, STRING, JSON }

typedef enum Zbl::ZScriptThread::alertConversion	AlertConversion

Public Slots
void	execScript (qulonglong requestID, const QString &script, QVariantMap userData=QVariantMap())
	Execute the specified javascript program fragment asynchronously in the background thread's javascript context. More...

bool	waitThreadComplete (unsigned long time=ULONG_MAX)
	Blocks the current thread until the background thread finishes running its event loop or a timeout occurrs. More...

void	start ()
	Causes the tread to start execution. More...

void	quit ()
	Causes the thread to stop processing events and exit the event loop. More...

void	sendInterruptRequest ()
	Calls the QThread::requestInterruption() method for this thread. If the thread is checking Zbl.isInterrupted() it should abort within a short period of time. More...

Signals
void	execComplete (qulonglong requestID, QVariant result, QVariant userData)
	Sent when an asynchronous background script execution has completed. More...

void	initComplete (QVariant status)
	Sent when the javascript execution environment has completed initialization and is ready for use. More...

void	beginShutdown ()
	Sent when the javascript thread is about to begin it's shutdown sequence. More...

void	finished ()
	Sent from the associated thread right before it finishes executing. More...

void	alert (const QString signalID, QVariant payload)
	Background scripts send this signal by calling the ZblApp::alert() method. More...

void	readyChanged ()
	Sent when ready property value changes. More...

void	completeChanged ()
	Sent when complete property value changes. More...

Public Member Functions
	ZScriptThread (QObject *parent=nullptr)

virtual	~ZScriptThread ()

QString	getInitScript ()

void	setInitScript (const QString &script)

QVariant	getInitError ()

bool	getReady ()

bool	getCompleted ()

Q_INVOKABLE bool	isInterrupted () const
	Calls the QThread::isInterruptionRequested() method for this thread. Can be used to determine if this thread's sendInterruptRequest() slot has been called. More...

Static Public Member Functions
static void	registerType ()
	Registers ZScriptThread as a QML type. More...

Protected Member Functions
void	onWorkerExecComplete (qulonglong requestID, QString result, QString userData)
	Receives and propagates the ZScriptWorker::execComplete signal. More...

Q_INVOKABLE void	onThreadAlert (QString signalID, QString payload, int conversion)
	Called by ZblApp in background thread to trigger ZScriptThread::alert signal in foreground thread. More...

void	onStarted ()
	Called when QThread has started running. More...

void	onFinished ()
	Called when QThread event loop has exited. More...

void	destroyThread ()
	Stops the QThread, waits for it to exit and then deletes it and the ZScriptWorker object. More...

Static Protected Member Functions
static QString	variantToJson (QVariant &var)
	Converts QVariant to json string. More...

static QVariant	jsonToVariant (const QString &json)
	Converts json string to QVariant. More...

Protected Attributes
ZBL_DECLARE_LOGGED_OBJECT QThread *	m_thread
	QThread object in which ZScriptWorker object will run. More...

ZScriptWorker *	m_worker
	Script worker object maintains this thread's javascript context. More...

QString	m_initScript
	Thread's javascript context will be initialized by running this script. More...

QVariant	m_initError
	The error message generated when running the initScript, or an empty string if initScript was successful or has not yet been executed. More...

bool	m_initReady
	true if thread initialization is complete, false otherwise More...

bool	m_threadCompleted
	true if thread has been shut down, false otherwise More...

Properties
QString	initScript
	Thread initialization script. More...

QVariant	initError
	The error message generated when executing the initScript program, or the empty string if no error was generated or the program has not yet been executed. More...

bool	ready
	True if thread is ready to run scripts, false otherwise. More...

bool	complete
	True when thread has been shut down, false otherwise. More...

Friends
class	ZblApp

Detailed Description

A thread class to support Zuble's background Javascript processing.

Zuble supports running javascript code asynchronously in a dedicated background thread. This class implements the Qt threading semantics and executes in the thread in which it is created.

ZScriptThread encapsulates a ZScriptWorker object that executes in a dedicated background thread and holds a separate javascript engine and runtime state. This state is kept alive until the ZScriptThread object is destroyed.

ZScriptThread objects maintain their javascript global state across calls to execScript. This allows background scripts to be stateful at the expense of maintaining a dedicated thread.

Initialization of the background Javascript global scope is performed by Zbl::ZScriptWorker

Definition at line 62 of file ZScriptThread.h.

Member Typedef Documentation

◆ AlertConversion

typedef enum Zbl::ZScriptThread::alertConversion Zbl::ZScriptThread::AlertConversion

Member Enumeration Documentation

◆ alertConversion

enum Zbl::ZScriptThread::alertConversion

Enumerator
UNDEFINED
INTEGER
DOUBLE
STRING
JSON

Definition at line 69 of file ZScriptThread.h.

Constructor & Destructor Documentation

◆ ZScriptThread()

Zbl::ZScriptThread::ZScriptThread ( QObject * parent = nullptr )

explicit

Definition at line 39 of file ZScriptThread.cpp.

◆ ~ZScriptThread()

Zbl::ZScriptThread::~ZScriptThread ( )

virtual

Definition at line 64 of file ZScriptThread.cpp.

Member Function Documentation

◆ alert

void Zbl::ZScriptThread::alert	(	const QString	signalID,
		QVariant	payload
	)

signal

Background scripts send this signal by calling the ZblApp::alert() method.

example: Zbl.alert('mySignal',{what: 'some data...'})

Parameters

signalID	thread-specific signal identifier
payload	thread-specific signal data

Referenced by onThreadAlert().

◆ beginShutdown

void Zbl::ZScriptThread::beginShutdown ( )

signal

Sent when the javascript thread is about to begin it's shutdown sequence.

◆ completeChanged

void Zbl::ZScriptThread::completeChanged ( )

signal

Sent when complete property value changes.

Referenced by onFinished().

◆ destroyThread()

void Zbl::ZScriptThread::destroyThread ( )

protected

Stops the QThread, waits for it to exit and then deletes it and the ZScriptWorker object.

Definition at line 71 of file ZScriptThread.cpp.

Referenced by ~ZScriptThread().

◆ execComplete

void Zbl::ZScriptThread::execComplete	(	qulonglong	requestID,
		QVariant	result,
		QVariant	userData
	)

signal

Sent when an asynchronous background script execution has completed.

This signal is issued once for each call to execScript.

Parameters

result The result of the script execution. Use result.isError() to determine if a javascript exception was thrown.

Referenced by onWorkerExecComplete().

◆ execScript

void Zbl::ZScriptThread::execScript	(	qulonglong	requestID,
		const QString &	script,
		QVariantMap	userData = `QVariantMap()`
	)

slot

Execute the specified javascript program fragment asynchronously in the background thread's javascript context.

The current thread will return immediately. Use the execComplete signal to determine when background thread has finished program execution.

Parameters

requestID	A user-defined integer value that is returned with the execComplete signal associated with script execution.
script	The program fragment to run in the background
userData	A javascript object that will be copied to the background thread prior to script execution. Properties of this object will be available to the background script. A copy is returned in the associated execComplete signal.

Definition at line 173 of file ZScriptThread.cpp.

Referenced by start().

◆ finished

void Zbl::ZScriptThread::finished ( )

signal

Sent from the associated thread right before it finishes executing.

Referenced by onFinished().

◆ getCompleted()

bool Zbl::ZScriptThread::getCompleted ( )

Definition at line 125 of file ZScriptThread.cpp.

◆ getInitError()

QVariant Zbl::ZScriptThread::getInitError ( )

Definition at line 115 of file ZScriptThread.cpp.

◆ getInitScript()

QString Zbl::ZScriptThread::getInitScript ( )

Definition at line 101 of file ZScriptThread.cpp.

◆ getReady()

bool Zbl::ZScriptThread::getReady ( )

Definition at line 120 of file ZScriptThread.cpp.

◆ initComplete

void Zbl::ZScriptThread::initComplete ( QVariant status )

signal

Sent when the javascript execution environment has completed initialization and is ready for use.

Referenced by onStarted(), and onWorkerExecComplete().

◆ isInterrupted()

bool Zbl::ZScriptThread::isInterrupted ( ) const

Calls the QThread::isInterruptionRequested() method for this thread. Can be used to determine if this thread's sendInterruptRequest() slot has been called.

See also: Zbl::ZblApp::isInterrupted()

Definition at line 303 of file ZScriptThread.cpp.

◆ jsonToVariant()

QVariant Zbl::ZScriptThread::jsonToVariant ( const QString & json )

staticprotected

Converts json string to QVariant.

Parameters

json

Returns

Definition at line 359 of file ZScriptThread.cpp.

Referenced by onThreadAlert(), and onWorkerExecComplete().

◆ onFinished()

void Zbl::ZScriptThread::onFinished ( )

protected

Called when QThread event loop has exited.

Definition at line 283 of file ZScriptThread.cpp.

Referenced by ZScriptThread().

◆ onStarted()

void Zbl::ZScriptThread::onStarted ( )

protected

Called when QThread has started running.

Definition at line 266 of file ZScriptThread.cpp.

Referenced by ZScriptThread().

◆ onThreadAlert()

void Zbl::ZScriptThread::onThreadAlert	(	QString	signalID,
		QString	payload,
		int	conversion
	)

protected

Called by ZblApp in background thread to trigger ZScriptThread::alert signal in foreground thread.

Should be called with QMetaObject::invokeMethod Qt request and Qt::QueuedConnection or Qt::BlockingQueuedConnection type only.

Parameters

signalID	User-defined signal identifier
payload	User-defined JSON string that will be passed to ZScriptThread::alert listeners as a JSON object.
conversion	A ZScriptThread::AlertConversion value

Definition at line 215 of file ZScriptThread.cpp.

◆ onWorkerExecComplete()

void Zbl::ZScriptThread::onWorkerExecComplete	(	qulonglong	requestID,
		QString	result,
		QString	userData
	)

protected

Receives and propagates the ZScriptWorker::execComplete signal.

This signal is issued once for each call to ZScriptWorker::execScript.

Parameters

result The result of the script execution. Use result.isError() to determine if a javascript exception was thrown.

Definition at line 194 of file ZScriptThread.cpp.

Referenced by ZScriptThread().

◆ quit

void Zbl::ZScriptThread::quit ( )

slot

Causes the thread to stop processing events and exit the event loop.

Definition at line 163 of file ZScriptThread.cpp.

◆ readyChanged

void Zbl::ZScriptThread::readyChanged ( )

signal

Sent when ready property value changes.

Referenced by destroyThread(), onFinished(), onStarted(), and onWorkerExecComplete().

◆ registerType()

void Zbl::ZScriptThread::registerType ( )

static

Registers ZScriptThread as a QML type.

Definition at line 345 of file ZScriptThread.cpp.

Referenced by Zbl::Zblcore::registerTypes().

◆ sendInterruptRequest

void Zbl::ZScriptThread::sendInterruptRequest ( )

slot

Calls the QThread::requestInterruption() method for this thread. If the thread is checking Zbl.isInterrupted() it should abort within a short period of time.

Definition at line 311 of file ZScriptThread.cpp.

◆ setInitScript()

void Zbl::ZScriptThread::setInitScript ( const QString & script )

Definition at line 106 of file ZScriptThread.cpp.

◆ start

void Zbl::ZScriptThread::start ( )

slot

Causes the tread to start execution.

After a brief setup the thread enters its event loop and starts processing events.

Definition at line 130 of file ZScriptThread.cpp.

◆ variantToJson()

QString Zbl::ZScriptThread::variantToJson ( QVariant & var )

staticprotected

Converts QVariant to json string.

Parameters

var

Returns

Definition at line 352 of file ZScriptThread.cpp.

Referenced by Zbl::ZblApp::alert(), and execScript().

◆ waitThreadComplete

bool Zbl::ZScriptThread::waitThreadComplete ( unsigned long time = ULONG_MAX )

slot

Blocks the current thread until the background thread finishes running its event loop or a timeout occurrs.

Parameters

time	number of milliseconds to wait

Returns: true if thread finished successfully, false if thread wait timeout was exceeded

Definition at line 316 of file ZScriptThread.cpp.

Referenced by destroyThread().

Friends And Related Function Documentation

◆ ZblApp

friend class ZblApp

friend

Definition at line 64 of file ZScriptThread.h.

Member Data Documentation

◆ m_initError

QVariant Zbl::ZScriptThread::m_initError

protected

The error message generated when running the initScript, or an empty string if initScript was successful or has not yet been executed.

Definition at line 375 of file ZScriptThread.h.

Referenced by getInitError(), and onWorkerExecComplete().

◆ m_initReady

bool Zbl::ZScriptThread::m_initReady

protected

true if thread initialization is complete, false otherwise

Definition at line 381 of file ZScriptThread.h.

Referenced by destroyThread(), getReady(), onFinished(), onStarted(), onWorkerExecComplete(), setInitScript(), and start().

◆ m_initScript

QString Zbl::ZScriptThread::m_initScript

protected

Thread's javascript context will be initialized by running this script.

The thread will run this javacscript program once the first time start is called. Errors are reported in m_initError.

Definition at line 368 of file ZScriptThread.h.

Referenced by getInitScript(), onStarted(), onWorkerExecComplete(), setInitScript(), and start().

◆ m_thread

ZBL_DECLARE_LOGGED_OBJECT QThread* Zbl::ZScriptThread::m_thread

protected

QThread object in which ZScriptWorker object will run.

Definition at line 351 of file ZScriptThread.h.

Referenced by destroyThread(), execScript(), isInterrupted(), onFinished(), onStarted(), quit(), sendInterruptRequest(), start(), and waitThreadComplete().

◆ m_threadCompleted

bool Zbl::ZScriptThread::m_threadCompleted

protected

true if thread has been shut down, false otherwise

Definition at line 387 of file ZScriptThread.h.

Referenced by getCompleted(), and onFinished().

◆ m_worker

ZScriptWorker* Zbl::ZScriptThread::m_worker

protected

Script worker object maintains this thread's javascript context.

Definition at line 358 of file ZScriptThread.h.

Referenced by destroyThread(), and execScript().

Property Documentation

◆ complete

bool Zbl::ZScriptThread::complete

read

True when thread has been shut down, false otherwise.

This flag is set when the thread's internal message pump has been shut down.

Definition at line 131 of file ZScriptThread.h.

◆ initError

QVariant Zbl::ZScriptThread::initError

read

The error message generated when executing the initScript program, or the empty string if no error was generated or the program has not yet been executed.

Definition at line 112 of file ZScriptThread.h.

◆ initScript

QString Zbl::ZScriptThread::initScript

readwrite

Thread initialization script.

Assign to this property a javascript initialization program that will be executed once by the background script engine the first time ZScriptThread::start() is called on this object. The value may not be changed after start() is called.

TBD: if a url is supplied load the corresponding javascript file instead of executing string as a program

Definition at line 104 of file ZScriptThread.h.

◆ ready

bool Zbl::ZScriptThread::ready

read

True if thread is ready to run scripts, false otherwise.

This flag is set when QThread and initScript initialization have completed execution and cleared when the thread's internal message pump is about to shut down.

Definition at line 123 of file ZScriptThread.h.

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

zblcore/ZScriptThread.h
zblcore/ZScriptThread.cpp

Public Types

Public Slots

Signals

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Properties

Friends

Detailed Description

Member Typedef Documentation

◆ AlertConversion

Member Enumeration Documentation

◆ alertConversion

Constructor & Destructor Documentation

◆ ZScriptThread()

◆ ~ZScriptThread()

Member Function Documentation

◆ alert

◆ beginShutdown

◆ completeChanged

◆ destroyThread()

◆ execComplete

◆ execScript

◆ finished

◆ getCompleted()

◆ getInitError()

◆ getInitScript()

◆ getReady()

◆ initComplete

◆ isInterrupted()

◆ jsonToVariant()

◆ onFinished()

◆ onStarted()

◆ onThreadAlert()

◆ onWorkerExecComplete()

◆ quit

◆ readyChanged

◆ registerType()

◆ sendInterruptRequest

◆ setInitScript()

◆ start

◆ variantToJson()

◆ waitThreadComplete

Friends And Related Function Documentation

◆ ZblApp

Member Data Documentation

◆ m_initError

◆ m_initReady

◆ m_initScript

◆ m_thread

◆ m_threadCompleted

◆ m_worker

Property Documentation

◆ complete

◆ initError

◆ initScript

◆ ready