Class NodeSet

A node set is a set of instantiated user nodes connected together in some particular way, although not necessarily completely connected. Nodes can communicate through flowing data or messages, and the execution pattern is defined from the connections you establish. Unity.DataFlowGraph.NodeDefinition`1 Update()

Inheritance
Object
NodeSetAPI
NodeSet
Inherited Members
Namespace: Unity.DataFlowGraph
Syntax
public class NodeSet : NodeSetAPI, IDisposable

Constructors

NodeSet()

Construct a node set. Remember to dispose it. Dispose()

Declaration
public NodeSet()

NodeSet(ComponentSystemBase)

Initializes this NodeSet in a mode that's compatible with running together with ECS, through the use of ComponentNodes. The hostSystem and this instance are tied together from this point, and you must update this set using the Update(JobHandle) function. See also NodeSet().

Declaration
public NodeSet(ComponentSystemBase hostSystem)
Parameters
Type Name Description
ComponentSystemBase hostSystem
Remarks

Any instantiated nodes with IKernelPortDefinitions containing ECS types will be added as dependencies to hostSystem.

Exceptions
Type Condition
ArgumentNullException

Thrown if the hostSystem is null

Properties

IsCreated

Query whether Dispose() has been called on the NodeSet.

Declaration
public bool IsCreated { get; }
Property Value
Type Description
Boolean

RendererModel

The render execution scheduling mode use for launching the processing of IGraphKernel<TKernelData, TKernelPortDefinition>s in the node set. Update()

Declaration
public NodeSet.RenderExecutionModel RendererModel { get; set; }
Property Value
Type Description
NodeSet.RenderExecutionModel
Remarks

Changing this can drastically alter the execution runtime of your graph. The best choice largely depends on the topological layout of the graph in question.

RendererOptimizations

Optional speculative optimizations applied to the rendering graph processing. NodeSet.RenderOptimizations

Declaration
public NodeSet.RenderOptimizations RendererOptimizations { get; set; }
Property Value
Type Description
NodeSet.RenderOptimizations
Remarks

Changing this can drastically alter the execution runtime of your graph. The best choice largely depends on the topological layout of the graph in question.

Methods

Dispose()

Cleans up the node set, and releasing any resources associated with it.

Declaration
public void Dispose()
Implements
Remarks

It's expected that the node set is completely cleaned up, i.e. no nodes exist in the set, together with any GraphValue<T>.

GetDefinition(NodeHandle)

Looks up the node definition for this handle. NodeDefinition

Declaration
public NodeDefinition GetDefinition(NodeHandle handle)
Parameters
Type Name Description
NodeHandle handle
Returns
Type Description
NodeDefinition
Exceptions
Type Condition
ArgumentException

Thrown if the node handle does not refer to a valid instance.

GetDefinition<TDefinition>()

Looks up the specified node definition, creating it if it doesn't exist already.

Declaration
public TDefinition GetDefinition<TDefinition>()
    where TDefinition : NodeDefinition, new()
Returns
Type Description
TDefinition
Type Parameters
Name Description
TDefinition
Exceptions
Type Condition
InvalidNodeDefinitionException

Thrown if the TDefinition is not a valid node definition.

GetDefinition<TDefinition>(NodeHandle<TDefinition>)

Looks up the verified node definition for this handle. NodeDefinition

Declaration
public TDefinition GetDefinition<TDefinition>(NodeHandle<TDefinition> handle)
    where TDefinition : NodeDefinition, new()
Parameters
Type Name Description
NodeHandle<TDefinition> handle
Returns
Type Description
TDefinition
Type Parameters
Name Description
TDefinition
Exceptions
Type Condition
ArgumentException

Thrown if the node handle does not refer to a valid instance.

GetDSLHandler<TDSLHandler>()

Declaration
public TDSLHandler GetDSLHandler<TDSLHandler>()
    where TDSLHandler : class, IDSLHandler, new()
Returns
Type Description
TDSLHandler
Type Parameters
Name Description
TDSLHandler

GetGraphValueResolver(out JobHandle)

Returns a GraphValueResolver that can be used to asynchronously read back graph state and buffers in a job. Put the resolver on a job ("consumer"), and schedule it against the parameter resultDependency.

Any job handles referencing the resolver must to be submitted back to the node set through InjectDependencyFromConsumer(JobHandle).

Declaration
public GraphValueResolver GetGraphValueResolver(out JobHandle resultDependency)
Parameters
Type Name Description
JobHandle resultDependency

Contains an aggregation of dependencies from the last Update() for any created graph values.
Returns
Type Description
GraphValueResolver
Remarks

The returned resolver is only valid until the next Update() is issued, so call this function after every Update().

The resolver does not need to be cleaned up from the user's side.

InjectDependencyFromConsumer(JobHandle)

Injects external dependencies into this node set, so the next Update() synchronizes against consumers of any data from this node set.

Declaration
public void InjectDependencyFromConsumer(JobHandle handle)
Parameters
Type Name Description
JobHandle handle
See Also

SendMessage<TMsg>(NodeHandle, InputPortID, TMsg)

Send a message of a specific type to a message input port on a node.

Declaration
public void SendMessage<TMsg>(NodeHandle handle, InputPortID port, in TMsg msg)
Parameters
Type Name Description
NodeHandle handle

The node to be messaged.
InputPortID port

A MessageInput<TDefinition, TMsg> port on the given node.
TMsg msg

The content of the message to be delivered.
Type Parameters
Name Description
TMsg

The type of message data. Must correspond to the type of the given MessageInput<TDefinition, TMsg>.
Exceptions
Type Condition
InvalidOperationException

Thrown if the request is invalid.

SendMessage<TMsg>(NodeHandle, InputPortID, Int32, TMsg)

Overload of targeting a port array with an index parameter.

Declaration
public void SendMessage<TMsg>(NodeHandle handle, InputPortID portArray, int index, in TMsg msg)
Parameters
Type Name Description
NodeHandle handle
InputPortID portArray
Int32 index
TMsg msg
Type Parameters
Name Description
TMsg
Exceptions
Type Condition
IndexOutOfRangeException

Thrown if the index is out of range with respect to the port array.

SendMessage<TMsg, TDefinition>(NodeHandle<TDefinition>, MessageInput<TDefinition, TMsg>, TMsg)

See

Declaration
public void SendMessage<TMsg, TDefinition>(NodeHandle<TDefinition> handle, MessageInput<TDefinition, TMsg> port, in TMsg msg)
    where TDefinition : NodeDefinition
Parameters
Type Name Description
NodeHandle<TDefinition> handle
MessageInput<TDefinition, TMsg> port
TMsg msg
Type Parameters
Name Description
TMsg
TDefinition

SendMessage<TMsg, TDefinition>(NodeHandle<TDefinition>, PortArray<MessageInput<TDefinition, TMsg>>, Int32, TMsg)

Overload of targeting a port array with an index parameter.

Declaration
public void SendMessage<TMsg, TDefinition>(NodeHandle<TDefinition> handle, PortArray<MessageInput<TDefinition, TMsg>> portArray, int index, in TMsg msg)
    where TDefinition : NodeDefinition
Parameters
Type Name Description
NodeHandle<TDefinition> handle
PortArray<MessageInput<TDefinition, TMsg>> portArray
Int32 index
TMsg msg
Type Parameters
Name Description
TMsg
TDefinition
Exceptions
Type Condition
IndexOutOfRangeException

Thrown if the index is out of range with respect to the port array.

SendMessage<TTask, TMsg>(NodeInterfaceLink<TTask>, TMsg)

Declaration
public void SendMessage<TTask, TMsg>(NodeInterfaceLink<TTask> handle, in TMsg msg)
    where TTask : ITaskPort<TTask>
Parameters
Type Name Description
NodeInterfaceLink<TTask> handle
TMsg msg
Type Parameters
Name Description
TTask
TMsg

SendMessage<TTask, TMsg, TDestination>(NodeInterfaceLink<TTask, TDestination>, TMsg)

Declaration
public void SendMessage<TTask, TMsg, TDestination>(NodeInterfaceLink<TTask, TDestination> handle, in TMsg msg)
    where TTask : ITaskPort<TTask> where TDestination : NodeDefinition, TTask, new()
Parameters
Type Name Description
NodeInterfaceLink<TTask, TDestination> handle
TMsg msg
Type Parameters
Name Description
TTask
TMsg
TDestination

SendTest<TNodeData>(NodeHandle, SimulationTestFunction<TNodeData>)

Shorthand version of SendTest<TNodeData>(NodeHandle, SimulationTestFunctionWithContext<TNodeData>) omitting the SimulationTestContext<TNodeData> for simple test cases which do not require testing of child nodes.

Declaration
public void SendTest<TNodeData>(NodeHandle handle, SimulationTestFunction<TNodeData> code)
    where TNodeData : struct, INodeData
Parameters
Type Name Description
NodeHandle handle
SimulationTestFunction<TNodeData> code
Type Parameters
Name Description
TNodeData
Exceptions
Type Condition
InvalidOperationException

Thrown if the given TNodeData type does not correspond to that declared in the node's NodeDefinition

SendTest<TNodeData>(NodeHandle, SimulationTestFunctionWithContext<TNodeData>)

Sends a function into the simulation for testing purposes. The given function will be queued into the stream of messages destined for the given node and will be invoked after any messages queued before it. The function should be used to throw testing exceptions (such as those from an ) which will be collected in the next Update() and can subsequently be recovered by calling ThrowCollectedTestException(). It is an error to Dispose() with pending uncollected test exceptions.

Declaration
public void SendTest<TNodeData>(NodeHandle handle, SimulationTestFunctionWithContext<TNodeData> code)
    where TNodeData : struct, INodeData
Parameters
Type Name Description
NodeHandle handle
SimulationTestFunctionWithContext<TNodeData> code
Type Parameters
Name Description
TNodeData
Remarks

This function is provided solely for test purposes and is not guaranteed to be available in release builds. This function should not be used to inject or recover any data from simulation or otherwise influence normal runtime behavior of nodes in non-testing scenarios.

Exceptions
Type Condition
InvalidOperationException

Thrown if the given TNodeData type does not correspond to that declared in the node's NodeDefinition

SetData<TType>(NodeHandle, InputPortID, TType)

Sets the data on an unconnected data input port on a node. The data will persist on the input until a connection is made to that input, or, it replaced by another call to .

Declaration
public void SetData<TType>(NodeHandle handle, InputPortID port, in TType data)
    where TType : struct
Parameters
Type Name Description
NodeHandle handle

The node on which data is to be set.
InputPortID port

A DataInput<TDefinition, TType> port on the given node.
TType data

The content of the data to be set.
Type Parameters
Name Description
TType

The type of data to be set. Must correspond to the type of the given DataInput<TDefinition, TType>.
Remarks

Note that Buffer<T> data is unsupported at this time.

Exceptions
Type Condition
InvalidOperationException

Thrown if the request is invalid.

SetData<TType>(NodeHandle, InputPortID, Int32, TType)

Overload of targeting a port array with an index parameter.

Declaration
public void SetData<TType>(NodeHandle handle, InputPortID portArray, int index, in TType data)
    where TType : struct
Parameters
Type Name Description
NodeHandle handle
InputPortID portArray
Int32 index
TType data
Type Parameters
Name Description
TType
Exceptions
Type Condition
IndexOutOfRangeException

Thrown if the index is out of range with respect to the port array.

SetData<TType, TDefinition>(NodeHandle<TDefinition>, DataInput<TDefinition, TType>, TType)

See

Declaration
public void SetData<TType, TDefinition>(NodeHandle<TDefinition> handle, DataInput<TDefinition, TType> port, in TType data)
    where TType : struct where TDefinition : NodeDefinition
Parameters
Type Name Description
NodeHandle<TDefinition> handle
DataInput<TDefinition, TType> port
TType data
Type Parameters
Name Description
TType
TDefinition

SetData<TType, TDefinition>(NodeHandle<TDefinition>, PortArray<DataInput<TDefinition, TType>>, Int32, TType)

Overload of targeting a port array with an index parameter.

Declaration
public void SetData<TType, TDefinition>(NodeHandle<TDefinition> handle, PortArray<DataInput<TDefinition, TType>> portArray, int index, in TType data)
    where TType : struct where TDefinition : NodeDefinition
Parameters
Type Name Description
NodeHandle<TDefinition> handle
PortArray<DataInput<TDefinition, TType>> portArray
Int32 index
TType data
Type Parameters
Name Description
TType
TDefinition
Exceptions
Type Condition
IndexOutOfRangeException

Thrown if the index is out of range with respect to the port array.

ThrowCollectedTestException()

Will rethrow any test exception (see SendTest<TNodeData>(NodeHandle, SimulationTestFunctionWithContext<TNodeData>)) that was collected in a previous Update(). If there are multiple pending test exceptions each individual call to this method will dequeue and rethrow the oldest one.

Declaration
public void ThrowCollectedTestException()
Remarks

It is not an error to call this method if there are no pending test exceptions to be thrown.

Update()

Updates the node set in two phases:

  1. A message phase (simulation) where nodes are updated and messages are passed around
  2. Aligning the simulation world and the rendering world and initiate the rendering.
NodeSet.RenderExecutionModel
Declaration
public void Update()
Exceptions
Type Condition
InvalidOperationException

Can be thrown if invalid or missing dependencies were added through InjectDependencyFromConsumer(JobHandle).

Can also be thrown if this NodeSet was created with the ECS constructor NodeSet(ComponentSystemBase), in which case you need to use the Update(JobHandle) function instead.

Update(JobHandle)

Overload of Update(). Use this function inside a ComponentSystemBase.

Declaration
public JobHandle Update(JobHandle inputDeps)
Parameters
Type Name Description
JobHandle inputDeps

Input dependencies derived from or Dependency, pass the input dependencies into this function.
Returns
Type Description
JobHandle

A JobHandle that should be returned or included in a dependency chain inside or assigned to Dependency.
Remarks

This function is only compatible if you used the NodeSet(ComponentSystemBase) constructor.

Exceptions
Type Condition
InvalidOperationException

Can be thrown if this NodeSet was created without using the ECS constructor NodeSet(ComponentSystemBase), in which case you need to use the Update() function instead. See also base documentation for Update()

Extension Methods