CGF Channel

CGF Channel is a data allocation and transport framework. Its features include:

Multiple transport backends including local shared memory, socket ipc, and NvSciStream, with near zero API differences for applications to switch between them. Code producing or consuming data can be written without knowledge of whether their peer is in the same process, a remote process, or on a different SOC.
Multicasting from a single producer to multiple consumers.
Flexibility to transfer many data types and use application-defined data types.
Buffer pool allocation.
Fifo or mailbox consumption modes for consumers.

CGF Channels include several different classes which are used together to accomplish its functionality.

ChannelObject is the abstract, weakly-typed interface which transports the data.
ChannelFactory serves as a shared context object for all ChannelObjects and is responsible for constructing them and managing their services.
[DEPRECATED] ChannelConnector is a utility which connects ChannelObjects to their peer producers and consumers at init-time.
Ports are lightweight objects that bind to a ChannelObject to provide a strongly-typed interface to allocate and transport data.
IChannelPacket is the interface that CGF Channels uses to handle type-specific functionality. Applications extend these interfaces in order to define how CGF Channels can allocate and transport their data types.

Channels are allocated by the ChannelFactory with parameters specified in a string format. The parameters are specified in key=value pairs delineated by commas. Unrecognized keys and their values are ignored.

The parameter keys include the following:

Key	Value Range	Usage	Description
role	{producer, consumer, composite}	required	Indicates if the channel is a producer, consumer. Composite role is deprecated.
type	{SHMEM_LOCAL, SOCKET, NVSCI}	optional (default SHMEM_LOCAL)	Indicates the type of channel, which implies the underlying transport protocal to use. Only channels of the same type may connect to each other.
fifo-size		optional (default 1)	For producer localshmem channels, fifo-size hints the number of packets allocate. The size of the packet pool is the maximum of fifo-size parameters for any connected consumer or the producer plus one for each connected consumer and the producer. For consumer localshmem channels, fifo-size indicates the maximum logical size that the queue of received packets is allowed to reach. For producer socket channels, fifo-size is ignored except when producer-fifo=1. For consumer socket channels, fifo-size is the maximum logical size that the queue of received packets is allowed to reach once packets have been read from the socket and placed in memory. The consumer allocates a pool of packets equal to the fifo-size parameter. For producer nvsci channels, fifo-size is the number of packets to allocate. For consumer nvsci channels, fifo-size is ignored. There is no logical limit on the size of the received packet queue imposed by a consumer. Instead, the size of the queue is determined simply by the number of packets allocated by the producer.
mode	{mailbox, singleton}	optional (default none)	mode=mailbox indicates that the maximum size of the queue of received packets is one and that old packets received but not yet read by the application will be dropped (immediately released back to the producer), and replaced when a newer packet is received. mode=singleton is deprecated. When not specified the default behavior of consumers is that old packets are not dropped. For localshmem fifo consumers, the producer application thread will throw an error on attempt to send more packets than are allowed.
id	uint16	localshmem and socket only, required	The unique producer id for the connection. Producer channels own the id and consumer channels use the id to identify the producer to connect to. For socket channels, the id is used as the port for the socket connection.
num-clients	uint16	optional (default 1)	Indicates the number of expected consumers to connect to the producer. If the number of connected consumers is less than num-clients, the producer is logically not yet fully connected. For nvsci channels, the parameter represents the number of consumers without nvsciipc endpoints which may either be intra-process or ipc.
singleton-id	uint16	localshmem producer only, optional (default none)	singleton-id enables shared pool packet useage where multiple producers utilize the same underlying packet pool instead of allocating their own disjoint packet pools. Each pool has a unique id and singleton-id, passed to a producer localshmem channel, indicates the id of the shared packet pool for the channel to use. It is enforced by Channels that only one producer and its associated consumers may use each packet from the shared packet pool at a time. The shared packet pool size is limited to 1.
ip	IPv4 or IPv6 address string	socket only, required	The IP address of remote peer to connect to.
producer-fifo	0 or 1	socket producer only, optional (default 0)	Indicates if the socket producer channel shall allocate more than one buffer to be filled by the application before send. In use-cases where producer application fills and sends one buffer at a time, the default value is sufficient. Indicates the nvsciipc endpoints to connect to. For consumer channels, only one endpoint is required and allowed.
streamName	colon-delineated string list	nvsci channels only	Indicates the nvsciipc endpoint(s) to use for the inter-process, inter-vm, or inter-SoC connections. For a producer, more than one endpoint may be provided, enabling multicasting. For a consumer, up to one endpoint may be provided.
limit	colon-delineated integer list	nvsci producer channels only	Indicates the packet limit(s) of endpoint connections, one per endpoint specified in the streamName parameter. The limit is the maximum number of packets that a consumer application is allowed to hold. The limit may be 0 and a negative value indicates no limit. This limit includes: packets that are waiting in NvSciStream for consumer application to consume. packets that the application is currently reading and has not yet released. packets that have been released and are in transmission back to producer.
connectPrio	colon-delineated integer list	nvsci producer channels only	Indicates the connect priority of endpoints listed in the streamNames parameter. Priority of 0 indicates that endpoint should be connected on first connect attempt. Priority of non-zero implies the endpoint shall be connected on second connect attempt.

