Configuration Guide

Late Join Options

Late Join allows sources to save a predefined amount of their messaging traffic for late-joining receivers. Sources set the configuration options that determine whether they use Late Join or not, and receivers set options that determine whether they will participate in Late Join recovery if sources use Late Join.

UMP's persistent store is built on Late Join technology. In the Estimating Recovery Time discussion below, the terms Late Join buffers and UMP store are roughly equivalent.

For more, review Late Join in the Ultra Messaging Concepts Guide, especially Configuring Late Join for Large Numbers of Messages.

# Estimating Recovery Time <-

Late Join message recovery time is a function of how much data must be recovered and how fast messages are retransmitted. To estimate Late Join recovery time R in minutes, use the formula:

    R = D / ( 1 - ( txrate / rxrate ) )

where:
  D is the downtime (in minutes) across all receivers
  txrate is the average source transmission rate of normal (live stream) messages during recovery (in kmsgs/sec).
  rxrate is the average source retransmission rate from source-side Late Join buffers during recovery (in kmsgs/sec). This rate needs to be greater than txrate.

For example, consider the following scenario:
  D = 10 minutes
  txrate = 10k messages / second
  rxrate = 25k messages / second

Plugging these values into the formula gives an estimated recovery time in minutes:

    R = 10 / ( 1 - ( 10 / 25 ) )

or 16.67 minutes. Note that this formula assumes the following:

- Retransmit rate(rxrate) is as linear as possible with use of option response_tcp_nodelay (context) to 1.
- Transmit rate (txrate) from all relevant sources is fairly constant and equal
- Retransmit rate (rxrate) from Late Join buffers is fairly constant and equal, and should be measured in a live test, if possible. You can adjust the recovery rate with two Late Join configuration options: retransmit_request_outstanding_maximum (receiver) and retransmit_request_interval (receiver).

# Reference <-

## late_join (source) <-

  Configure the source to enable both Late Join and Off-Transport Recovery operation for receivers.

  See Using Late Join and Off-Transport Recovery (OTR).

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

  Value | Description
  --- | ---
  1 | Enable source for Late Join and OTR. (Forced on for Persistence.)
  0 | Disable source for Late Join and OTR. Default for all.

## late_join_info_request_interval (receiver) <-

  The interval at which the receiver requests a Late Join Information Record (LJI) from the source.

  Controlling these requests helps reduce receiver start-up traffic on your network.

  See Late Join.

  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

## late_join_info_request_maximum (receiver) <-

  The maximum number of requests the receiver issues for a Late Join Information Record (LJI) from the source.

  If the receiver has not received an LJI 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

## retransmit_initial_sequence_number_request (receiver) <-

  When a late-joining receiver detects (from the topic advertisement) that a source is enabled for Late Join but has sent no messages, this flag option lets the receiver request an initial sequence number from a source.

  Sources respond with a TSNI.

  Scope: | receiver
  Type: | int
  Default value: | 1
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 4.2.

  Value | Description
  --- | ---
  1 | The receiver requests an initial sequence number from Late Join enabled sources that have not sent any messages. Default for all.
  0 | The receiver does not request an initial sequence number.

## retransmit_message_caching_proximity (receiver) <-

  This option determines how a receiver handles new messages that are being published while the receiver is in the process of recovering older messages through the retransmit request mechanism.

  A receiver has the ability to cache new messages during the recovery process in order to facilitate a smooth transition from recovery to live stream. This option value determines how close (proximate) a newly received message sequence number must be to the latest retransmitted sequence number for the receiver to cache it. New messages that arrive while the receiver is not within proximity will be discarded, and the receiver will attempt to recover those messages later via OTR.

  An option value between 0 and 0x7FFFFFFE (2,147,483,646) enables proximity caching, with larger values allowing caching to begin earlier during recovery. Values 0x7FFFFFFF and above disable proximity caching. This value has meaning for only receivers using ordered delivery of data.

  See Configuring Late Join for Large Numbers of Messages for additional information.

  Scope: | receiver
  Type: | lbm_ulong_t
  Units: | messages
  Default value: | 5000 (was 0xFFFFFFFF = 4,294,967,295 in versions prior to 6.8)
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 3.3.2/UME 2.0.

