![]() |
SolarCapture C Bindings User Guide
SF-115721-CD
Issue 3
|
Node used as a sub-node to manage inputs and/or pools.
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.
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. |
You can add an arbitrary set of outgoing links to this node, and they are made available via sc_subnode_helper::sh_links.
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. |