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

[Sebastian Huber]

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