[rtems-docs commit] c-users: Clarify semaphore obtain/flush

[Joel Sherrill]

Classic API Barriers offer a cleaner alternative to using semaphore_flush.
Unlike
POSIX barriers, they have a manual release option. And unlike
semaphore_flush,
you wake up with SUCCESSFUL when it is signaled/released. It seems more
natural to get an OK than an UNSATISFIED when you got the "good result".

Off the top of my head, I don't know if they address the scenario you are
warning about but it would be nice to address the same use case and possibly
same issue.

--joel

On Fri, Nov 17, 2017 at 12:30 AM, Sebastian Huber <sebh at rtems.org> wrote:

> Module:    rtems-docs
> Branch:    master
> Commit:    d9ecff105d5438158a994f106ca7f55b5c4e60e3
> Changeset: http://git.rtems.org/rtems-docs/commit/?id=
> d9ecff105d5438158a994f106ca7f55b5c4e60e3
>
> Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
> Date:      Thu Nov 16 10:29:43 2017 +0100
>
> c-users: Clarify semaphore obtain/flush
>
> ---
>
>  c-user/semaphore_manager.rst | 44 ++++++++++++++++++++++++++++++
> +++++++++++++-
>  1 file changed, 43 insertions(+), 1 deletion(-)
>
> diff --git a/c-user/semaphore_manager.rst b/c-user/semaphore_manager.rst
> index 27080e0..f39f429 100644
> --- a/c-user/semaphore_manager.rst
> +++ b/c-user/semaphore_manager.rst
> @@ -614,6 +614,11 @@ DESCRIPTION:
>      semaphore is available or the ``RTEMS_NO_WAIT`` option component is
> set,
>      then timeout is ignored.
>
> +    In case a semaphore is not available, then ``RTEMS_UNSATISFIED`` will
> be
> +    returned.  This happens immediately in case ``RTEMS_NO_WAIT`` is
> specified,
> +    or as a result of another task invoking the ``rtems_semaphore_flush``
> +    directive in case ``RTEMS_WAIT`` is specified.
> +
>      Deadlock situations are detected for MrsP semaphores and the
>      ``RTEMS_UNSATISFIED`` status code will be returned in SMP
> configurations in
>      this case.
> @@ -734,7 +739,7 @@ DIRECTIVE STATUS CODES:
>       * - ``RTEMS_INVALID_ID``
>         - invalid semaphore id
>       * - ``RTEMS_NOT_DEFINED``
> -       - operation not defined for the protocol ofthe semaphore
> +       - operation not defined for the protocol of the semaphore
>       * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT``
>         - not supported for remote semaphores
>
> @@ -762,6 +767,43 @@ NOTES:
>      It is not allowed to flush a MrsP semaphore and the
> ``RTEMS_NOT_DEFINED``
>      status code will be returned in SMP configurations in this case.
>
> +    Using the ``rtems_semaphore_flush`` directive for condition
> synchronization
> +    in concert with another semaphore may be subject to the lost wake-up
> +    problem.  The following attempt to implement a condition variable is
> +    broken.
> +
> +    .. code-block:: c
> +
> +        #include <rtems.h>
> +        #include <assert.h>
> +
> +        void cnd_wait( rtems_id cnd, rtems_id mtx )
> +        {
> +          rtems_status_code sc;
> +
> +          sc = rtems_semaphore_release( mtx );
> +          assert( sc == RTEMS_SUCCESSFUL );
> +
> +          /*
> +           * Here, a higher priority task may run and satisfy the
> condition. We
> +           * may never wake up from the next semaphore obtain.
> +           */
> +
> +          sc = rtems_semaphore_obtain( cnd, RTEMS_WAIT, RTEMS_NO_TIMEOUT
> );
> +          assert( sc == RTEMS_UNSATISFIED );
> +
> +          sc = rtems_semaphore_obtain( mtx, RTEMS_WAIT, RTEMS_NO_TIMEOUT
> );
> +          assert( sc == RTEMS_SUCCESSFUL );
> +        }
> +
> +        void cnd_broadcast( rtems_id cnd )
> +        {
> +          rtems_status_code sc;
> +
> +          sc = rtems_semaphore_flush( cnd );
> +          assert( sc == RTEMS_SUCCESSFUL );
> +        }
> +
>  .. raw:: latex
>
>     \clearpage
>
> _______________________________________________
> vc mailing list
> vc at rtems.org
> http://lists.rtems.org/mailman/listinfo/vc
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20171117/d933e58c/attachment.html>