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

Description

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, 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 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.
 
json_object * 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.
 
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, 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 to get an input port's value.
 
json_object * 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 VuoRunnernewSeparateProcessRunnerFromExecutable (string executablePath, bool deleteExecutableWhenFinished=false)
 Creates a runner object that can run a composition in a new process.
 
static VuoRunnernewSeparateProcessRunnerFromDynamicLibrary (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 VuoRunnernewCurrentProcessRunnerFromDynamicLibrary (string dylibPath, bool deleteDylibWhenFinished=false)
 Creates a runner object that can run a composition in the current process.
 

Friends

class TestVuoRunner
 

Constructor & Destructor Documentation

VuoRunner::~VuoRunner ( void  )

Destructor.

Assumes the composition 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 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.

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 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.

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

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

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

Parameters
portIdentifierThe compile-time identifier for the port (see VuoCompilerEventPort::getIdentifier()).
Returns
JSON 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 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.

json_object * 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.

Parameters
portThe published output port.
Returns
JSON representation of the port's value.
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 composition 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 composition in the current process.

Parameters
dylibPathA linked composition dynamic library, produced by VuoCompiler::linkCompositionToCreateDynamicLibrary().
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  resourceDylibPath,
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().
resourceDylibPathA linked resource dynamic library, produced by the first call to VuoCompiler::linkCompositionToCreateDynamicLibraries() for this runner.
deleteDylibsWhenFinishedTrue if the runner should delete compositionDylibPath and resourceDylibPath when it's finished using the files.
VuoRunner * VuoRunner::newSeparateProcessRunnerFromExecutable ( string  executablePath,
bool  deleteExecutableWhenFinished = false 
)
static

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

Parameters
executablePathA linked composition executable, produced by VuoCompiler::linkCompositionToCreateExecutable().
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 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.

Parameters
compositionDylibPathA linked composition dynamic library, produced by VuoCompiler::linkCompositionToCreateDynamicLibrary().
resourceDylibPathA 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.
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,
json_object *  value 
)

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.

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

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.

Parameters
portThe published input port.
valueJSON representation of the port's new value.
See Also
Built-in Types for information about types and serialization.
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.

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

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