Vuo
0.4.3
|
This class runs a graph and manages communication with a graph produced by VuoCompiler
.
It can run a graph 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 graph and return a VuoRunner:
VuoRunner allows a client to control the graph (start, change input port values, generate events, hibernate, stop) and receive data from the graph (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 graph. More... | |
Public Member Functions | |
~VuoRunner (void) | |
Destructor. | |
void | start (void) |
Starts the graph running. | |
void | startPaused (void) |
Starts the graph 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 graph telling it to cease triggering events. | |
void | unpause (void) |
Sends a control request to the graph telling it to resume generating events. | |
void | replaceComposition (string compositionDylibPath, 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 graph 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 graph telling it to modify a published input port's value. | |
void | generatePublishedInputPortEvent (Port *port) |
Sends a control request to the graph 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 graph to get a published output port's value. | |
vector< Port * > | getPublishedInputPorts (void) |
Returns the list of published input ports in the graph. | |
vector< Port * > | getPublishedOutputPorts (void) |
Returns the list of published output ports in the graph. | |
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 graph telling it to modify an input port's value. | |
string | getInputPortValue (string portIdentifier) |
Sends a control request to the graph to get an input port's value. | |
string | getOutputPortValue (string portIdentifier) |
Sends a control request to the graph 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 graph 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 graph in a new process. | |
static VuoRunner * | newSeparateProcessRunnerFromDynamicLibrary (string compositionLoaderPath, string compositionDylibPath, string resourcesDylibPath, 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 graph in the current process. | |
VuoRunner::~VuoRunner | ( | void | ) |
Destructor.
Assumes the graph 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 graph 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 graph 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 graph 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 graph to get an input port's value.
Assumes the graph 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 graph to get an output port's value.
Assumes the graph 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 graph.
Assumes the graph 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 graph 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 graph.
Assumes the graph has been started and has not been hibernated or stopped.
string VuoRunner::getPublishedOutputPortValue | ( | VuoRunner::Port * | port | ) |
Sends a control request to the graph to get a published output port's value.
Assumes the graph 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 graph has been started and has not been hibernated or stopped.
|
static |
Creates a runner object that can run a graph in the current process.
dylibPath | A linked graph dynamic library, produced by VuoCompiler::linkGraphIntoDynamicLibrary() . |
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() . |
resourcesDylibPath | A linked resources dynamic library, produced by VuoCompiler::linkCompositionToCreateDynamicLibraries() . |
deleteDylibsWhenFinished | True if the runner should delete compositionDylibPath and resourcesDylibPath when it's finished using the files. |
|
static |
Creates a runner object that can run a graph in a new process.
executablePath | A linked graph executable, produced by VuoCompiler::linkGraphIntoExecutable() . |
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 graph 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 graph has been started, is not paused, and has not been hibernated or stopped.
void VuoRunner::replaceComposition | ( | string | compositionDylibPath, |
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::linkGraphIntoDynamicLibrary() . |
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 graph telling it to modify an input port's value.
When this method returns, the input port value will have been modified.
Assumes the graph 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 graph telling it to modify a published input port's value.
When this method returns, the input port value will have been modified.
Assumes the graph has been started and has not been hibernated or stopped.
void VuoRunner::start | ( | void | ) |
Starts the graph running.
If running the graph 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 graph.
If running the graph in a separate process, no further calls are needed.
Assumes the graph has not been started.
void VuoRunner::startPaused | ( | void | ) |
Starts the graph running, but in a paused state.
Useful in conjunction with setPublishedInputPortValue()
.
If running the graph 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 graph.
If running the graph in a separate process, no further calls are needed.
Assumes the graph has not been started.
void VuoRunner::stop | ( | void | ) |
Sends a control request to the graph telling it to stop.
When this method returns, the graph process will be on its way to terminating.
This method waits for any pending delegate methods to return.
Assumes the graph has been started and has not been stopped.
void VuoRunner::unpause | ( | void | ) |
Sends a control request to the graph telling it to resume generating events.
Assumes the graph is paused.
void VuoRunner::waitForAnyPublishedOutputPortEvent | ( | void | ) |
Waits until the first event following a call to generatePublishedInputPortEvent()
emerges from any published output port.
Assumes the graph has been started and has not been hibernated or stopped.