Channels currently have many more deprecated parameters that are exposed and useable but not documented here.

Simplified late attachment with nvsci channels is achieved with the following steps:

The application creates producer channel, passing streamNames parameter with full list of nvsciipc endpoints to be connected.
The application binds the producer channel.
The application creates and binds any intra-process consumers which will consume from the producer.
The application calls startServices() on the ChannelFactory, which triggers connection of the early consumers.
The application waits for the ChannelFactory to deliver a CONNECTED event for the channel.
The application starts serving frames on the channel, in parallel to the following steps.
The application calls startServices() again on ChannelFactory, triggering connection to remaining consumers.
The application waits for the ChannelFactory to deliver a CONNECTED event for the channel, after which further produced packets will be sent to late consumers.
Note: while a set of late endpoints are being connected, service to any one of the late endpoints will not be started until the connection to all succeeds. Similarly, while a late set of endpoints are being connected, no further late endpoints may be connected until connection to the currently connecting endpoints has succeeded.

Late Attachment with nvsci channels is achieved with the following steps:

The application passes the num-clients parameter which is equal to the sum of the number of intra-process consumers, and the number of late attached consumers.
The application creates and binds any intra-process consumers which will consume from the producer.
The application calls startServices() on the ChannelFactory, which triggers connection of the early consumers.
The application waits for the ChannelFactory to deliver a CONNECTED event for the channel.
The application starts serving frames on the channel, in parallel to the following steps.
The application calls connectEndpoint() for each of the nvsciipc endpoints it wishes to late attach.
The application calls connect() on the channel to start the connection process for all the endpoints which it specified it wishes to late attach in the previous step.
The application waits for the ChannelFactory to deliver a CONNECTED event for the channel, after which further produced packets will be sent to late consumers.
Note: while a set of late endpoints are being connected, service to any one of the late endpoints will not be started until the connection to all succeeds. Similarly, while a late set of endpoints are being connected, no further late endpoints may be connected until connection to the currently connecting endpoints has succeeded.

Dead consumer detachment with nvsci channels:

If a remote consumer of an nvsci channel exits gracefully, a disconnect notification will be delivered as an error to the ChannelFactory, with name of the nvsciipc endpoint through which the producer was connected to the consumer.
If a remote consumer of an nvsci channel exits disgracefully, a disconnect notification may not be delivered as in the graceful case.
In the case a consumer exits disgracefully and the disconnect notification is not delivered, the producer may see backpressure due to packets being sent and never released by the "dead" consumer.
As such, it is up to the system integrator to monitor the topology of connected applications, detect when a consumer process may have died, and indicate to the producer channel which endpoints have been effected by calling disconnectEndpoint().
disconnectEndpoint() will remove the connection to the dead consumer and return the packets of the dead consumer to the producer such that the stream may continue to operate.

Reattachment with nvsci channels is achieved with the following steps:

The application detects that the consumer has died and calls disconnectEndpoint() on the producer channel to remove the connection to the now-dead consumer.
The application calls connectEndpoint() on the producer channel to re-add the connections to the reattaching consumer.
The application calls connect() to initiate the connection to the dead consumer.
The application waits for CONNECTED event to be delvered by the ChannelFactory for the channel.
Note: the same restrictions with regard to connecting sets of consumers applies as in the late-attachment case.
Note: it is possible that a late and/or re-attaching consumer may die.
If so, the application calls disconnectEndpoint() as indicated in the first step to unblock connection to other still-alive consumers, and proceeds to call connectEndpoint() to retry the connection after CONNECTED event is delivered for the other pending consumers.