Background Script Threads
Zuble provides a mechanism to pass Javascript code to background threads for processing. This allows QML applications to perform background I/O operations. Each Zuble background thread has its own QJSEngine object, javascript context, and Zbl object that provides a set of methods for creating instances of Zuble core and sprocket QML objects for background threads to use.
ZScriptThread and ZScriptWorker objects
The ZScripThread object encapsulates a background QThread object and a ZScriptWorker object that contains its own QJSEngine and Zbl objects. The ZScriptThread object runs in the creator's thread while the ZScriptWorker object runs in the background QThread. Javascript code sent from the creator thread will be executed in the background QThread.
execScript signal
The ZScriptThread.execScript() signal is used to send Javascript code fragments to the ZScriptWorker object for background processing. Each call to execScript results in an associated execComplete signal returned from the ZScriptThread object when execution of the background script has completed. execScript accepts three arguments:
- A number representing the execution ID. It will be returned with the results of the javascript code execution in the associated execComplete signal.
- A string containing the javascript code to be executed in the background thread.
- A javascript data object that will be copied to the background thread. Note that this object is passed in JSON string format.
execComplete signal
The ZScriptThread.execComplete signal is received for each call to ZScriptThread.execScript(). It passes the following parameters:
- requestID: A number representing the execution ID that was passed in the originating execScript signal. This number can be used to associate execComplete signals with their originating execScript sigals or to re-sequence an asynchronous result stream.
- result: A javascript object containing the results of the background code execution. Note that this object is passed in JSON string format.
- userData: A copy of the javascript data object that was passed in the originating execScript signal. Contents may have been modified by the script. Note that this object is passed in JSON string format. This object can be used to preserve execution context between calls to execScript.
The result of the execution must be either an object or an array of strings in order for JSON conversion to succeed. Background script functions should return one of these. The value will be undefined if JSON conversion fails or if no result is returned by the script.
Core Objects
Background scripts create Zuble core objects by calling the appropriate "Zbl.new..." methods. Call Zbl.newFile(), for example, to create a new ZFile object.
Sprocket Objects
Background scripts create Zuble sprocket objects by first calling the Zbl.import() method once to load the Sprocket into the thread's object factory, then calling the Zbl.newObject() method for each new instance of the Sprocket object to be created.
Zbl.import() takes the following arguments:
- A URI string identifying the Sprocket
- Major version of the Sprocket
- Minor version of the Sprocket
Zbl.newObject() takes the following arguments:
- A URI string identifying the Sprocket
- A name string identifying the object to create
Timers
The Zbl object provides timers for background threads. Pass a function to the Zbl.startTimerInterval() method and it will be called appropriately. Zbl.stopTimerInterval() will stop timers individually. Zbl.stopAllTimers() will stop all Zbl timers for this thread.
Zbl.startTimerInterval() takes the following arguments:
- A javascript function to be called at the specified timer interval
- An argument to be passed to the function each time it is called
- Millliseconds interval between function calls
Alerts
Background script theads can send signals to their containing ZScriptThread objects by calling the Zbl.alert() method. It takes the following arguments:
- A string identifying the signal
- A javascript object to be passed to signal listeners
- A boolean value, false to send a queued alert and return immediately, true to send a blocking queued alert and wait until ZScriptThread::alert signal handlers have processed the alert (default value = false)
Originating threads connect signal handlers to the ZScriptThread::alert signal to receive alerts from background threads.