28.2. Background#
The regulator provides facilities to accept bursty input and buffer it as needed before delivering it at a pre-defined periodic rate. The input is referred to as the Source, with the output referred to as the Destination. Messages are accepted from the Source and delivered to the Destination by a user-provided Delivery function.
The Regulator implementation uses the RTEMS Classic API Partition Manager to manage the buffer pool and the RTEMS Classic API Message Queue Manager to send the buffer to the Delivery thread. The Delivery thread invokes a user-provided delivery function to get the message to the Destination.
28.2.1. Regulator Buffering#
The regulator is designed to sit logically between two entities – a
source and a destination, where it limits the traffic sent to the
destination to prevent it from being flooded with messages from the
source. This can be used to accommodate bursts of input from a source
and meter it out to a destination. The maximum number of messages
which can be buffered in the regulator is specified by the
maximum_messages field in the rtems_regulator_attributes
structure passed as an argument to rtems_regulator_create().
The regulator library accepts an input stream of messages from a source and delivers them to a destination. The regulator assumes that the input stream from the source contains sporadic bursts of data which can exceed the acceptable rate of the destination. By limiting the message rate, the regulator prevents an overflow of messages.
The regulator can be configured for the input buffering required to manage the maximum burst and for the metering rate for the delivery. The delivery rate is in messages per second. If the sender produces data too fast, the regulator will buffer the configured number of messages.
A configuration capability is provided to allow for adaptation to different message streams. The regulator can also support running multiple instances, which could be used on independent message streams.
It is assumed that the application has a design limit on the number of messages which may be buffered. All messages accepted by the regulator, assuming no overflow on input, will eventually be output by the Delivery thread.
28.2.2. Message Delivery Rate#
The Source sends buffers to the Regulator instance. The Regulator
then sends the buffer via a message queue which delivers them to the
Delivery thread. The Delivery thread executes periodically at a rate
specified by the delivery_thread_period field in the
rtems_regulator_attributes structure passed as an argument
to rtems_regulator_create().
During each period, the Delivery thread attempts to receive
up to maximum_to_dequeue_per_period number of buffers and
invoke the Delivery function to deliver each of them to the
Destination. The maximum_to_dequeue_per_period field in the
rtems_regulator_attributes structure passed as an argument
to rtems_regulator_create().
For example, consider a Source that may produce a burst of up to seven messages every five seconds. But the Destination cannot handle a burst of seven and either drops messages or gives an error. This can be accommodated by a Regulator instance configured as follows:
maximum_messages- 7delivery_thread_period- one secondmaximum_to_dequeue_per_period- 3
In this scenario, the application will use the Delivery thread rtems_regulator_send() to enqueue the seven messages when they arrive. The Delivery thread will deliver three messages per second. The following illustrates this sequence:
Time 0: Source sends seven messages
Time 1: Delivery of messages 1 to 3
Time 3: Delivery of messages 4 to 6
Time 3: Delivery of message 7
Time 4: No messages to deliver
This configuration of the regulator ensures that the Destination does not overflow.