## retransmit_request_interval (receiver) <-

  The interval between retransmission request messages to the source.

  See Configuring Late Join for Large Numbers of Messages for additional information.

  Scope: | receiver
  Type: | lbm_ulong_t
  Units: | milliseconds
  Default value: | 500 (0.5 seconds)
  When to Set: | Can only be set during object initialization.

## retransmit_request_maximum (receiver) <-

  The maximum number of messages to request, counting backward from the current latest message, when late-joining a topic.

  Due to network timing factors, UM may transmit an additional message. For example, a value of 5 sends 5 or possibly 6 retransmit messages to the new receiver. (Hence, you cannot request and be guaranteed to receive only 1 last message–you may get 2.)

  A value of 0 indicates no maximum (receiver requests all available messages).

  Scope: | receiver
  Type: | lbm_ulong_t
  Units: | messages
  Default value: | 0
  When to Set: | Can only be set during object initialization.

## retransmit_request_message_timeout (receiver) <-

  The maximum time from when a receiver first sends a retransmission request to when the receiver gives up on receiving the retransmitted message and reports loss.

  See Configuring Late Join for Large Numbers of Messages for additional information.

  Scope: | receiver
  Type: | lbm_ulong_t
  Units: | milliseconds
  Default value: | 10000 (10 seconds)
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in UM 6.0

## retransmit_request_outstanding_maximum (receiver) <-

  The maximum number of messages to request and to remain active (pending) at a single time.

  Value must be greater than zero.

  If this option is increased significantly, retransmit_request_interval (receiver) should also be increased.

  See Configuring Late Join for Large Numbers of Messages for additional information.

  Scope: | receiver
  Type: | lbm_ulong_t
  Units: | messages
  Default value: | 10
  When to Set: | Can only be set during object initialization.

## retransmit_retention_age_threshold (source) <-

  Specifies the minimum age of messages in the retained message buffer before UM can delete them. UM cannot delete any messages younger than this value.

  For UMS Late Joins, this and retransmit_retention_size_threshold (source) are the only options that affect the retention buffer size. For UME, these two options combined with retransmit_retention_size_limit (source) affect the retention buffer size. UM deletes a message when it meets all configured threshold criteria, i.e., the message is older than this option (if set), and the size of the retention buffer exceeds the `retransmit_retention_size_threshold` (if set). A value of 0 sets the age threshold to be always triggered, in which case deletion is determined by other threshold criteria.

  With Smart Sources, this option is ignored. Retention buffers are preallocated and are never deleted.

  Scope: | source
  Type: | lbm_ulong_t
  Units: | seconds
  Default value: | 0 (threshold always triggered)
  When to Set: | Can only be set during object initialization.

## retransmit_retention_size_limit (source) <-

  Sets a maximum limit on the size of the source's retransmit retention buffer when using a persistent Store.

  With UME, stability and delivery confirmation events can delay the deletion of retained messages, which can increase the size of the buffer above the retransmit_retention_size_threshold (source). Hence, this option provides a hard size limit. UM sets a minimum value for this option of 8K for UDP and 64K for TCP, and issues a log warning if you set a value less than the minimum.

  With Smart Sources, this option is ignored. Retention buffers are preallocated.

  Scope: | source
  Type: | size_t
  Units: | bytes
  Default value: | 25165824 (24 MB)
  When to Set: | Can only be set during object initialization.

## retransmit_retention_size_threshold (source) <-

  Specifies the minimum size of the retained message buffer before UM can delete messages.

  The buffer must reach this size before UM can delete any messages older than retransmit_retention_age_threshold (source).

  For persistence, these options combined with retransmit_retention_size_limit (source) affect the retention buffer size. A value of 0 sets the size threshold to be always triggered, in which case deletion is determined by other threshold criteria.

  With Smart Sources, this option is ignored. Retention buffers are preallocated and are never deleted.

  Scope: | source
  Type: | size_t
  Units: | bytes
  Default value: | 0 (threshold always triggered)
  When to Set: | Can only be set during object initialization.

## use_late_join (receiver) <-

  Flag indicating if the receiver should participate in a late join operation or not.

  See Late Join for more information.

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

  Value | Description
  --- | ---
  1 | The receiver will participate in using late join if offered by the source. Default for all.
  0 | The receiver will not participate in using late join if offered by the source.