Throttling

Liberator throttles updates to clients from records and generic objects (Liberator 7.1.24+) by default. Throttling client updates reduces the performance impact of high update rates from adapters by merging updates over a period of time called 'throttle time' (default 1 second).

The default throttling settings are not suitable for all purposes and it is common practice to change them on a subject-by-subject basis. For example, executable pricing streams may require a shorter throttle time, and messaging channels require throttling to be disabled.

This page provides an overview of throttling, how to configure it, and how to disable it. For information on a related performance feature that batches rather than merges client updates, see Bursting.

From version 7.1.24, in addition to throttling updates from records, Liberator now throttles updates from generic objects too. Review your configuration before upgrading to Liberator 7.1.24, and disable throttling for generic objects for which throttling is inappropriate (for example, messaging channels). For more details, see Disabling throttling, below.

Overview

In a fast moving market, data updates can be generated more frequently than the end-user can actually notice them. For example, the user can’t actually see every update for an item that is updating at ten times a second. Additionally, having to feed such high update rates through to client applications can adversely impact system resources, performance, and the network.

When throttling is enabled (the default), Liberator conflates all the updates for a data item during an interval called the throttle time (default 1 second). At the end of this interval, Liberator sends an update to the client.

Throttling of records

At the end of the throttle time for a record, by default Liberator sends the client all updated fields regardless of whether their value has changed since the last update was sent to the client. If no fields were updated in the throttle time, then no update is sent to the client

Example 1. Records (default behaviour)

Three updates are received by a type 1 record /ABC during throttle time. At the end of throttle time, the object’s bid and ask fields have both received updates, but only the bid field has changed in value since the last update was sent to the client. Liberator sends the client an update containing both fields.

ClientLiberator object cache/ABCAdapterSubscribe /ABCRequest /ABCbid=51.160, ask=52.032bid=51.160, ask=52.032bid=51.160, ask=52.032Throttle timebid=51.162, ask=52.032bid=51.155, ask=52.032bid=51.158, ask=52.032bid=51.158, ask=52.032bid=51.158, ask=52.032

By default, throttled record updates to clients include all fields that have been updated in the throttle time, even if the updated fields have not changed in value. To configure throttled record updates to include only the updated fields that have changed in value, see configuration option add-object::only-changed-fields.

Example 2. Records (only-changed-fields TRUE)

A type 1 object, /ABC, has been configured to send only changed fields in client updates:

add-object
    name /ABC
    type record
    only-changed-fields TRUE
end-object

Three updates are received by the type 1 object /ABC during throttle time. At the end of throttle time, the object’s bid and ask fields have both received updates, but only the bid field has changed in value since the last update was sent to the client. Liberator sends the client an update containing only the bid field.

ClientLiberator object cache/ABCAdapterSubscribe /ABCRequest /ABCbid=51.160, ask=52.032bid=51.160, ask=52.032bid=51.160, ask=52.032Throttle timebid=51.162, ask=52.032bid=51.155, ask=52.032bid=51.158, ask=52.032bid=51.158, ask=52.032bid=51.158

Throttling of generic objects

Available from: Liberator 7.1.24

From version 7.1.24, Liberator throttles updates from generic objects by default. To restore throttling behaviour for all generic objects to pre 7.1.24 behaviour, set the object-disable-generic-throttling item to true.

At the end of the throttle interval for a generic object, Liberator sends the client an update containing only the updated fields that have changed in value. If no fields have changed in value, then no update is sent to the client.

Example 3. Generic objects

Three updates are received by a generic object /ABC during throttle time. At the end of throttle time, the object’s bid and ask fields have both received updates, but only the bid field has changed in value since the last update was sent to the client. Liberator sends the client an update containing only the bid field.

ClientLiberator object cache/ABCAdapterSubscribe /ABCRequest /ABCbid=51.160, ask=52.032bid=51.160, ask=52.032bid=51.160, ask=52.032Throttle timebid=51.162, ask=52.032bid=51.155, ask=52.032bid=51.158, ask=52.032bid=51.158, ask=52.032bid=51.158

