Vuo  0.4.1
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Classes | Public Member Functions | Static Public Member Functions | List of all members
VuoRunner Class Reference

Description

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.

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 generating 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.
 
PortgetPublishedInputPortWithName (string name)
 Returns the published input port with the given name, or NULL if no such port exists.
 
PortgetPublishedOutputPortWithName (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.
 
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 VuoRunnernewSeparateProcessRunnerFromExecutable (string executablePath, bool deleteExecutableWhenFinished=false)
 Creates a runner object that can run a graph in a new process.
 
static VuoRunnernewSeparateProcessRunnerFromDynamicLibrary (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 VuoRunnernewCurrentProcessRunnerFromDynamicLibrary (string dylibPath, bool deleteDylibWhenFinished=false)
 Creates a runner object that can run a graph in the current process.
 

Constructor & Destructor Documentation

VuoRunner::~VuoRunner ( void  )

Destructor.

Assumes the graph either has not been started or has been started and stopped.

Member Function Documentation

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.

Example:
runner->start();
while (! runner->isStopped())
{
// do other work on the main thread
}
See Also
runOnMainThread(), an alternative to this method.
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::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.

Parameters
portIdentifierThe compile-time identifier for the port (see VuoCompilerEventPort::getIdentifier()).
Returns
String representation of the port's value.
See Also
Built-in Types for information about types and serialization.
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.

Parameters
portIdentifierThe compile-time identifier for the port (see VuoCompilerEventPort::getIdentifier()).
Returns
String representation of the port's value.
See Also
Built-in Types for information about types and serialization.
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.

See Also
Built-in Types for information about types and serialization.
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.

VuoRunner * VuoRunner::newCurrentProcessRunnerFromDynamicLibrary ( string  dylibPath,
bool  deleteDylibWhenFinished = false 
)
static

Creates a runner object that can run a graph in the current process.

Parameters
dylibPathA linked graph dynamic library, produced by VuoCompiler::linkGraphIntoDynamicLibrary().
deleteDylibWhenFinishedTrue if the runner should delete dylibPath when it's finished using the file.
See Also
CompileAndRunInCurrentProcess.cc
VuoRunner * VuoRunner::newSeparateProcessRunnerFromDynamicLibrary ( string  compositionLoaderPath,
string  compositionDylibPath,
string  resourcesDylibPath,
bool  deleteDylibsWhenFinished = false 
)
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.

Parameters
compositionLoaderPathThe VuoCompositionLoader executable.
compositionDylibPathA linked composition dynamic library, produced by VuoCompiler::linkCompositionToCreateDynamicLibraries().
resourcesDylibPathA linked resources dynamic library, produced by VuoCompiler::linkCompositionToCreateDynamicLibraries().
deleteDylibsWhenFinishedTrue if the runner should delete compositionDylibPath and resourcesDylibPath when it's finished using the files.
VuoRunner * VuoRunner::newSeparateProcessRunnerFromExecutable ( string  executablePath,
bool  deleteExecutableWhenFinished = false 
)
static

Creates a runner object that can run a graph in a new process.

Parameters
executablePathA linked graph executable, produced by VuoCompiler::linkGraphIntoExecutable().
deleteExecutableWhenFinishedTrue if the runner should delete executablePath when it's finished using the file.
See Also
CompileAndRunInNewProcess.cc
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::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.

Parameters
compositionDylibPathA linked composition dynamic library, produced by VuoCompiler::linkGraphIntoDynamicLibrary().
compositionDiffA 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.

See Also
drainMainDispatchQueue(), an alternative to this method.
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.

Parameters
portIdentifierThe compile-time identifier for the port (see VuoCompilerEventPort::getIdentifier()).
valueAsStringString representation of the port's new value.
See Also
Built-in Types for information about types and serialization.
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.

See Also
Built-in Types for information about types and serialization.
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.

Example:
runner.setPublishedInputPortValue(inputPort, inputValue);
runner.setPublishedInputPortValue(anotherInputPort, anotherInputValue);
result = runner.getPublishedOutputPortValue(outputPort);

The documentation for this class was generated from the following files: