SolarCapture C Bindings User Guide  SF-115721-CD
Issue 3
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
sc_subnode_helper Node Reference

Node used as a sub-node to manage inputs and/or pools.

Detailed Description

This node is used as a subnode to manage buffered input and/or outputs that use a packet pool. It is never instantiated on its own. Here are two example scenarios where this node is helpful:

1) Generating output based on the input without modifying the input. The top-level node instantiates a pool and an sc_subnode_helper, and directs its input to the subnode. Incoming buffers are placed in the backlog, and the handler is invoked when the backlog is non-empty and the pool has buffers. ie. When the resources are available to make progress.

2) Keeping multiple inputs separate. When a node receives buffers from multiple input links it is not possible to tell which buffers came from which input. A solution is to use an nt_select_subnode_fn() handler to instantiate a subnode for each distinct input.

When packets are received by an sc_subnode_helper they are appended to a backlog list (sc_subnode_helper::sh_backlog). The backlog handler is invoked repeatedly until either the backlog is emptied or the packet handler leaves the backlog unmodified. If sc_subnode_helper::sh_pool_threshold is set, then the backlog handler is only invoked so long as the pool has at least the requested number of buffers available.

If sc_subnode_helper::sh_handle_end_of_stream_fn is set then it is invoked when the end-of-stream signal has been received and the backlog is empty. If sh_pool_threshold is also set, the end-of-stream handler is only invoked when the pool has at least the requested number of buffers available.

If sc_subnode_helper::sh_poll_backlog_ns is set then the backlog handler is invoked periodically whenever the backlog is non-empty, even if the pool threshold has been set and not yet reached.

When 'with_pool=1', a packet pool is allocated and a pointer stored at sc_subnode_helper::sh_pool. The attributes of the pool are set by the attributes passed to the node allocation function.

Alternatively sh_pool can be set to point at a pool allocated elsewhere (eg. by the parent node). This is useful when implementing nodes that forward information from inputs to outputs, but in new buffers.

By default, a link for freeing packets is allocated and placed in sc_subnode_helper::sh_free_link. If with_free_link=0 then a free link is not allocated. If with_free_link=2 then a free link is only allocated if the node has no other outgoing links.

Any outgoing links added to the node are made available via sc_subnode_helper::sh_links and sc_subnode_helper::sh_n_links. If no links are added then a copy of sh_free_link (if requested) is placed at sh_links[0]. This allows access sh_links[0] without having to check whether any links were added.

See also sc_subnode_helper for further details of the interface to this node.

Arguments

Argument Optional? Default Type Description
with_pool Yes 0 SC_PARAM_INT Whether to allocate a pool.
with_free_link Yes 1 SC_PARAM_INT Whether to allocate a free link.

Output Links

You can add an arbitrary set of outgoing links to this node, and they are made available via sc_subnode_helper::sh_links.

Exposed Statistics

Batch limiter statistics are exposed by the sc_subnode_helper node.

Name Type Data Type Description
backlog_len uint64_t pkt_count Number of packets in backlog.