There are some differences between the throttling of generic objects and the throttling of records:

Throttle times

Records: all throttle times in object-throttle-times and add-object::throttle-times can be used.

Generic objects: only the first throttle time in object-throttle-times and add-object::throttle-times is used.

Fields in updates sent to clients

Records: regardless of whether throttling is enabled or disabled, you can configure whether updates sent to clients contain all updated fields, or only updated fields that have changed in value. See add-object::only-changed-fields.

Generic objects: when throttling is disabled, updates sent to clients contain all updated fields. When throttling is enabled, updates sent to clients contain only updated fields that have changed in value. This behaviour is non-configurable.

Configuring throttling

Client applications can change the level of throttling for specified items, groups of items, or all items globally.

Global-level configuration

Global throttling configuration applies to all records and generic objects, unless overridden at object level.

  • object-throttle-off: when set to TRUE, disables throttling for all objects. This item cannot be overridden at object level.

  • object-throttle-times: an array (space-separated values) of throttle times. When an array is provided, clients begin with the value indicated by object-throttle-default-level, and can switch to any of the other values in the array. For most scenarios, one value is sufficient.

    For throttled generic objects, only the first value in the array is used.

  • object-throttle-default-level: an index (0 based) to the array specified in object-throttle-times. Defaults to 0 (the first value in the array).

    For throttled generic objects, only the first value (0) in the object-throttle-times array is used.

  • object-disable-generic-throttling: when set to TRUE, disables throttling for all generic objects.

Object-level configuration

You can use the add-object configuration item to configure throttling at the object level for records and generic objects. You can also configure throttling at the directory level (objects of type directory), and records and generic objects under that directory will inherit the configuration.

add-object:

  • name option: the name of the object.

  • type option: the type of the object. Set to record or generic for a specific object (for example, /FX/EURUSD) or directory for a namespace containing objects of type record and generic (for example, /FX).

  • throttle-times option: overrides object-throttle-times. Set to 0 to disable throttling for this subject.

  • only-changed-fields option: [type 'record' only] determines which fields are sent to clients in updates. Set to FALSE (default) to send clients all updated fields, and set to TRUE to send clients only updated fields that have changed in value.

    This option is ignored by generic objects. When throttling is disabled, generic objects send clients all updated fields. From Liberator 7.1.24, when throttling is enabled, generic objects send clients only updated fields that have changed in value.

  • disable-generic-throttling option: disables throttling of generic objects in a directory.

Example 4. Subject-level configuration

The configuration below sets the throttle time to 0.25s for objects under the /FX namespace. Subscriptions to type 1 records under the /FX namespace will receive a maximum of 4 updates a second.

add-object
    name /FX
    type directory
    throttle-times 0.25
end-object

Disabling throttling

By default, throttling is enabled for records (and generic objects, since Liberator 7.1.24) with a throttle time of 1 second.

Throttling updates is not appropriate for all objects. Updates in messaging channels, such as those used by FX Integration API trade-models, must not be throttled. Throttling message channels may delay message transmission, and, if only changed fields are sent, throttling breaks message specifications that guarantee the presence of specific fields.

Disabling throttling for all namespaces

Before disabling throttling globally, consider whether some objects would benefit from some level of throttling (highly volatile pricing streams, for example).

Choose the most appropriate option below:

Disabling throttling for a specific namespace

Choose the most appropriate option below:

  • To disable throttling of records and generic objects under a specific namespace, use an add-object item with option type set to directory and option throttle-times set to 0.

    Example 5. Disabling throttling of records and generic objects in a namespace

    To disable throttling of records and generic objects under the /PRIVATE namespace, use the configuration below:

    add-object
    name /PRIVATE
    type directory
    throttle-times 0
end-object

  • To disable throttling of generic objects under a specific namespace, use an add-object item with option type set to directory and option disable-generic-throttling set to TRUE.

    Example 6. Disabling throttling of generic objects in a namespace

    To disable throttling of generic objects under the /PRIVATE namespace, use the configuration below:

    add-object
    name /PRIVATE
    type directory
    disable-generic-throttling TRUE
end-object

See also: