Configuration Guide

Unicast Immediate Messaging Operation Options

In early versions of UM, the Unicast Immediate Messaging (UIM) feature was primarily used to support the Request/Response feature. Therefore, the configuration options related to UIMs have names that start with "request" and "response". However, as UM has evolved, the UIM feature has come to be used by a great many UM features, such as Late Join, Persistence, and Queuing.

To maintain backwards compatibility, the old names of the configuration options have been retained. The reader must simply be aware that the "request_..." and "response_..." options affect more than just the request/response feature.

See Unicast Immediate Messaging for general information on UIM. See also Unicast Immediate Messaging Network Options for network-oriented options.

# Reference <-

## request_tcp_activity_timeout (context) <-

  This timeout option enables the Request TCP socket to use SO_KEEPALIVE to detect when the TCP connection does not cleanly disconnect or is no longer reachable.

  This timeout value must be either 0 (to disable the feature) or greater than or equal to 20,000 (20 seconds). Note that the time specified is only approximate; the operating system has wide discretion for deciding exactly when to disconnect a connection, and the actual time can be more than a factor of 2 different from this configured value.

  This option is only available on Linux or Windows platforms.

  See TCP Disconnections for more information.

  Scope: | context
  Type: | int
  Units: | milliseconds
  Default value: | 0
  When to Set: | Can only be set during object initialization.
  Version: | UM 6.16

## request_tcp_exclusiveaddr (context) <-

  Controls whether the context sets SO_EXCLUSIVEADDRUSE before it binds to the UIM port (also known as the "Request Port").

  Applicable only to Windows.

  The default setting in Windows allows multiple binds to the same port. By default, UM will set SO_EXCLUSIVEADDRUSE to minimize port sharing. Refer to Microsoft's web site for more information on SO_EXCLUSIVEADDRUSE.

  See Unicast Immediate Messaging for general information on UIM.

  Scope: | context
  Type: | int
  When to Set: | Can only be set during object initialization.

  Value | Description
  --- | ---
  1 | Set SO_EXCLUSIVEADDRUSE. Default for Windows.
  0 | Do not set SO_EXCLUSIVEADDRUSE.

## request_tcp_listen_backlog (context) <-

  The backlog used in the TCP listen() call to set the queue length for incoming UIM connections (also known as "request connections" or "response connections").

  See Unicast Immediate Messaging for general information on UIM.

  Scope: | context
  Type: | int
  Default value: | 5
  When to Set: | Can only be set during object initialization.

## request_tcp_reuseaddr (context) <-

  Controls whether the context sets SO_REUSEADDR before it binds to the UIM port (also known as the "Request Port").

  See Unicast Immediate Messaging for general information on UIM.

Warning
  This option is not recommended for Microsoft Windows users because the SO_REUSEADDR socket option in Windows allows a socket to forcibly bind to a port in use by another socket. Multiple sockets using the same port results in indeterminate behavior.

  Scope: | context
  Type: | int
  When to Set: | Can only be set during object initialization.

  Value | Description
  --- | ---
  1 | Set SO_REUSEADDR.
  0 | Do not set SO_REUSEADDR. Default for all.

## response_session_maximum_buffer (context) <-

  Maximum number of bytes of application data which can be queued for a UIM connection.

  When the application sends a UIM message via a UIM API function, UM may not be able to immediately send the message. For example, if many messages are bring sent but the receiver is slow, TCP flow control may prevent messages from being sent. UM will queue outgoing UIM messages that cannot be sent immediately. If that queue fills, then the UIM send API will either block, or will return -1 with the error code LBM_EWOULDBLOCK.

  This queue is shared across all API methods of sending UIMs, including lbm_unicast_immediate_message(), lbm_send_response(), etc.

  See Unicast Immediate Messaging for general information on UIM.

  Scope: | context
  Type: | lbm_ulong_t
  Units: | bytes
  Default value: | 65536
  When to Set: | Can only be set during object initialization.

## response_session_sender_socket_buffer (context) <-

  Value used to set the SO_SNDBUF socket option for the UIM sending socket.

  In some cases the OS will not allow all of this value to be used.

  A value of 0 instructs UM to use the OS defaults. See Socket Buffer Sizes for platform-dependent information.

  See Unicast Immediate Messaging for general information on UIM.

  Scope: | context
  Type: | lbm_ulong_t
  Units: | bytes
  Default value: | 0 (use TCP autotuning)
  When to Set: | Can only be set during object initialization.

## response_tcp_activity_timeout (context) <-

  This timeout option enables the Response TCP socket to use SO_KEEPALIVE to detect when the TCP connection does not cleanly disconnect or is no longer reachable.

  This timeout value must be either 0 (to disable the feature) or greater than or equal to 20,000 (20 seconds). Note that the time specified is only approximate; the operating system has wide discretion for deciding exactly when to disconnect a connection, and the actual time can be more than a factor of 2 different from this configured value.

  The special value -1 can be specified to copy the value supplied for request_tcp_activity_timeout (context).

  This option is only available on Linux or Windows platforms.

  See TCP Disconnections for more information.

  Scope: | context
  Type: | int
  Units: | milliseconds
  Default value: | -1
  When to Set: | Can only be set during object initialization.
  Version: | UM 6.16

## response_tcp_deletion_timeout (context) <-

  Time period that the context waits before deleting a UIM connection.

  UIM connections are dynamic, being created when needed and deleted when no longer needed. The purpose of this timer is to keep the TCP connection up for a time after it is no longer needed, just in case it becomes needed again. The exact semantics of this timer are described in Unicast Immediate Messaging.

  NOTE: When using Off-Transport Recovery (OTR), this value must be longer than otr_request_maximum_interval (receiver).

  Scope: | context
  Type: | lbm_ulong_t
  Units: | milliseconds
  Default value: | 20,000 (20 seconds)
  When to Set: | Can only be set during object initialization.

## response_tcp_interface (context) <-

  Specifies the network interface over which UM initiates outgoing TCP connections for UIMs.

  You can specify the full IP address of interface, or just the 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 not bind to a specific interface. You can also set this option to 0.0.0.0/0 which produces the same result.

  See Unicast Immediate Messaging for general information on UIM.

  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.

## response_tcp_nodelay (context) <-

  Controls whether the context sets TCP_NODELAY before it binds to the UIM port (also known as the "Request Port").

  Setting TCP_NODELAY disables Nagle's algorithm, which somewhat decreases the efficiency and throughput of TCP, but decreases the latency of individual messages.

  See Unicast Immediate Messaging for general information on UIM.

  Scope: | context
  Type: | int
  When to Set: | Can only be set during object initialization.

  Value | Description
  --- | ---
  1 | TCP response sockets should set TCP_NODELAY (disable Nagle).
  0 | TCP response sockets should not set TCP_NODELAY (leave Nagle enabled). Default for all.