sACN Receiver Options

Macros
#define	SACN_RECEIVER_THREAD_PRIORITY   ETCPAL_THREAD_DEFAULT_PRIORITY
	The priority of each sACN receiver thread.
#define	SACN_RECEIVER_THREAD_STACK   ETCPAL_THREAD_DEFAULT_STACK
	The stack size of each sACN receiver thread.
#define	SACN_RECEIVER_THREAD_NAME   "sACN Receive Thread"
	The name to assign each sACN receiver thread.
#define	SACN_RECEIVER_READ_TIMEOUT_MS   100
	The maximum amount of time that a call to sacnrecv_read() will block waiting for data, in milliseconds.
#define	SACN_RECEIVER_MAX_UNIVERSES   1
	The maximum number of sACN universes that can be listened to simultaneously.
#define	SACN_RECEIVER_MAX_SOURCES_PER_UNIVERSE   4
	The maximum number of sources that can be tracked on each universe.
#define	SACN_RECEIVER_TOTAL_MAX_SOURCES   (SACN_RECEIVER_MAX_UNIVERSES * SACN_RECEIVER_MAX_SOURCES_PER_UNIVERSE)
	The total maximum number of sources that can be tracked in all universes.
#define	SACN_RECEIVER_LIMIT_BIND   (!_WIN32 && !__APPLE__)
	If set to 1, bind only two sockets per thread to reduce duplicate multicast traffic.
#define	SACN_RECEIVER_SOCKET_PER_NIC   (_WIN32)
	Configure whether or not to use the PKTINFO sockopts to determine which NIC received a packet.
#define	SACN_RECEIVER_MAX_SUBS_PER_SOCKET   20
	The maximum number of multicast subscriptions supported per shared socket.
#define	SACN_RECEIVER_ENABLE_SO_REUSEPORT   1
	Determines whether sACN should try to enable the SO_REUSEPORT socket option.
#define	SACN_RECEIVER_ENABLE_SO_RCVBUF   1
	Determines whether sACN should try to set the SO_RCVBUF socket option.
#define	SACN_RECEIVER_MAX_THREADS   1
	Currently unconfigurable; will be configurable in the future.
#define	SACN_RECEIVER_MAX_FOOTPRINT   512
	Currently unconfigurable; will be configurable in the future.

Detailed Description

Configuration options for the sACN Receiver module.

Macro Definition Documentation

SACN_RECEIVER_ENABLE_SO_RCVBUF

#define SACN_RECEIVER_ENABLE_SO_RCVBUF   1

Determines whether sACN should try to set the SO_RCVBUF socket option.

If enabled, the library will try to set it to #SACN_RECEIVER_SOCKET_RCVBUF_SIZE and log an error if it failed.

Define to 0 to disable. Then the library will not attempt this sockopt, avoiding potential errors.

SACN_RECEIVER_ENABLE_SO_REUSEPORT

#define SACN_RECEIVER_ENABLE_SO_REUSEPORT   1

Determines whether sACN should try to enable the SO_REUSEPORT socket option.

If enabled, the library will try to enable this socket option and fail to initialize if it fails.

Define to 0 to disable. Then the library will not attempt this sockopt, avoiding potential errors.

SACN_RECEIVER_LIMIT_BIND

#define SACN_RECEIVER_LIMIT_BIND   (!_WIN32 && !__APPLE__)

If set to 1, bind only two sockets per thread to reduce duplicate multicast traffic.

Each sACN receiver socket joins up to SACN_RECEIVER_MAX_SUBS_PER_SOCKET unique multicast groups. If SACN_RECEIVER_LIMIT_BIND is 0, then each socket binds to the wildcard. On certain platforms, this results in multicast traffic being duplicated between sockets. In this case, setting SACN_RECEIVER_LIMIT_BIND to 1 will limit sACN to binding (and polling) just two sockets per thread (one for IPv4 and another for IPv6). The purpose is to cause all multicast and unicast traffic to go to the bound sockets and reduce duplication. This has been verified to work on Linux and lwIP.

Set this to 0 in your sacn_config.h if the default causes packets to be lost on your platform.

Don't change this option unless you know what you're doing.

