LBT-RU Transport Session Management <-
The image below illustrates the relationship between the primary LBT-RU network options.
When a source is created, the application can explicitly map it to a transport session by setting the transport_lbtru_port (source) option. If a previous source was created on the same context with the same port, this new source will be mapped to the same transport session. However, two different contexts on the same host may not share the same port number. If a source is created with a port number that is already in use, UM will return an error.
Alternatively, if the application does not explicitly specify a source port, UM will implicitly assign the new source to a pool of transport sessions defined when the context was created. The pool is defined as a range of port numbers specified by the options transport_lbtru_port_low (context) and transport_lbtru_port_high (context). In addition, the option transport_lbtru_maximum_ports (context) defines the number of transport sessions in the pool.
When a new source is created and the source port is not explicitly defined, UM will check to see how many transport sessions are currently active from the pool within the context. If it is less than the number in the pool, then UM will activate the next transport session in the range. However, if the context already has activated all transport sessions in the pool, then the new topic is mapped to one of the existing transport sessions, in round-robin fashion.
Note that if you intend to do both explicit mapping and implicit mapping to the default pool of transport sessions, the LBT-RU transport behaves differently than some of the other transport types (e.g. LBT-RM). Any explicitly given port will be added to the default pool. This means that subsequent implicit mappings to the default pool can include this newly added port.
Notice that the default range of ports, 14380 to 14389, is 10 ports. But the default number of transport sessions in the pool is 5. This allows two contexts to be created on the same host and use the same configuration. If more than 2 contexts are intended to co-exist on the same host, the port range and number of transport session per context must be managed to give a unique port number to every transport session.
The option transport_lbtru_interface (source) may be used on LBT-RU sources to choose particular interface, overriding the default INADDR_ANY which accepts connections on all interfaces. Similarly, transport_lbtru_interface (receiver) may be used on receivers to choose a particular interface for outgoing connections.
Reference <-
transport_lbtru_interface (receiver) <-
- Specifies the network interface over which UM LBT-RU receivers read application data messages.
- Can specify full IP address of interface, or just network part (see Specifying Interfaces for details).
- Default is set to default_interface (context), if specified. Otherwise, it is set to INADDR_ANY, meaning that it will accept incoming connection requests from any interface.
- Note: if specifying an interface name in an XML-format file, see Interface Device Names and XML.
Scope: receiver Type: lbm_ipv4_address_mask_t Default value: 0.0.0.0 (INADDR_ANY) When to Set: Can only be set during object initialization.
transport_lbtru_interface (source) <-
- Specifies the network interface over which UM LBT-RU sources receive connection requests from topic receivers.
- Can specify full IP address of interface, or just network part (see Specifying Interfaces for details).
- Be aware that this option is applied to the transport session when the first topic is created on that session. Thus, setting a different interface for a subsequent topic that maps onto the same transport session will have no effect.
- Default is set to default_interface (context), if specified. Otherwise, it is set to INADDR_ANY, meaning that it will accept incoming connection requests from any interface.
- Note: if specifying an interface name in an XML-format file, see Interface Device Names and XML.
Scope: source Type: lbm_ipv4_address_mask_t Default value: 0.0.0.0 (INADDR_ANY) When to Set: Can only be set during object initialization.
transport_lbtru_maximum_ports (context) <-
- Maximum size of LBT-RU source transport session default pool.
- See LBT-RU Transport Session Management for how LBT-RU source transport sessions are managed.
Scope: context Type: lbm_uint16_t Units: number of ports Default value: 5 When to Set: Can only be set during object initialization.
transport_lbtru_port (source) <-
- The UDP port to be used for the source transport session.
- This is the source-side option. For receive-side ports, see transport_lbtru_port_low (receiver).
- Setting this option to non-zero overrides the use of the default pool of LBT-RU source transport sessions.
- See LBT-RU Transport Session Management for how LBT-RU source transport sessions are managed.
- See Port Assignments for more information about configuring ports.
- Note that this port is only used by LBT-RU sources, not receivers.
- Attention
- If a source is configured for a port that is not currently part of the transport session default pool, UM will create a new transport session for this port and add it to the default pool. See Transport Session Differences.
Scope: source Type: lbm_uint16_t Default value: 0 (use open port) Byte order: Network When to Set: Can only be set during object initialization.
transport_lbtru_port_high (context) <-
- High UDP port number of range for default pool of LBT-RU source transport sessions.
- When transport_lbtru_port (source) is not specified, a newly-created transport session will use an unused port from this range. Receivers that join the source's transport session send connection requests, acknowledgements, and NAKs to the source port.
- See also transport_lbtru_port_high (context).
- This is the source-side option. For the corresponding receiver option, see transport_lbtru_port_high (receiver).
- See LBT-RU Transport Session Management for how LBT-RU source transport sessions are managed.
- See Port Assignments for more information about configuring ports.
Scope: context Type: lbm_uint16_t Default value: 14389 Byte order: Host When to Set: Can only be set during object initialization.
transport_lbtru_port_high (receiver) <-
- High port number to use for receiving LBT-RU data.
- This is the receive-side option. For the corresponding source option, see transport_lbtru_port_high (context).
- When a newly-created receiver joins a source's transport session, it finds a free port from this range, binds to it, and informs the source of the receiver's IP and port. The UM source will send message data to that IP and port.
- Unlike most UM port ranges, if the library is not able to find an unused port in this range, it will log a warning (Core-5688-3300), but instead of failing the receiver creation, it will allocate a port from the host's ephemeral pool and operate normally. Thus, it is possible for a receiver to get messages on a port outside of the configured range.
- See Port Assignments for more information about configuring ports.
Scope: receiver Type: lbm_uint16_t Default value: 14379 Byte order: Host When to Set: Can only be set during object initialization.
transport_lbtru_port_low (context) <-
- Low UDP port number of range for default pool of LBT-RU source transport sessions.
- When transport_lbtru_port (source) is not specified, a newly-created transport session will use an unused port from this range. Receivers that join the source's transport session send connection requests, acknowledgements, and NAKs to the source port.
- See also transport_lbtru_port_high (context).
- This is the source-side option. For the corresponding receiver option, see transport_lbtru_port_low (receiver).
- See LBT-RU Transport Session Management for how LBT-RU source transport sessions are managed.
- See Port Assignments for more information about configuring ports.
Scope: context Type: lbm_uint16_t Default value: 14380 Byte order: Host When to Set: Can only be set during object initialization.
transport_lbtru_port_low (receiver) <-
- Low port number to use for receiving LBT-RU data.
- This is the receive-side option. For the corresponding source option, see transport_lbtru_port_low (context).
- When a newly-created receiver joins a source's transport session, it finds a free port from this range, binds to it, and informs the source of the receiver's IP and port. The UM source will send message data to that IP and port.
- Unlike most UM port ranges, if the library is not able to find an unused port in this range, it will log a warning (Core-5688-3300), but instead of failing the receiver creation, it will allocate a port from the host's ephemeral pool and operate normally. Thus, it is possible for a receiver to get messages on a port outside of the configured range.
- See Port Assignments for more information about configuring ports.
Scope: receiver Type: lbm_uint16_t Default value: 14360 Byte order: Host When to Set: Can only be set during object initialization.