[PATCH rtems-docs 2/2] c-user/message/directives.rst: Regen from spec

[Sebastian Huber]

On 11.02.23 17:27, Martin Erik Werner wrote:
> Regenerate message queue directives from the rtems-central spec in
> order
> to include the detailed note about non-atomicity of broadcast.
> 
> This file is selectively added, other changes in generated files are
> omitted.
> 
> Update #4804.
> ---
>   c-user/message/directives.rst | 8 ++++++++
>   1 file changed, 8 insertions(+)
> 
> diff --git a/c-user/message/directives.rst b/c-
> user/message/directives.rst
> index a13e4c7..ac53ec4 100644
> --- a/c-user/message/directives.rst
> +++ b/c-user/message/directives.rst
> @@ -758,6 +758,14 @@ The execution time of this directive is directly
> related to the number of tasks
>   waiting on the message queue, although it is more efficient than the
> equivalent
>   number of invocations of :ref:`InterfaceRtemsMessageQueueSend`.
>   
> +:ref:`InterfaceRtemsMessageQueueBroadcast` unblocks :term:`receivers
> +<receiver>` in a non-atomic way. Meaning, it will not only
> :term:`unblock`
> +those :term:`receivers <receiver>` it finds waiting at the queue when
> +:ref:`InterfaceRtemsMessageQueueBroadcast` is invoked but also any new
> +:term:`receivers <receiver>` which start waiting for messages after
> +:ref:`InterfaceRtemsMessageQueueBroadcast` is invoked and before it
> returns.
> +This may lead to infinite unblocking loops.
> +
>   .. rubric:: CONSTRAINTS:
>   
>   The following constraints apply to this directive:

Thanks for the updated documentation. It let me think about the current 
implementation since the current behaviour is a bit scary.

In uniprocessor configurations, the current behaviour could be fixed by 
disabling thread dispatching for the entire broadcast. This should be 
acceptable. The disabled thread dispatching prevents that new waiting 
threads show up in the queue.

In SMP configurations, this is not sufficient (new waiting threads can 
show up on other processors). We could add a 32-bit generation number to 
the message queue. When a waiting thread is enqueued, it increments and 
gets the generation number. In the broadcast we dequeue only threads 
with a generation number less than the one at broadcast start (modulo 
operation).

-- 
embedded brains GmbH
Herr Sebastian HUBER
Dornierstr. 4
82178 Puchheim
Germany
email: sebastian.huber at embedded-brains.de
phone: +49-89-18 94 741 - 16
fax:   +49-89-18 94 741 - 08

Registergericht: Amtsgericht München
Registernummer: HRB 157899
Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler
Unsere Datenschutzerklärung finden Sie hier:
https://embedded-brains.de/datenschutzerklaerung/