Vuo
0.4.7
|
This class runs a composition and manages communication with a composition produced by VuoCompiler
.
It can run a composition in the current process using the newCurrentProcessRunnerFromDynamicLibrary(string dylibPath)
factory method, or in a separate process using the newSeparateProcessRunnerFromExecutable(string executablePath)
factory method.
See also the following VuoCompiler methods which compile a composition and return a VuoRunner:
VuoRunner allows a client to control the composition (start, change input port values, generate events, hibernate, stop) and receive data from the composition (output port values, uptime, node executions, edge hits).
Member functions that send control requests to the composition (pause()
, getPublishedOutputPortValue()
, etc.) are mutually thread-safe. They must be called after start()
or startPaused()
returns and before stop()
is called, but may be called concurrently with each other.
If start()
or startPaused()
is called, then stop()
must also be called.
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 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 triggering events. | |
void | unpause (void) |
Sends a control request to the composition telling it to resume generating 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, string valueAsString) |
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 generate an event on a published input port. | |
void | waitForAnyPublishedOutputPortEvent (void) |
Waits until the first event following a call to generatePublishedInputPortEvent() emerges from any published output port. | |
string | getPublishedOutputPortValue (Port *port) |
Sends a control request to the composition to get 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, string valueAsString) |
Sends a control request to the composition telling it to modify an input port's value. | |
string | getInputPortValue (string portIdentifier) |
Sends a control request to the composition to get an input port's value. | |
string | getOutputPortValue (string portIdentifier) |
Sends a control request to the composition to get an output port's value. | |
string | getInputPortSummary (string portIdentifier) |
Sends a control request to the composition to get an input port's summary. | |
string | getOutputPortSummary (string portIdentifier) |
Sends a control request to the composition to get 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 data. | |
Static Public Member Functions | |
static VuoRunner * | newSeparateProcessRunnerFromExecutable (string executablePath, bool deleteExecutableWhenFinished=false) |
Creates a runner object 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 method if your application calls dispatch_main()
, NSApplicationMain()
, or UIApplicationMain()
, or invokes a CFRunLoop
on the main thread.
Throws a std::logic_error
if this VuoRunner
was constructed with newSeparateProcessRunnerFromExecutable()
or if this function is not called on the main thread.
void VuoRunner::generatePublishedInputPortEvent | ( | VuoRunner::Port * | port | ) |
Sends a control request to the composition telling it to generate an event on a published input port.
When this method returns, the event will have been enqueued. This method clears the event flags used by waitForAnyPublishedOutputPortEvent()
.
Assumes the composition has been started, is not paused, and has not been hibernated or stopped.
string VuoRunner::getInputPortSummary | ( | string | portIdentifier | ) |
Sends a control request to the composition to get 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() ). |
string VuoRunner::getInputPortValue | ( | string | portIdentifier | ) |
Sends a control request to the composition to get an input port's value.
Assumes the composition has been started and has not been hibernated or stopped.
portIdentifier | The compile-time identifier for the port (see VuoCompilerEventPort::getIdentifier() ). |
string VuoRunner::getOutputPortSummary | ( | string | portIdentifier | ) |
Sends a control request to the composition to get 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() ). |
string VuoRunner::getOutputPortValue | ( | string | portIdentifier | ) |
Sends a control request to the composition to get an output port's value.
Assumes the composition has been started and has not been hibernated or 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.
Assumes the composition has been started and has not been hibernated or stopped.
VuoRunner::Port * VuoRunner::getPublishedInputPortWithName | ( | string | name | ) |
Returns the published input port with the given name, or NULL if no such port exists.
Assumes the composition has been started and has not been hibernated or stopped.
vector< VuoRunner::Port * > VuoRunner::getPublishedOutputPorts | ( | void | ) |
Returns the list of published output ports in the composition.
Assumes the composition has been started and has not been hibernated or stopped.
string VuoRunner::getPublishedOutputPortValue | ( | VuoRunner::Port * | port | ) |
Sends a control request to the composition to get a published output port's value.
Assumes the composition has been started and has not been hibernated or stopped.
VuoRunner::Port * VuoRunner::getPublishedOutputPortWithName | ( | string | name | ) |
Returns the published output port with the given name, or NULL if no such port exists.
Assumes the composition has been started and has not been hibernated or 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 object 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 triggering events.
When this method returns, no more events will be triggered and all events will have finished propagating through the composition.
Assumes the composition has been started, is not paused, and has not been hibernated or 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.
When this method returns, the new composition 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 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 invokes a CFRunLoop
on the main thread.
Throws a std::logic_error
if this VuoRunner
was constructed with newSeparateProcessRunnerFromExecutable()
or if this function is not called on the main thread.
void VuoRunner::setDelegate | ( | VuoRunnerDelegate * | delegate | ) |
Sets the delegate that receives telemetry data.
May be null.
void VuoRunner::setInputPortValue | ( | string | portIdentifier, |
string | valueAsString | ||
) |
Sends a control request to the composition telling it to modify an input port's value.
When this method returns, the input port value will have been modified.
Assumes the composition has been started and has not been hibernated or stopped.
portIdentifier | The compile-time identifier for the port (see VuoCompilerEventPort::getIdentifier() ). |
valueAsString | String representation of the port's new value. |
void VuoRunner::setPublishedInputPortValue | ( | VuoRunner::Port * | port, |
string | valueAsString | ||
) |
Sends a control request to the composition telling it to modify a published input port's value.
When this method returns, the input port value will have been modified.
Assumes the composition has been started and has not been hibernated or stopped.
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.
Assumes the composition has not been started.
void VuoRunner::startPaused | ( | void | ) |
Starts the composition running, but in a paused state.
Useful in conjunction with setPublishedInputPortValue()
.
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 has not been started.
void VuoRunner::stop | ( | void | ) |
Sends a control request to the composition telling it to stop.
When this method returns, the composition process will be on its way to terminating.
This method waits for any pending delegate methods 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 generating events.
Assumes the composition is paused.
void VuoRunner::waitForAnyPublishedOutputPortEvent | ( | void | ) |
Waits until the first event following a call to generatePublishedInputPortEvent()
emerges from any published output port.
Assumes the composition has been started and has not been hibernated or stopped.