Configuration Guide

Smart Source Options

See Smart Sources for introductory information on Smart Sources.

# Reference <-

## mem_mgt_callbacks (source) <-

  Callback functions (and optional associated client data pointer) that are called when a Smart Source allocates, reallocates, and deallocates memory.

  The callbacks are called by the user thread that invokes lbm_ssrc_create() for create, and by lbm_ssrc_delete() for delete. See lbm_mem_mgt_malloc_cb_func, lbm_mem_mgt_realloc_cb_func, lbm_mem_mgt_free_cb_func.

  See Smart Sources and Memory Management for restrictions.

  See Smart Sources for more information about Smart Sources.

  Scope: | source
  Type: | lbm_mem_mgt_callbacks_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

## smart_src_enable_spectrum_channel (source) <-

  This option enables spectrum channel use with Smart Sources.

  See Smart Sources and Spectrum for restrictions.

  See Smart Sources for more information about Smart Sources.

  Scope: | source
  Type: | int
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in UM 6.11

  Value | Description
  --- | ---
  1 | The source will allocate spectrum channel resources.
  0 | The source will not allocate spectrum channel resources. Default for all.

## smart_src_max_message_length (source) <-

  The number of bytes allocated for application messages to each Smart Source buffer.

  Smart Source buffers are pre-allocated when the source is created. The final allocation size is the value specified for this option, plus the sizes required for internal headers, plus a possible padding value intended to ensure that the final internal buffer allocation is a power of 2. Because of these additions, the actual amount of memory allocated can be over twice as much as requested.

  There are three types of buffers sized by smart_src_max_message_length: user buffers, retention buffers (for late join), and transmission window buffers (for transport retransmissions). User buffers and retention buffers are created by lbm_ssrc_create(), and are deleted by lbm_ssrc_delete(). Transmission window buffers are created only when the first Smart Source on a transport session is created, and are deleted when the last Smart Source on a transport session is deleted.

  Different numbers of buffers can be allocated for each buffer type. See smart_src_user_buffer_count (source) for user buffers, transport_lbtrm_smart_src_transmission_window_buffer_count (source) and transport_lbtru_smart_src_transmission_window_buffer_count (source) for transmission window buffers, and smart_src_retention_buffer_count (source) for retention buffers.

  The smart_src_max_message_length option affects both the transport session underlying the source and also the source itself. The transport session uses the value from the first source created on the session when it allocates the transmission window; subsequent sources created on the same session do not affect the transmission window. However, the sizes of the user buffers and retention buffers are specific to each Smart Source on a session.

  The default value was specifically chosen so that for a Smart Source with no optional headers (no message properties, no spectrum channel, etc.), the total memory consumed per buffer, including internal headers, is 512 bytes.

  Note that unlike most UM configuration options, the default value for smart_src_max_message_length is likely to change with new versions of UM. This is because the addition of new capabilities to the Smart Sources feature often requires the addition of internal headers to the message buffer, thus reducing the available user space while staying within the 512-byte total buffer size default target. To assist application designers who want to use the default, the constant SSRC_DEFAULT_MAX_MSG_LEN is defined in lbm.h.

  Also note that the application designer can avoid that uncertainty by simply defining smart_src_max_message_length to be the maximum size of his messages, and allowing the final allocation size of the message buffer to vary by UM version. This is the recommended approach.

  See Smart Sources for more information about Smart Sources.

  Scope: | source
  Type: | int
  Units: | bytes
  Default value: | SSRC_DEFAULT_MAX_MSG_LEN (368)
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in UM 6.10

## smart_src_message_property_int_count (source) <-

  The maximum number of 32-bit integer message properties that can be set on messages for a particular Smart Source.

  See Smart Sources and Message Properties for restrictions.

  See Smart Sources for more information about Smart Sources.

  Scope: | source
  Type: | int
  Units: | 32-bit integer properties
  Default value: | 0
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in UM 6.11

## smart_src_retention_buffer_count (source) <-

  The number of Smart Source buffers that are allocated for Late Join and other topic level retransmission features such as Off Transport Recovery.

  Once created, the application cannot change the number of buffers. Also, the number of buffers should be a power of 2. If a value is supplied that is not a power of 2, the value is increased to the next larger power of two and a warning message is logged.

  The buffer size is determined by smart_src_max_message_length (source), see that option description for more details.

  The normal Late Join options "retransmit_retention_*" do not apply to Smart Sources.

  See Smart Sources for more information about Smart Sources.

  Scope: | source
  Type: | int
  Units: | buffers
  Default value: | 1024
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in UM 6.10

## smart_src_user_buffer_count (source) <-

  The number of Smart Source buffers that are allocated when the source is created.

  Once created, the application cannot change the number of buffers. Also, the number of buffers should be a power of 2. If a value is supplied that is not a power of 2, the value is increased to the next larger power of two and a warning message is logged.

  The buffer is sized by the smart_src_max_message_length (source) option.

  See Smart Sources for more information about Smart Sources.

  Scope: | source
  Type: | int
  Units: | buffers
  Default value: | 32
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in UM 6.10

## transport_lbtrm_smart_src_transmission_window_buffer_count (source) <-

  The number of Smart Source buffers allocated for transport-level retransmissions.

  Once created, the application cannot change the number of buffers. Also, the number of buffers should be a power of 2. If a value is supplied that is not a power of 2, the value is increased to the next larger power of two and a warning message is logged.

  This option affects the transport session underlying the source rather than the source itself. The transport session uses the value from the first source created on the session and ignores subsequent sources' configuration.

  The option smart_src_max_message_length (source) is used to size the buffers (see that option description for more details). This means that the first Smart Source created on the session defines the maximum possible size of user messages for all Smart Sources on the transport session. It is not legal to create a subsequent Smart Source on the same transport session with a larger max message size, although smaller values are permissible.

  The normal LBT-RM transmission window options "transport_lbtrm_transmission_window_*" do not apply to Smart Sources.

  See Smart Sources for more information about Smart Sources.

  Scope: | source
  Type: | int
  Units: | buffers
  Default value: | 16384 (16K)
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in UM 6.10

## transport_lbtru_smart_src_transmission_window_buffer_count (source) <-

  The number of Smart Source buffers allocated for transport-level retransmissions.

  Once created, the application cannot change the number of buffers. Also, the number of buffers should be a power of 2. If a value is supplied that is not a power of 2, the value is increased to the next larger power of two and a warning message is logged.

  This option affects the transport session underlying the source rather than the source itself. The transport session uses the value from the first source created on the session and ignores subsequent sources' configuration.

  The option smart_src_max_message_length (source) is used to size the buffers (see that option description for more details). This means that the first Smart Source created on the session defines the maximum possible size of user messages for all Smart Sources on the transport session. It is not legal to create a subsequent Smart Source on the same transport session with a larger max message size, although smaller values are permissible.

  The normal LBT-RU transmission window options "transport_lbtru_transmission_window_*" do not apply to Smart Sources.

Note
  If transport_source_side_filtering_behavior (source) is enabled, each connecting receiver will be assigned its own transmission window buffer. As the number of connecting receivers increases, the total memory consumption of the source can become very large.

  See Smart Sources for more information about Smart Sources.

  Scope: | source
  Type: | int
  Units: | buffers
  Default value: | 16384 (16K)
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in UM 6.11