[PATCH] c-user: Add self-contained objects chapter

[Sebastian Huber]

On 02/02/17 16:56, Gedare Bloom wrote:
>>>> +.. c:function:: void rtems_binary_semaphore_post(rtems_binary_semaphore
>>>> >>>*semaphore)
>>>> >>>+
>>>> >>>+Posts the binary semaphore.  In case at least one thread is waiting on
>>>> >>>the
>>>> >>>+binary semaphore, then the highest priority thread is woken up,
>>>> >>>otherwise the
>>>> >>>+current count is set to one.
>>>> >>>+
>>>> >>>+This function may be called from interrupt context.  In case it is
>>>> >>>called from
>>>> >>>+thread context, then interrupts must be enabled.
>>>> >>>
>>> >>What is the difference between mutex and binary semaphore?
>> >
>> >
>> >Yes, there is a big difference. A binary semaphore is a counting semaphore
>> >those values are restricted to 0 and 1. It has no owner.
>> >
> Whichever thread passes 'wait()' is (implicitly) owning the binary
> semaphore. Semantically there is very little difference to me.
> Certainly based on the description here I don't know what the
> difference is and why if I'm a user I should pick rtems_mutex or
> rtems_binary_semaphore.

Ok, the RTEMS term for this "binary semaphore" here is simple binary 
semaphore. We could name it rtems_simple_binary_semaphore(), however, 
this would be a bit long. Normally, if you need something for mutual 
exclusion it is called mutex or lock and not semaphore.

>
> Do the counting/binary semaphores also use priority inheritance?

No, they have no owner. The are not useful for mutual exclusion.

>
> If the binary semaphore is identically equal to a counting semaphore
> initialized to 1, then why even include it in the API?
>

It stays as 1 if you post it again and again. It can be used for 
task/interrupt synchronization. One example is Termios

https://git.rtems.org/rtems/tree/cpukit/libcsupport/src/termios.c#n1774


-- 
Sebastian Huber, embedded brains GmbH

Address : Dornierstr. 4, D-82178 Puchheim, Germany
Phone   : +49 89 189 47 41-16
Fax     : +49 89 189 47 41-09
E-Mail  : sebastian.huber at embedded-brains.de
PGP     : Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.