SACN_RECEIVER_MAX_SOURCES_PER_UNIVERSE

#define SACN_RECEIVER_MAX_SOURCES_PER_UNIVERSE   4

The maximum number of sources that can be tracked on each universe.

If this is set to 0, the Receiver, Merge Receiver, and Source Detector APIs are disabled and no memory pools are allocated for them.

Meaningful only if SACN_DYNAMIC_MEM is defined to 0. This includes sources at any priority; all sources for a given universe are tracked, even those with a lower priority than the highest-priority source.

SACN_RECEIVER_MAX_SUBS_PER_SOCKET

#define SACN_RECEIVER_MAX_SUBS_PER_SOCKET   20

The maximum number of multicast subscriptions supported per shared socket.

We cap multicast subscriptions at a certain number to keep it below the system limit.

Don't change this option unless you know what you're doing.

SACN_RECEIVER_MAX_UNIVERSES

#define SACN_RECEIVER_MAX_UNIVERSES   1

The maximum number of sACN universes that can be listened to simultaneously.

If this is set to 0, the Receiver, Merge Receiver, and Source Detector APIs are disabled and no memory pools are allocated for them.

Meaningful only if SACN_DYNAMIC_MEM is defined to 0.

SACN_RECEIVER_READ_TIMEOUT_MS

#define SACN_RECEIVER_READ_TIMEOUT_MS   100

The maximum amount of time that a call to sacnrecv_read() will block waiting for data, in milliseconds.

It is recommended to keep this time short to avoid delays on shutdown.

SACN_RECEIVER_SOCKET_PER_NIC

#define SACN_RECEIVER_SOCKET_PER_NIC   (_WIN32)

Configure whether or not to use the PKTINFO sockopts to determine which NIC received a packet.

If set to 0, the corresponding PKTINFO sockopts for IPv4 and/or IPv6 are enabled, and the NIC is obtained from ancillary data via recvmsg. This is not supported on Windows due to performance issues that occur when either of the PKTINFO sockopts are enabled.

If set to 1, a socket will only be able to subscribe on one NIC instead of all of them. This will result in the creation of more sockets to cover all the NICs on the system. The NIC will then be determined by the socket that received the data. This will likely not work on Linux or lwIP, since each bound socket is susceptible to receiving data from subscriptions on other sockets.

Don't change this option unless you know what you're doing.

SACN_RECEIVER_THREAD_NAME

#define SACN_RECEIVER_THREAD_NAME   "sACN Receive Thread"

The name to assign each sACN receiver thread.

This is useful for distinguishing the receiver threads from other threads when debugging.

SACN_RECEIVER_THREAD_PRIORITY

#define SACN_RECEIVER_THREAD_PRIORITY   ETCPAL_THREAD_DEFAULT_PRIORITY

The priority of each sACN receiver thread.

This is usually only meaningful on real-time systems.

SACN_RECEIVER_THREAD_STACK

#define SACN_RECEIVER_THREAD_STACK   ETCPAL_THREAD_DEFAULT_STACK

The stack size of each sACN receiver thread.

It's usually only necessary to worry about this on real-time or embedded systems.

SACN_RECEIVER_TOTAL_MAX_SOURCES

#define SACN_RECEIVER_TOTAL_MAX_SOURCES   (SACN_RECEIVER_MAX_UNIVERSES * SACN_RECEIVER_MAX_SOURCES_PER_UNIVERSE)

The total maximum number of sources that can be tracked in all universes.

If this is set to 0, the Receiver, Merge Receiver, and Source Detector APIs are disabled and no memory pools are allocated for them.

Meaningful only if SACN_DYNAMIC_MEM is defined to 0. Defaults to SACN_RECEIVER_MAX_UNIVERSES * SACN_RECEIVER_MAX_SOURCES_PER_UNIVERSE, but can be made lower if an application wants to impose a global hard source limit. The total number of sources that will be handled will be the lower of SACN_RECEIVER_TOTAL_MAX_SOURCES and (SACN_RECEIVER_MAX_UNIVERSES * SACN_RECEIVER_MAX_SOURCES_PER_UNIVERSE).

Note that this limit counts the same remote source on multiple universes as multiple sources, one per universe.