Flags (v0.3.0 only)

Flags are an optional field in a data flow declaration, their purpose is to toggle on/off part(s) of a data flow. Flags are only present in the version v0.3.0 of Zenoh-Flow.

Imagine you have two ways of accomplishing the same computation (for instance you have two control algorithms or two IA you want to try) and you want to be able to switch without having to maintain two copies of almost the same data flow.

Then Flags are probably what you want! ;-)

Overview

Before diving into how they work, let’s look at an example:

flow: my-data-flow


flags:
- id: Flag-Op-1
  toggle: true
  nodes:
  - Op-1

- id: Flag-Op-2
  toggle: false
  nodes:
  - Op-2


sources:
- id: Source
  uri: …
  output:
    id: Source-out
    type: …


operators:
- id: Op-1
  uri: …
  inputs:
  - id: Op-1-in
    type: …
  outputs:
  - id: Op-1-out
    type: …

- id: Op-2
  uri: …
  inputs:
  - id: Op-2-in
    type: …
  outputs:
  - id: Op-2-out
    type: …


sinks:
- id: Sink
  uri: …
  input:
    id: Sink-in
    type: …


links:
# Flow with Op-1
- from:
    node: Source
    output: Source-out
  to:
    node: Op-1
    input: Op-1-in
- from:
    node: Op-1
    output: Op-1-out
  to:
    node: Sink
    input: Sink-in
# Flow with Op-2
- from:
    node: Source
    output: Source-out
  to:
    node: Op-2
    input: Op-2-in
- from:
    node: Op-2
    output: Op-2-out
  to:
    node: Sink
    input: Sink-in

There are few things to unpack here, let us start with the flow in itself --- excluding the flags.

We are defining 4 nodes: Source, Op-1, Op-2 and Sink.

We are also telling Zenoh-Flow that the links are:

• (i) Source -> Op-1 -> Sink
• (ii) Source -> Op-2 -> Sink

With just this, Zenoh-Flow will refuse to instantiate: our node Sink has two links going to its port Sink-in — something that is incorrect in Zenoh-Flow.

Hopefully we have the flags to remedy this situation!

The first flag, Flag-Op-1 controls when Op-1 is activated and the second flag, Flag-Op-2 controls Op-2. As Flag-Op-1 is toggled on and Flag-Op-2 is off, only Op-1 will be activated.

Additionally, Zenoh-Flow knows that it should discard all links going in and coming out of nodes that are deactivated.

Hence, considering the flags, Zenoh-Flow will:

1. only activate Op-1,
2. only consider the links: Source -> Op-1 -> Sink.

To activate Op-2 instead, just switch the Flag-Op-1 toggle to false and the Flag-Op-2 toggle to true. That’s it!

In-depth view

Declaration

Let us look again at the declaration of the Flags:

flags:
- id: Flag-1
  toggle: true
  nodes:
  - node-1
  - node-2

The field id is only used for debug purposes to give a clearer error --- we will get to validation right after.

The field toggle specifies if a Flag is on or off. If a Flag is on then all the nodes it refers to will be activated. The opposite is not necessarily true --- more on that after.

The field nodes lists the nodes this Flag will activate. Multiple nodes can be listed. A node can be listed in different flags.

Validation

Zenoh-Flow checks for the validity of the Flags in the description. A Flag is invalid if it refers to nodes that do not exist. A node does not exist if Zenoh-Flow cannot find a node with the same id (we perform a string comparison, so an id is case-sensitive).

When are nodes (de)activated?

A node is activated if and only if:

• at least one Flag refers to it and that Flag is toggled on (i.e. there is: toggle: true); OR
• no Flag refers to that node.

The first condition allows having several Flags that control the same subset of nodes. For instance, you want to try out 3 different algorithms and 2 of those have one node in common.

The second condition allows not having to specify all nodes in Flags. Flags only focus on the nodes they want to control.

Thus, a node is deactivated if and only if:

• at least one Flag refers to it and all the Flags that refers to it are toggled off (i.e. there is, for all these Flags, toggle: false).

Looking at the following example:

flags:
- id: Flag-1
  toggle: true
  nodes:
  - node-1
  - node-2
- id: Flag-2
  toggle: false
  nodes:
  - node-1
  - node-3

node-2 will be activated as it is listed in Flag-1 which is toggled on. node-3 will be deactivated as it is listed in Flag-2 which is toggled off.

As explained earlier, node-1 is activated because Flag-1 is toggled on. As long as one Flag is toggled on, a node will be activated.