Skip to content

← programming package

ByReference

Pass a given value by reference into the next node.

This is a special-purpose node that should not be used frequently, and only then with care and a clear understanding. It addresses the following: in NeuroPype, nodes generally do not modify the data that is passed into them -- if a node might modify their received value, they will create a copy beforehand so that that does not happen. This is called pass-by-value. In rare cases, you may wish to override this behavior and allow a node to act on a "reference" to some wired-in data, which causes any modifications to that data to be reflected in the original input and thus be visible on the "left-hand" side of the node. This is called "pass-by-reference". The node has two modes of operation: it can either mark the value that flows through the node as being passed by reference to the next node ('value' mode), so that that value becomes marked as a reference value, OR it can mark the graph that contains this node as being passed by reference ('graph mode'). In the first scenario, the marking applies to the first node that accepts a value, and does not propagate any further. The second scenario is more involved: the most common case in which a graph is created and then passed to a node, is when a node accepts a value of type "Graph", but the preceding node does not emit a value of type "Graph"; in that case, NeuroPype will extract a portion of the preceding graph (subject to some rules) and pass that to the next node (rendered as a dotted line in some UIs). If that portion includes a ByReference node (or any other node that accepts graphs) near its end that is set to 'graph' mode, then that graph is treated by reference by the receiving node. Furthermore, since the node remains in the graph, if the node passes the graph back out, then any receiving node will also treat it by reference (unless the ByReference node is removed again). A graph being treated by reference has the consequence that, if a node executes the graph, any state changes in its contained nodes will persist across subsequent executions of that graph, and this is the main use case for this variant. A second way to end up with a graph that contains a ByReference node is to construct it as such (e.g., inside a node). To make matters slightly more nuanced, be aware that graphs can also flow as "ordinary" values over edges, which occurs when both the sending and receiving node use the type Graph for their ports (typically the sending node would be some sort of graph transformation or generation node). Consequently, you can insert a ByReference node into the graph-transporting edge, and set it to 'value' mode, and it will mark the graph that flows though it to be received by reference by the next node (like an ordinary value), whether the flowing graph contains a ByReference node or not (however, you could not simply "insert" such a node into the graph that flows by without employing some sort of graph transformation). It is important to note, however, that when you replace the Graph-to-Graph edge by a Graph-ByReference-Graph edge, you need to wire out of the data_asgraph output of the ByReference node to tell NeuroPype that a graph is travelling over the edge (otherwise NeuroPype's rule to construct a graph from the preceding nodes would be triggered). Version 1.0.0

Ports/Properties

data

Pass-through data.

  • verbose name: Data
  • default value: None
  • port type: DataPort
  • value type: object (can be None)
  • data direction: INOUT

data_asgraph

Pass-through data, as a graph.

  • verbose name: Data Asgraph
  • default value: None
  • port type: GraphPort
  • value type: Graph

apply_to

indicates what shall be passed by reference. If set to 'value', the value travelling through this node is passed by reference and not copied before received by the next node. If set to 'graph', any graphs that contain this node in their tail will themselves always be passed by reference.

  • verbose name: Apply To
  • default value: value
  • port type: EnumPort
  • value type: str (can be None)

set_breakpoint

Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

  • verbose name: Set Breakpoint (Debug Only)
  • default value: False
  • port type: BoolPort
  • value type: bool (can be None)

metadata

User-definable meta-data associated with the node. Usually reserved for technical purposes.

  • verbose name: Metadata
  • default value: {}
  • port type: DictPort
  • value type: dict (can be None)