4.2. How events travel through a node

An event can come into a node through cables connected to one or more of its input ports. When an event reaches the node’s input ports, the node executes, and it may or may not send the event through its output ports.

4.2.1. Input ports

An input port is the location on the left side of the node where you can enter data directly, connect a data-and-event cable, or connect an event-only cable. When an event arrives at an input port, it causes the node to execute and perform its function based on the data present at the node’s input ports. Event walls and doors

Some nodes, like the ones shown below, have input ports that block an event. This means the node will execute, but the event associated with that data won’t travel through any output ports. Event blocking is useful when you want part of your composition to execute in response to events from one trigger port but not events from another trigger port, or when you’re creating a feedback loop.

Ports that always block events have a solid semi-circle (like the URL port above) or a solid chevron (like the Start port above). This is called an event wall. The node must receive an event from another port without an event wall for the results of the node’s execution to be available to other nodes.

The event wall is visually placed inside the node to indicate that the event gets blocked inside the node (as it executes) — rather than getting blocked before it reaches the node.

Ports that sometimes block events have a broken semi-circle (like the Which port above) or a broken chevron (like the Time port above). This is called an event door. Event doors are useful when you want to take events from a trigger port and filter some of them out or route them to different parts of the composition. For example, in the Select Output node, the value at the Which port will determine whether the data-and-event coming into the In port will be transmitted to the Option 1 port or the Option 2 port.

The manual section How events travel through a composition has more information on how events move through a composition. Port actions

Some input ports cause the node to do something special when they receive an event. In the Count within Range node shown below, the Increment, Decrement, and Set Count ports each uniquely affect the count stored by the node — upon receiving an event, they increment the count, decrement the count, or change the count to a specific number. Likewise, in the Display Console Window node, the Write Line input port does something special when it receives an event — it writes a line of text to the console window. Each of these ports has a port action.

If an input port has a port action, then the node does something different when that input port receives an event than it does when any other input port receives an event. What counts as something different? Either the node outputs different data (immediately or later) or the node affects the world outside the composition differently.

Looking again at the Count within Range node, you can see that the node has some input ports with port actions and some without. For the ports without port actions — Minimum, Maximum, and Wrap Mode — the node will output the same number regardless of whether the event causing the node to execute has hit one of these ports. The node uses the data from these ports and doesn’t care if they received an event. For each of the ports with port actions, however, it makes a difference whether the event has hit the port. The Increment port, for example, only affects the count if the event came in through that input port.

Rather than affecting the node’s output data, as in the Count within Range node, the Display Console Window node’s port action affects the world outside the composition. When the Write Line input port receives an event, it doesn’t affect the data coming out of the node’s output ports. Rather, it affects what you see in the console window.

You can recognize an input port with a port action by the little triangle to the right of the port name. In Vuo, the triangle shape symbolizes events. The little triangle for the port action reminds you that this port does something unique when it receives an event. Refresh ports

Every node has a built-in event-only input port called the refresh port. The purpose of this port is to execute the node without performing any port actions.

For example, the composition above shows how you can use the refresh port to get the Count node’s current count without incrementing or decrementing it. When the lower Fire Periodically node fires an event, Display Console Window writes the incremented count. When the upper Fire Periodically node — which is connected to the Count node’s refresh port — fires an event, the count stays the same. Display Console Window writes the same count as before.

On other nodes, like Hold Value, the refresh port is the only input port that transmits events to any output ports. The Hold Value node lets you store a value during one event and use it during later events. The composition below shows how you can use a Hold Value node to update a value every 1 second and write it every 5 seconds.

Refresh ports are useful for allowing event flow out of nodes that have event walls. The event entering the Refresh port can travel to downstream nodes, while an event encountering an event wall cannot.

When the left Fire Periodically node executes, the count, as a data-and-event, is transmitted to the Hold Value node. The Display Console Window node doesn’t execute because, when the event arrives at the Hold Value node, it is blocked.

When the upper Fire Periodically node executes, the count stored in the Hold Value node travels to the Display Console Window node and gets written.

4.2.2. Output ports

When an event executes a node, the event can travel to downstream nodes using the output ports. Like input ports, output ports can be data-and-event or event-only. Trigger ports

Although trigger ports can create events, they never transmit events that came into the node through an input port (hence the thick line to the left of each trigger port — an event wall), nor do they cause any other output ports to emit events.