Options in this group have a major impact on the operation of Ultra Messaging. Most UM application developers will need to be aware of the default values of these options or perhaps override them.
Reference <-
broker (context) <-
- Add a broker specification to the list of brokers. Unlike most other UM options, every time this option is supplied, it adds one or more service specifications to the list, and does NOT overwrite previous specifications.
- For the configuration file as well as string API method of setting this option, you can specify multiple brokers with a comma or semicolon-separated list on a single line. Each entry contains the broker IP address (or domain name of the IP address) and destination port in the format
IP:Dest_Port[,IP:Dest_Port].
- An entry or string with the IP address of 0.0.0.0 and port 0 removes all previous broker specifications.
- When the binary form of option setting is used, UM does NOT expect an array of structures. Instead, only one broker specification can be supplied for each call to lbm_context_attr_setopt(). However, when the binary form of option retrieval lbm_context_attr_getopt() is used, the list of brokers is returned as an array, and the
optlen parameter should be set as: optlen = (max_num_brokers * sizeof(lbm_transport_broker_entry_t));
| Scope: | context |
| Type: | lbm_transport_broker_entry_t |
| When to Set: | Can only be set during object initialization. |
| Version: | This option was implemented in UMQ 6.8 |
compatibility_include_pre_um_6_0_behavior (context) <-
- Enable Ultra Messaging 6.x applications to inter-operate with pre-6.0 applications.
- Enabling this option increases overhead data on the wire and slightly changes some operational behaviors of persistent sources.
| Scope: | context |
| Type: | int |
| When to Set: | Can only be set during object initialization. |
| Version: | This option was implemented in UM 6.7 |
| String value | Integer value | Description |
| "1" | 1 | Inter-operate with pre-6.0 applications.
|
| "0" | 0 | Disable Inter-operation with pre-6.0 applications. Default for all. |
context_event_function (context) <-
- Callback function (and associated client data pointer) that is called when a context event occurs. This callback may be called inline or from an event queue, if one is given.
- If called inline, the callback function used should not block or it will block the context thread processing. See lbm_context_event_cb_proc.
| Scope: | context |
| Type: | lbm_context_event_func_t |
| When to Set: | Can only be set during object initialization. |
| Version: | This option was implemented in UMQ 1.0. |
context_name (context) <-
- The name of the context, limited to 128 alphanumeric characters, hyphens or underscores.
- This is only used for XML Configuration Files.
| Scope: | context |
| Type: | string |
| When to Set: | Can only be set during object initialization. |
| Version: | This option was implemented in LBM 4.3/UME 3.3/UMQ 2.3. |
default_interface (context) <-
- Specifies the network interface to be used as the default setting for all other interface configuration options.
- You can specify the full IP address of an interface, or just the network part (see Specifying Interfaces for details).
- Default is set to INADDR_ANY, meaning that it will not bind to a specific interface.
- Note: if specifying an interface name in an XML-format file, see Interface Device Names and XML.
| Scope: | context |
| Type: | lbm_ipv4_address_mask_t |
| Default value: | 0.0.0.0 (INADDR_ANY) |
| When to Set: | Can only be set during object initialization. |
| Version: | This option was implemented in LBM 6.10 |
dynamic_fragmentation_reduction (context) <-
- Reduce UM and/or IP fragmentation by dynamically calculating the header size per message datagram.
- Enabling this option makes UM's transport protocols more-fully utilize the configured datagram max size. This option is typically only of interest to users of LBT-RM and/or LBT-RU who need to avoid IP fragmentation, such as users of a kernel-bypass driver.
- See Dynamic Fragmentation Reduction for details.
- Enabling this option should be done in conjunction with setting the datagram max size options to 1472.
| Scope: | context |
| Type: | int |
| When to Set: | Can only be set during object initialization. |
| Version: | This option was implemented in UM 6.14 |
| Value | Description |
| 1 | Uses optimal fragmentation lengths.
|
| 0 | Uses conservative fragmentation lengths. Default for all. |
fd_management_type (context) <-
- Define the mechanism UM uses for socket file descriptor (FD) management.
- For more information, search on "file descriptors" in the Informatica Knowledge Base.
- Warning
- If using Sequential Mode and fd_management_type "wincompport", the thread that creates the context must not exit while the context is active. Furthermore, you gain a small performance improvement if the thread that creates the context is the same thread that calls lbm_context_process_events().
| Scope: | context |
| Type: | int |
| When to Set: | Can only be set during object initialization. |
| String value | Integer value | Description |
| "poll" | LBM_CTX_ATTR_FDTYPE_POLL | FD management uses poll(). Unix only. |
| "select" | LBM_CTX_ATTR_FDTYPE_SELECT | FD management uses select(). Unix only. Default for Unix. |
| "epoll" | LBM_CTX_ATTR_FDTYPE_EPOLL | FD management uses epoll(). Linux kernel 2.6 or later only. |
| "devpoll" | LBM_CTX_ATTR_FDTYPE_DEVPOLL | FD management uses the /dev/poll driver. Solaris 8 or later only. |
| "wsaeventselect" | LBM_CTX_ATTR_FDTYPE_WSAEV | FD management uses WSAEventSelect() and WaitForMultipleObjects(), which imposes a limit of 64 file descriptors. Windows only. |
| "wincompport" | LBM_CTX_ATTR_FDTYPE_WINCPORT | FD management uses Windows completion ports and completion routines. Avoids the 64 file descriptor limit set by WSAEventSelect(). Windows XP or later only. Default for Windows. |
file_descriptor_management_behavior (context) <-
- Set how the context monitors file descriptors (sockets) for events.
- The "busy_wait" selection can reduce latency and especially latency outliers (jitter), at the expense of the thread consuming 100% CPU.
- Only use "busy_wait" if there are enough cores to allocate a core exclusively to each receive thread. If there are too few cores, enabling "busy_wait" can actually increase latencies due to threads time-sharing CPU resources. Also, pinning threads to cores is highly recommended to prevent thread migration across cores.
- See Receive Thread Busy Waiting for more information.
| Scope: | context |
| Type: | int |
| When to Set: | Can only be set during object initialization. |
| Version: | This option was implemented in UM 6.12.1 |
| String value | Integer value | Description |
| "pend" | LBM_CTX_ATTR_FD_MANAGEMENT_BEHAVIOR_PEND | Causes the context or XSP thread to go to sleep waiting for socket events to happen. Default for all. |
| "busy_wait" | LBM_CTX_ATTR_FD_MANAGEMENT_BEHAVIOR_BUSY_WAIT | The context or XSP thread will check repeatedly in a tight loop (busy waiting) for socket events to happen.
|
message_selector (receiver) <-
- Enables UM to pass a message selector string to any receiver.
- The value must be an expression that conforms to JMS message selector syntax as defined in the Oracle JMS specification.
| Scope: | receiver |
| Type: | string |
| Default value: | NULL |
| When to Set: | Can only be set during object initialization. |
| Version: | This option was implemented in UMQ 5.3. |
multiple_receive_maximum_datagrams (context) <-
- The number of datagrams requested to be read at a time from a UDP-based transport socket.
- Normally, UM reads one datagram at a time from each socket that has data. This option allows the reading of multiple datagrams in a single read (using recvmmsg()), and processing them in a tight loop. This improves efficiency and can reduce average latency.
- Value of 0 means do NOT use recvmmsg().
- Only supported for LBT-RM and LBT-RU transport types. The multiple_receive_maximum_datagrams option does not apply to MIM or Topic Resolution.
- Requires glibc 2.12 or later. This option is ignored for non-Linux platforms.
- See Receive Multiple Datagrams for more information.
| Scope: | context |
| Type: | lbm_uint32_t |
| Units: | datagrams |
| Default value: | 0 |
| When to Set: | Can only be set during object initialization. |
| Version: | This option was implemented in UM 6.8. However, it did not work correctly until UM 6.9. |
operational_mode (context) <-
- The mode in which UM's context thread operates to process events.
- See Embedded Mode and Sequential Mode for more information.
- Warning
- If using sequential mode and fd_management_type "wincompport", the thread that creates the context must not exit while the context is active. Furthermore, you gain a small performance improvement if the thread that creates the context is the same thread that calls lbm_context_process_events().
| Scope: | context |
| Type: | int |
| When to Set: | Can only be set during object initialization. |
| String value | Integer value | Description |
| "embedded" | LBM_CTX_ATTR_OP_EMBEDDED | A thread is spawned within UM to handle processing of events (timers and socket events). Default for all. |
| "sequential" | LBM_CTX_ATTR_OP_SEQUENTIAL | The application is responsible for calling lbm_context_process_events() to process events. Sequential mode does not support Multi-Transport Threads. |
operational_mode (xsp) <-
- The mode in which UM operates to process events.
- See Embedded Mode and Sequential Mode for more information.
- Warning
- If using sequential mode and fd_management_type "wincompport", the thread that creates the context must not exit while the context is active. Furthermore, you gain a small performance improvement if the thread that creates the context is the same thread that calls lbm_xsp_process_events().
| Scope: | xsp |
| Type: | int |
| When to Set: | Can only be set during object initialization. |
| Version: | This option was implemented in UM 6.11 |
| String value | Integer value | Description |
| "embedded" | LBM_CTX_ATTR_OP_EMBEDDED | A thread is spawned within UM to handle processing of events (timers and socket events). Default for all. |
| "sequential" | LBM_CTX_ATTR_OP_SEQUENTIAL | The application is responsible for calling lbm_xsp_process_events() to process events.
|
ordered_delivery (receiver) <-
- Indicates whether or not the topic should have its data delivered in order and reassembled.
- For LBT-RM, LBT-RU, TCP-LB or LBT-IPC transport sessions only. (This option also applies to TCP when using Late Join because the Late Join messages are not part of the TCP message stream.)
- Changing this option from the default value to a value of 0 (zero) results in message fragments being delivered as soon as they fully arrive. Value -1 allows arrival order delivery after the reassembly of large messages.
- Note that ordering only applies to a specific topic from a single publisher. UM does not ensure ordering across topics, or on a single topic across different publishers.
- See Message Ordering and Message Fragmentation and Reassembly for more information.
| Scope: | receiver |
| Type: | int |
| When to Set: | Can only be set during object initialization. |
| String value | Integer value | Description |
| "1" | 1 | UM delivers topic messages to a receiver in-order and reassembles large messages. Default for all. |
| "-1" | -1 | UM delivers topic messages to a receiver as they arrive and may be out of order. Duplicate delivery is possible. However, UM reassembles large messages. Your application can use the sequence_number field of lbm_msg_t objects to order or discard messages.
|
| "0" | 0 | UM delivers topic messages to a receiver as they arrive and may be out of order.
WARNING: This mode of operation is deprecated and may be removed in a future UM version. The user is advised to use mode -1.
UM delivers large messages as individual fragments of less than the maximum datagram size for the transport in use. Duplicate delivery is possible. This mode is incompatible with Message Properties.
|
receiver_callback_service_time_enabled (context) <-
- Indicates if UM collects receiver callback statistics, which provide the maximum, mean and minimum time in microseconds required to complete wildcard, hot-failover, and regular receiver callbacks.
- Enabling this function slightly decreases the efficiency of the receive code path, but provides operators with greater visibility of application behavior.
| Scope: | context |
| Type: | int |
| Default value: | 0 |
| When to Set: | Can only be set during object initialization. |
| Version: | This option was implemented in UM 6.5 |
| Value | Description |
| 1 | UM collects receiver callback statistics.
|
| 0 | UM does NOT collects receiver callback statistics. Default for all. |
resolver_source_notification_function (context) <-
- Application callback function (and associated client data pointer) that is called when a new source is discovered for any topic, even if the application does not have a matching receiver.
- Contrast this with source_notification_function (receiver).
- This callback is called by the context thread and can not use an event queue. Therefore the callback function used should not block or it will delay reception of latency-sensitive messages.
- If this feature is used with a context that is connected to an SRS for Topic Resolution, resolver_service_interest_mode (context) may need to be set to "flood". See TCP-Based TR Interest.
| Scope: | context |
| Type: | lbm_src_notify_func_t |
| Default value: | NULL |
| When to Set: | Can only be set during object initialization. |
| Config File: | Cannot be set from an UM configuration file. |
source_event_function (context) <-
- Callback function (and associated client data pointer) that is called when a context source event (such as a multicast immediate mode source wakeup event) occurs.
- This callback may be called inline or from an event queue, if one is given. If called inline, the callback function used should not block or it will block the context thread processing.
| Scope: | context |
| Type: | lbm_context_src_event_func_t |
| Default value: | NULL |
| When to Set: | Can only be set during object initialization. |
| Config File: | Cannot be set from an UM configuration file. |
| Version: | This option was implemented in LBM 3.4/UME 2.1. |
source_includes_topic_index (context) <-
- Determines whether the topic index is included in the source string generated for messages and new source notifications.
- Users should not disable this.
| Scope: | context |
| Type: | int |
| When to Set: | Can only be set during object initialization. |
| Version: | This option was implemented in LBM 3.6/UME 3.0. |
| Value | Description |
| 1 | Indicates the topic index should be included in the source string. Default for all. |
| 0 | Indicates the topic index should not be included.
|
transport (source) <-
- The transport type to be used for created sources.
- Note
- With Smart Sources, only LBT-RM and LBT-RU are supported.
- Note
- With Transport Services Provider (XSP), only LBT-RM, LBT-RU, and TCP are supported.
| Scope: | source |
| Type: | int |
| When to Set: | Can only be set during object initialization. |
| String value | Integer value | Description |
| "tcp" | LBM_SRC_TOPIC_ATTR_TRANSPORT_TCP | TCP over IPv4. Default for all. |
| "lbtrm", "lbt-rm" | LBM_SRC_TOPIC_ATTR_TRANSPORT_LBTRM | UDP-based reliable multicast with unicast NAKs. |
| "lbtru", "lbt-ru" | LBM_SRC_TOPIC_ATTR_TRANSPORT_LBTRU | UDP-based reliable unicast with unicast NAKs. |
| "lbtipc", "lbt-ipc" | LBM_SRC_TOPIC_ATTR_TRANSPORT_LBTIPC | Inter-Process Communication between processes on the same host using a shared memory area. |
| "lbtsmx", "lbt-smx" | LBM_SRC_TOPIC_ATTR_TRANSPORT_LBTSMX | Shared Memory Acceleration. Ultra-low-latency Inter-Process Communication transport between processes on the same host using a shared memory area. Restrictions apply.
|
| "broker" | LBM_SRC_TOPIC_ATTR_TRANSPORT_BROKER | Sources send messages to a broker, which manages the messages for consumption. |
| "lbtrdma", "lbt-rdma" | LBM_SRC_TOPIC_ATTR_TRANSPORT_LBTRDMA | InfiniBand Remote Direct Memory Access transport. Deprecated in UM 6.9. |
transport_demux_tablesz (receiver) <-
- Specifies the size of the table used for storing receiver delivery controllers used by UM for message delivery.
- Must be a power of two (1, 2, 4, 8, 16, etc.). If not a power of two, UM generates a log warning and uses the next highest power of two. For most use cases with low to moderate numbers of topics per transport session, the default suffices. For large numbers of topics and in cases where the lowest latency is desired, set the option to the next higher power of two than the number of topics expected on the transport session.
- See Transport Demultiplexer Table Size for more information.
| Scope: | receiver |
| Type: | size_t |
| Default value: | 1 |
| When to Set: | Can only be set during object initialization. |
| Version: | This option was implemented in LBM 4.2/UME 3.2. |
transport_mapping_function (context) <-
- Application callback function (and associated client data pointer) that is called when a context is about to join a new transport session.
- This callback provides an opportunity for the user to map the transport session in question to an XSP.
- This callback is called by the context thread and can not use an event queue. Therefore the callback function used should not block or it will delay reception of latency-sensitive messages.
| Scope: | context |
| Type: | lbm_transport_mapping_func_t |
| Default value: | NULL |
| When to Set: | Can only be set during object initialization. |
| Config File: | Cannot be set from an UM configuration file. |
| Version: | This option was implemented in UM 6.11 |
transport_session_multiple_sending_threads (context) <-
- Flag that indicates the application intends to use multiple sending threads per transport session.
- Setting this flag to 0 provides a very small efficiency improvement to the process of waking up a sleeping sending thread which is blocked on a send call, but renders the send functions thread-unsafe.
- Do not use this option unless directed by UM Support.
- For the most-efficient sending method, see Smart Sources.
| Scope: | context |
| Type: | int |
| When to Set: | Can only be set during object initialization. |
| Value | Description |
| 1 | Indicates the application does intend to use multiple sending threads per transport session and that UM should make that assumption. Default for all. |
| 0 | Indicates the application does not intend to use multiple sending threads per transport session and that UM should make that assumption.
|
transport_session_single_receiving_thread (context) <-
- Flag that indicates the application intends to use only a single thread for receiving.
- This improves message reception latency and outliers by converting certain thread-safe operations to more-efficient thread-unsafe operations. For example, certain bus-locked operations (e.g. atomic increment) are replaced by non-bus-locked equivalents (e.g. non-atomic increment).
- See Single Receiving Thread for more information and restrictions.
| Scope: | context |
| Type: | int |
| When to Set: | Can only be set during object initialization. |
| Version: | This option was implemented in UM 6.12 |
| Value | Description |
| 1 | The user intends to ensure that only one thread is used to process LBM transport messages.
|
| 0 | No assumptions will be made by LBM regarding threading. Default for all. |
transport_source_side_filtering_behavior (source) <-
- Enable and set the behavior for UM sources to filter out topics prior to sending to clients.
- This option is not applicable for multicast-based sources (LBT-RM). These control messages are sent to the TCP UIM port (also known as the "request port") of the senders context and processed internally.
- This option affects the transport session underlying the source rather than the source itself. See Source Object for additional information.
| Scope: | source |
| Type: | int |
| When to Set: | Can only be set during object initialization. |
| String value | Integer value | Description |
| "none" | LBM_SRC_TOPIC_ATTR_SSF_NONE | The source sends all data to all clients regardless of the topics they are listening to. Default for all. |
| "inclusion" | LBM_SRC_TOPIC_ATTR_SSF_INCLUSION | The source sends only that data to a client that the client specifically requests. |
| "ulb" | LBM_SRC_TOPIC_ATTR_SSF_ULB | The ULB source sends control and data only to the ULB client that the source has specifically assigned for a given message. See ULB Performance for more information. This selection was added in UM version 6.12.
|
transport_topic_sequence_number_info_active_threshold (source) <-
- Duration in seconds that an inactive source sends contiguous Topic Sequence Number Info (TSNI) messages.
- A value of 0 indicates that sources continue sending TSNIs until data messages resume, with no timeout.
- TSNIs are sent at an interval defined by transport_topic_sequence_number_info_interval (source).
- See also Interrelated Configuration Options.
| Scope: | source |
| Type: | lbm_ulong_t |
| Units: | seconds |
| Default value: | 60 |
| When to Set: | Can only be set during object initialization. |
| Version: | This option was implemented in LBM 4.0 |
transport_topic_sequence_number_info_interval (source) <-
- The interval between Topic Sequence Number Info (TSNI) messages that a source sends.
- TSNI messages are enabled on all transports except LBT-SMX, and they carry the topic sequence number of the latest message sent by the source. The interval is also a source inactivity threshold. In other words, a source does not send TSNIs during normal data transmission, but once the source is inactive for as long as this interval, it starts sending TSNI messages. A value of 0 turns off TSNI messages for the source.
- See also Interrelated Configuration Options.
| Scope: | source |
| Type: | lbm_ulong_t |
| Units: | milliseconds |
| Default value: | 5000 (5 second) |
| When to Set: | Can only be set during object initialization. |
| Version: | This option was implemented in LBM 3.3 |
transport_topic_sequence_number_info_request_interval (receiver) <-
- The interval at which the receiver requests a Topic Sequence Number Information Record (TSNI) from the source.
- Controlling these requests helps reduce receiver start-up traffic on your network.
| Scope: | receiver |
| Type: | lbm_ulong_t |
| Units: | milliseconds |
| Default value: | 1000 (1 second) |
| When to Set: | Can only be set during object initialization. |
| Version: | This option was implemented in UMP 6.0 |
transport_topic_sequence_number_info_request_maximum (receiver) <-
- The maximum number of requests the receiver issues for a Topic Sequence Number Information Record (TSNI) from the source.
- If the receiver has not received an TSNI after this number of requests, it stops requesting.
| Scope: | receiver |
| Type: | lbm_ulong_t |
| Default value: | 60 |
| When to Set: | Can only be set during object initialization. |
| Version: | This option was implemented in UMP 6.0 |
use_extended_reclaim_notifications (source) <-
- Specifies which reclaim notification your application receives.
- The older LBM_SRC_EVENT_UME_MESSAGE_RECLAIMED source event delivered the structure lbm_src_event_ume_ack_info_t. The newer LBM_SRC_EVENT_UME_MESSAGE_RECLAIMED_EX source event delivers the structure lbm_src_event_ume_ack_ex_info_t, which contains additional information.
| Scope: | source |
| Type: | int |
| When to Set: | Can only be set during object initialization. |
| Version: | This option was implemented in LBM 4.2. |
| Value | Description |
| 1 | Indicates your application receives the expanded reclaim notification. Default for all. |
| 0 | Indicates your application receives the older reclaim notification.
|
zero_transports_function (xsp) <-
- Application callback function (and associated client data pointer) that is called when the number of transports associated with a given XSP falls to zero.
- This callback provides an opportunity to delete the given XSP.
- This callback is called by the context thread and can not use an event queue. Therefore the callback function used should not block or it will delay reception of latency-sensitive messages.
| Scope: | xsp |
| Type: | lbm_xsp_zero_transports_func_t |
| Default value: | NULL |
| When to Set: | Can only be set during object initialization. |
| Config File: | Cannot be set from an UM configuration file. |
| Version: | This option was implemented in UM 6.11 |