Vuo
0.4.9
|
This class runs and controls a composition that has been compiled and linked by VuoCompiler.
The composition can run in the same process as the VuoRunner or in a separate process, depending on how the VuoRunner is constructed.
To construct a VuoRunner, use one of the factory methods:
To start a composition running, call start() or startPaused(). To stop the composition, call stop(). The composition must be stopped by the time VuoRunner's destructor is called. If the composition process ends on its own, the VuoRunner detects this and stops itself.
While the composition is running, the VuoRunner can control it by sending control request messages to it. The VuoRunner functions that send control request messages must only be called while the composition is running. They are mutually thread-safe, so they may be called concurrently with each other. These functions include:
While the composition is running, the VuoRunner receives telemetry messages from it. To receive notifications of these messages, create a class that inherits from VuoRunnerDelegate, and call VuoRunner::setDelegate().
Classes | |
class | Port |
This class represents a published port in a composition. More... | |
Public Member Functions | |
~VuoRunner (void) | |
Destructor. | |
void | start (void) |
Starts the composition running. | |
void | startPaused (void) |
Starts the composition running, but in a paused state. | |
void | runOnMainThread (void) |
For a composition in the current process, runs the composition on the main thread until it stops (either on its own or from a call to stop() on another thread). | |
void | drainMainDispatchQueue (void) |
For a composition in the current process, briefly performs work that requires the main thread (such as Cocoa event handling). | |
void | pause (void) |
Sends a control request to the composition telling it to cease firing events. | |
void | unpause (void) |
Sends a control request to the composition telling it to resume firing events. | |
void | replaceComposition (string compositionDylibPath, string resourceDylibPath, string compositionDiff) |
Sends a control request to the composition loader telling it to load an updated version of the running composition. | |
void | stop (void) |
Sends a control request to the composition telling it to stop. | |
void | waitUntilStopped (void) |
Waits until the composition is stopped. | |
void | setPublishedInputPortValue (Port *port, json_object *value) |
Sends a control request to the composition telling it to modify a published input port's value. | |
void | generatePublishedInputPortEvent (Port *port) |
Sends a control request to the composition telling it to fire an event into a published input port. | |
void | waitForAnyPublishedOutputPortEvent (void) |
Waits until the first event following a call to generatePublishedInputPortEvent() comes out of any published output port. | |
json_object * | getPublishedOutputPortValue (Port *port) |
Sends a control request to the composition telling it to retrieve a published output port's value. | |
vector< Port * > | getPublishedInputPorts (void) |
Returns the list of published input ports in the composition. | |
vector< Port * > | getPublishedOutputPorts (void) |
Returns the list of published output ports in the composition. | |
Port * | getPublishedInputPortWithName (string name) |
Returns the published input port with the given name, or NULL if no such port exists. | |
Port * | getPublishedOutputPortWithName (string name) |
Returns the published output port with the given name, or NULL if no such port exists. | |
void | setInputPortValue (string portIdentifier, json_object *value) |
Sends a control request to the composition telling it to modify an input port's value. | |
json_object * | getInputPortValue (string portIdentifier) |
Sends a control request to the composition telling it to retrieve an input port's value. | |
json_object * | getOutputPortValue (string portIdentifier) |
Sends a control request to the composition telling it to retrieve an output port's value. | |
string | getInputPortSummary (string portIdentifier) |
Sends a control request to the composition telling it to retrieve an input port's summary. | |
string | getOutputPortSummary (string portIdentifier) |
Sends a control request to the composition telling it to retrieve an output port's summary. | |
bool | isStopped (void) |
Returns true if the composition either has not been started or has been started and stopped. | |
void | setDelegate (VuoRunnerDelegate *delegate) |
Sets the delegate that receives telemetry messages from the running composition. | |
Static Public Member Functions | |
static VuoRunner * | newSeparateProcessRunnerFromExecutable (string executablePath, bool deleteExecutableWhenFinished=false) |
Creates a runner that can run a composition in a new process. | |
static VuoRunner * | newSeparateProcessRunnerFromDynamicLibrary (string compositionLoaderPath, string compositionDylibPath, string resourceDylibPath, bool deleteDylibsWhenFinished=false) |
Creates a runner object that can run a composition in a new process and replace the composition with a new version while it's running. | |
static VuoRunner * | newCurrentProcessRunnerFromDynamicLibrary (string dylibPath, bool deleteDylibWhenFinished=false) |
Creates a runner object that can run a composition in the current process. | |
Friends | |
class | TestVuoRunner |
VuoRunner::~VuoRunner | ( | void | ) |
Destructor.
Assumes the composition either has not been started or has been started and stopped.
void VuoRunner::drainMainDispatchQueue | ( | void | ) |
For a composition in the current process, briefly performs work that requires the main thread (such as Cocoa event handling).
Repeated calls to this function allow the composition to run without taking over the main thread like runOnMainThread() does.
Start calling this function after start() or startPaused().
There's no need to call this function if your application calls dispatch_main()
, NSApplicationMain()
, or UIApplicationMain()
, or if it invokes a CFRunLoop
on the main thread.
Throws a std::logic_error
if this runner was not constructed to run the composition in the current process or if this function was not called on the main thread.
void VuoRunner::generatePublishedInputPortEvent | ( | VuoRunner::Port * | port | ) |
Sends a control request to the composition telling it to fire an event into a published input port.
Upon return, the event will have been fired.
Assumes the composition has been started, is not paused, and has not been stopped.
string VuoRunner::getInputPortSummary | ( | string | portIdentifier | ) |
Sends a control request to the composition telling it to retrieve an input port's summary.
Assumes the composition has been started and has not been stopped.
portIdentifier | The compile-time identifier for the port (see VuoCompilerEventPort::getIdentifier()). |
json_object * VuoRunner::getInputPortValue | ( | string | portIdentifier | ) |
Sends a control request to the composition telling it to retrieve an input port's value.
Assumes the composition has been started and has not been stopped.
portIdentifier | The compile-time identifier for the port (see VuoCompilerEventPort::getIdentifier()). |
string VuoRunner::getOutputPortSummary | ( | string | portIdentifier | ) |
Sends a control request to the composition telling it to retrieve an output port's summary.
Assumes the composition has been started and has not been stopped.
portIdentifier | The compile-time identifier for the port (see VuoCompilerEventPort::getIdentifier()). |
json_object * VuoRunner::getOutputPortValue | ( | string | portIdentifier | ) |
Sends a control request to the composition telling it to retrieve an output port's value.
Assumes the composition has been started and has not been stopped.
portIdentifier | The compile-time identifier for the port (see VuoCompilerEventPort::getIdentifier()). |
vector< VuoRunner::Port * > VuoRunner::getPublishedInputPorts | ( | void | ) |
Returns the list of published input ports in the composition.
This function may either send a control request to the composition or use cached values.
Assumes the composition has been started and has not been stopped.
VuoRunner::Port * VuoRunner::getPublishedInputPortWithName | ( | string | name | ) |
Returns the published input port with the given name, or NULL if no such port exists.
This function may either send a control request to the composition or use cached values.
Assumes the composition has been started and has not been stopped.
vector< VuoRunner::Port * > VuoRunner::getPublishedOutputPorts | ( | void | ) |
Returns the list of published output ports in the composition.
This function may either send a control request to the composition or use cached values.
Assumes the composition has been started and has not been stopped.
json_object * VuoRunner::getPublishedOutputPortValue | ( | VuoRunner::Port * | port | ) |
Sends a control request to the composition telling it to retrieve a published output port's value.
Assumes the composition has been started and has not been stopped.
port | The published output port. |
VuoRunner::Port * VuoRunner::getPublishedOutputPortWithName | ( | string | name | ) |
Returns the published output port with the given name, or NULL if no such port exists.
This function may either send a control request to the composition or use cached values.
Assumes the composition has been started and has not been stopped.
bool VuoRunner::isStopped | ( | void | ) |
Returns true if the composition either has not been started or has been started and stopped.
|
static |
Creates a runner object that can run a composition in the current process.
dylibPath | A linked composition dynamic library, produced by VuoCompiler::linkCompositionToCreateDynamicLibrary(). |
deleteDylibWhenFinished | True if the runner should delete dylibPath when it's finished using the file. |
|
static |
Creates a runner object that can run a composition in a new process and replace the composition with a new version while it's running.
compositionLoaderPath | The VuoCompositionLoader executable. |
compositionDylibPath | A linked composition dynamic library, produced by VuoCompiler::linkCompositionToCreateDynamicLibraries(). |
resourceDylibPath | A linked resource dynamic library, produced by the first call to VuoCompiler::linkCompositionToCreateDynamicLibraries() for this runner. |
deleteDylibsWhenFinished | True if the runner should delete compositionDylibPath and resourceDylibPath when it's finished using the files. |
|
static |
Creates a runner that can run a composition in a new process.
executablePath | A linked composition executable, produced by VuoCompiler::linkCompositionToCreateExecutable(). |
deleteExecutableWhenFinished | True if the runner should delete executablePath when it's finished using the file. |
void VuoRunner::pause | ( | void | ) |
Sends a control request to the composition telling it to cease firing events.
Upon return, no more events will be fired and all events will have finished propagating through the composition.
Assumes the composition has been started, is not paused, and has not been stopped.
void VuoRunner::replaceComposition | ( | string | compositionDylibPath, |
string | resourceDylibPath, | ||
string | compositionDiff | ||
) |
Sends a control request to the composition loader telling it to load an updated version of the running composition.
Upon return, the old version of the composition will have stopped and the updated version will have started.
Assumes the composition loader has been started and has not been stopped.
compositionDylibPath | A linked composition dynamic library, produced by VuoCompiler::linkCompositionToCreateDynamicLibrary(). |
resourceDylibPath | A linked resource dynamic library, produced by a call to VuoCompiler::linkCompositionToCreateDynamicLibraries() for this runner. Pass an empty string if no linked resource dynamic library was created. |
compositionDiff | A comparison of the old and new compositions, produced by VuoCompilerComposition::diffAgainstOlderComposition(). |
void VuoRunner::runOnMainThread | ( | void | ) |
For a composition in the current process, runs the composition on the main thread until it stops (either on its own or from a call to stop() on another thread).
Call this function after start() or startPaused().
There's no need to call this function if your application calls dispatch_main()
, NSApplicationMain()
, or UIApplicationMain()
, or if it invokes a CFRunLoop
on the main thread.
Throws a std::logic_error
if this runner was not constructed to run the composition in the current process or if this function was not called on the main thread.
void VuoRunner::setDelegate | ( | VuoRunnerDelegate * | delegate | ) |
Sets the delegate that receives telemetry messages from the running composition.
May be null.
void VuoRunner::setInputPortValue | ( | string | portIdentifier, |
json_object * | value | ||
) |
Sends a control request to the composition telling it to modify an input port's value.
Upon return, the input port value will have been modified.
Assumes the composition has been started and has not been stopped.
portIdentifier | The compile-time identifier for the port (see VuoCompilerEventPort::getIdentifier()). |
value | JSON representation of the port's new value. |
void VuoRunner::setPublishedInputPortValue | ( | VuoRunner::Port * | port, |
json_object * | value | ||
) |
Sends a control request to the composition telling it to modify a published input port's value.
Upon return, the published input port value will have been modified.
Assumes the composition has been started and has not been stopped.
port | The published input port. |
value | JSON representation of the port's new value. |
void VuoRunner::start | ( | void | ) |
Starts the composition running.
If running the composition in the current process, a call to this method must be followed by either a call to runOnMainThread() or repeated calls to drainMainDispatchQueue() in order to run the composition.
If running the composition in a separate process, no further calls are needed to run the composition.
Assumes the composition is not already running.
void VuoRunner::startPaused | ( | void | ) |
Starts the composition running, but in a paused state.
This is useful if you want to call setPublishedInputPortValue() before the composition begins firing events. To unpause the composition, call unpause().
If running the composition in the current process, a call to this method must be followed by either a call to runOnMainThread() or repeated calls to drainMainDispatchQueue() in order to run the composition.
If running the composition in a separate process, no further calls are needed.
Assumes the composition is not already running.
void VuoRunner::stop | ( | void | ) |
Sends a control request to the composition telling it to stop.
Upon return, the composition will have stopped. If the composition was running in a separate process, that process will have ended.
If the composition has already stopped on its own, this function skips sending the control request. It just performs some cleanup.
This function waits for any pending VuoRunnerDelegate function calls to return.
Assumes the composition has been started and has not been stopped.
void VuoRunner::unpause | ( | void | ) |
Sends a control request to the composition telling it to resume firing events.
Assumes the composition is paused.
void VuoRunner::waitForAnyPublishedOutputPortEvent | ( | void | ) |
Waits until the first event following a call to generatePublishedInputPortEvent() comes out of any published output port.
The event that comes out may not be the same as the one fired by generatePublishedInputPortEvent() if the composition contains trigger ports. The event also may not be finished traveling through the composition if the composition contains a branch where the event travels through multiple parts of the composition concurrently.
Assumes the composition has been started and has not been stopped.
void VuoRunner::waitUntilStopped | ( | void | ) |
Waits until the composition is stopped.
If the composition is already stopped, this function returns immediately.