Hi,
Thanks for posting this code. My comments are below and I hope they help.
Thanks
Chris
On 8/7/2023 6:55 am, Joel Sherrill wrote:
> Updates #4924.
>
> The Regulator is an application support class which is used to
> deal with the scenario where there is a bursty input source
> which needs to be metered out to a destination sink. The maximum
> size of bursts needs to be known and the delivery method must
> be configured to deliver messages at a rate that allows the
> traffic to not overflow.
> ---
> cpukit/include/rtems/regulator.h | 360 +
> cpukit/include/rtems/regulatorimpl.h | 100 ++
> cpukit/regulator/regulator.c | 487 +++
I prefer we do not add pieces of functionality to cpukit at this level. You
mention this is application support so would `libapp` work? It would allow for
growth, eg logging. We have separate libraries for libdl etc so should this be
separate or placed in libcpu? We also have libmisc and it could live there?
FYI and unrelated I also think moving dtc, ftpd, mghttpd, compression and
telnetd somewhere would be good.
> spec/build/cpukit/librtemscpu.yml |3 +
> spec/build/testsuites/libtests/grp.yml|2 +
> .../build/testsuites/libtests/regulator01.yml | 21 +
> testsuites/libtests/regulator01/regulator01.c | 1156 +
> .../libtests/regulator01/regulator01.doc | 37 +
> .../libtests/regulator01/rtems_config.c | 59 +
> 9 files changed, 2225 insertions(+)
> create mode 100644 cpukit/include/rtems/regulator.h
> create mode 100644 cpukit/include/rtems/regulatorimpl.h
> create mode 100644 cpukit/regulator/regulator.c
> create mode 100644 spec/build/testsuites/libtests/regulator01.yml
> create mode 100644 testsuites/libtests/regulator01/regulator01.c
> create mode 100644 testsuites/libtests/regulator01/regulator01.doc
> create mode 100644 testsuites/libtests/regulator01/rtems_config.c
>
> diff --git a/cpukit/include/rtems/regulator.h
> b/cpukit/include/rtems/regulator.h
> new file mode 100644
> index 00..7344ced2ae
> --- /dev/null
> +++ b/cpukit/include/rtems/regulator.h
> @@ -0,0 +1,360 @@
> +/* SPDX-License-Identifier: BSD-2-Clause */
> +
> +/**
> + * @defgroup RegulatorAPI Regulator API
> + *
> + * @brief Regulator APIs
> + *
> + * The Regulator provides a set of APIs to manage bursty message traffic.
> + */
> +
> +/**
> + * @mainpage
> + *
> + * 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 bursty input from a source
... bursts of input ...
> + * and meter it out to a destination.
> + *
> + * 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 output. The output
> rate
How is the maximum burst defined?
> + * is in messages per second. If the sender produces data too fast, the
> + * regulator will buffer the configured number of messages.
What happens to the input data when the "configured number of messages" limit is
reached?
There is no discussion about error, error responiblity and recovery.
> + * 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.
> + *
> + * The regulator provides a simple interface to the application for avoiding
> + * bursty input from a fast source overflowing a slower output sink.
> + *
> + * It is assumed that the application has a design limit on the number of
> + * messages which may be buffered. All messages will eventually be output.
Does the regulator provide any stats, latched states or alarms to help a user
integrate and prove the data flows are operating as designed? I have
successfully used high or low water marks as a way to help audit this type of
functionality in systems. The marks are set at the system level and can be
manually checked or monitored to make sure no system limits are beached. Slient
drops or overflows can be difficult to resolve.
> + *
> + * A regulator instance is used as follows:
> + *
> + * @code
> + * while (1)
> + * use rtems_regulator_obtain_buffer to obtain a buffer
> + * input operation to fetch data into the buffer
> + * rtems_regulator_send(buffer, size of message)
> + * // rtems_regulator_send() will release the buffer automatically
>
