diff options
author | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2017-11-16 10:29:43 +0100 |
---|---|---|
committer | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2017-11-16 10:44:55 +0100 |
commit | d9ecff105d5438158a994f106ca7f55b5c4e60e3 (patch) | |
tree | a55eb0af174e9b407a8144767b967aafef075d05 /c-user/semaphore_manager.rst | |
parent | bsp-howto/console: Move misplaced var. in example (diff) | |
download | rtems-docs-d9ecff105d5438158a994f106ca7f55b5c4e60e3.tar.bz2 |
c-users: Clarify semaphore obtain/flush
Diffstat (limited to '')
-rw-r--r-- | c-user/semaphore_manager.rst | 44 |
1 files changed, 43 insertions, 1 deletions
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 |