# Bursting configuration

These Liberator configuration items define the settings of Liberator’s bursting feature.

The efficiency of the Liberator can be increased by writing user output in defined "bursts", or "batches".

For an explanation of how these configuration items control the amount of bursting, see How bursting works below.

 You can also use Liberator’s throttling feature to reduce the performance impact of high update rates by merging updates together.

## burst-increment

`burst-increment` specifies defines the amount by which the batching interval is increased when more than three messages are received and batched within the batching interval (up to a maximum of burst-max) , and by which the batching interval is decreased when no messages are received within the batching interval (down to a minimum of burst-min). For an explanation of how `burst-increment` works together with burst-min and burst-max, see How bursting works below.

Syntax: `burst-increment <delay-increment-in-secs>`

Type: float

Default value: `0.05` seconds

## burst-max

`burst-max` specifies the maximum time in seconds during which messages are batched together before being sent to the client (the batching interval). For an explanation of how `burst-max` works together with burst-min and burst-increment, see How bursting works below.

Benchmark testing has shown that the default `burst-max` setting of `0.5` together with the default burst-min setting of `0.1` seconds provide the best compromise between performance and display. We recommend that Liberator always has a `burst-max` setting, even if it is small, such as `0.1` seconds.

 A burst-max setting of greater than `0.5` seconds can give a visual effect on the client side that data is being "pulsed" instead of streamed.

In the Caplin Platform Deployment Framework, you use a configuration macro `LIBERATOR${THIS_LEG}_BURST_MAX` to specify Liberator’s `burst-max` value. Set the macro in the file <Framework-root>/global_config/environment.conf. See Deployment Framework Configuration macros and items.  Don’t batch trade messages. The no-batching option of add-object turns off batching of messages for that object, thus overriding the `burst-min`, `burst-increment` and `burst-max` settings. Set `no-batching` to `TRUE` for objects that define the subjects of trade messages, since trade messages should be propagated to clients with minimum possible latency and so must never be batched. Syntax: `burst-max <max-time-in-secs>` Type: float Default value: `0.5` seconds ## burst-min `burst-min` specifies defines the minimum time in seconds during which messages are batched together before being sent to the client (the batching interval). For an explanation of how `burst-min` works together with burst-max and burst-increment, see How bursting works below.  In the Caplin Platform Deployment Framework, you use a configuration macro `LIBERATOR${THIS_LEG}_BURST_MIN` to specify Liberator’s `burst-min` value. Set the macro in the file /global_config/environment.conf. See Deployment Framework Configuration macros and items.
 Don’t batch trade messages. The no-batching option of add-object turns off batching of messages for that object, thus overriding the `burst-min`, `burst-increment` and `burst-max` settings. Set `no-batching` to `TRUE` for objects that define the subjects of trade messages, since trade messages should be propagated to clients with minimum possible latency and so must never be batched.

Syntax: `burst-min <min-time-in-secs>`

Type: float

Default value: `0.1` seconds

## How bursting works

First, read the simple explanation of how bursting works; this simple explanation assumes that only the burst-max configuration item controls the bursting behaviour. However, in reality, the burst-min and burst-max configuration items define a "bursting" time window. The time within this window at which successive messages are batched together can vary according to the value of the burst-increment configuration item and the incoming message rate. This is best shown by an example:

Assume:

• `burst-min` = `0.1` seconds

• `burst-max` = `0.5` seconds

• `burst-increment` = `0.05` seconds

Call the time interval in which successive messages are batched together `batching_interval`. At the end of each `batching_interval`, the batched messages (if there are any) are sent to the client.

Initially `batching_interval` is set to `burst-min`, that is, `0.1` seconds. If Liberator receives one, two or three messages from the supplying DataSource application within that `0.1` seconds, it batches them and sends the batch to the client after `0.1` seconds, and then waits another `0.1` seconds for more incoming messages. However, if Liberator receives more than three messages within a `0.1` seconds `batching_interval`, once it’s sent the batch on to the client, it adjusts `batching_interval` by adding on the `burst-increment`, so the `batching_interval` becomes `0.15` seconds.

Assume that in the next `0.15` second interval, just three messages arrive; now Liberator sends the batch of three messages on after `0.15` seconds. But in the next `0.15` second interval, more than three messages arrive, so once Liberator has sent the batch on, it adds `burst-increment` to `batching_interval` again, making a `batching_interval` of `0.2` seconds.

Continuing in the same way, every time more than three messages arrive within `batching_interval` seconds, Liberator increments `batching_interval` by `burst-increment` seconds, up to a maximum value of `burst-max` seconds.

The `batching_interval` can also be reduced - every time no messages arrive within `batching_interval` seconds, Liberator reduces `batching_interval` by `burst-increment` seconds, down to a minimum value of `burst-min` seconds.

See also: