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).
start()
, startPaused()
, and any member functions that send control requests to the graph are not mutually thread-safe. They must not be executed concurrently.
If start()
or startPaused()
is called, then stop()
must also be called.
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 generating events. | |
void | unpause (void) |
Sends a control request to the graph telling it to resume generating events. | |
void | hibernate (void) |
Sends a control request to the graph telling it to hibernate. | |
void | stop (void) |
Sends a control request to the graph telling it to stop. | |
void | waitUntilStopped (void) |
Waits until the composition is stopped. | |
void | setInputPortValue (string portIdentifier, string valueAsString) |
Sends a control request to the graph telling it to modify an input port's value. | |
string | getOutputPortValue (string portIdentifier) |
Sends a control request to the graph to get an output port's value. | |
void | setPublishedInputPortValue (VuoPublishedPort *port, string valueAsString) |
Sends a control request to the graph telling it to modify a published input port's value. | |
void | generatePublishedInputPortEvent (VuoPublishedPort *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 (VuoPublishedPort *port) |
Sends a control request to the graph to get a published output port's value. | |
vector< VuoPublishedPort * > | getPublishedInputPorts (void) |
Returns the list of published input ports in the graph. | |
vector< VuoPublishedPort * > | getPublishedOutputPorts (void) |
Returns the list of published output ports in the graph. | |
VuoPublishedPort * | getPublishedInputPortWithName (string name) |
Returns the published input port with the given name, or NULL if no such port exists. | |
VuoPublishedPort * | getPublishedOutputPortWithName (string name) |
Returns the published output port with the given name, or NULL if no such port exists. | |
string | getExecutablePath (void) |
Returns the path to the linked graph executable, or the empty string if this object was constructed without an executable. | |
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) |
Creates a runner object that can run a graph in a new process. | |
static VuoRunner * | newCurrentProcessRunnerFromDynamicLibrary (string dylibPath) |
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 | ( | VuoPublishedPort * | 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::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. |
vector< VuoPublishedPort * > 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.
VuoPublishedPort * 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< VuoPublishedPort * > 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 | ( | VuoPublishedPort * | 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.
VuoPublishedPort * 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.
void VuoRunner::hibernate | ( | void | ) |
Sends a control request to the graph telling it to hibernate.
When this method returns, the graph will be hibernating unless the graph process has crashed.
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() . |
|
static |
Creates a runner object that can run a graph in a new process.
executablePath | A linked graph executable, produced by VuoCompiler::linkGraphIntoExecutable() . |
void VuoRunner::pause | ( | void | ) |
Sends a control request to the graph telling it to cease generating events.
When this method returns, event generation will have ceased. Events that were already in progress will, however, continue to traverse the graph.
Assumes the graph has been started, is not paused, and has not been hibernated or stopped.
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. |
valueAsString | String representation of the port's new value. |
void VuoRunner::setPublishedInputPortValue | ( | VuoPublishedPort * | 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.