Data Structures | Defines | Typedefs | Functions

core/include/semaphore.h File Reference

Semaphores. More...

Data Structures

struct  os_sema_s
 Semaphore structure. More...

Defines

#define os_sema_init(sem, init_value)   DOC_HIDDEN
 Initialization of the semaphore.
#define os_sema_post(sem)   os_sema_post_common( sem, 0 )
 Macro releases the semaphore outside ISR.
#define os_sema_post_intr(sem)   os_sema_post_common( sem , 1 )
 Macro releases the semaphore in ISR.
#define os_sema_wait(sem)   os_sema_wait_timeouted( sem, 0 )
 Waits on the semaphore.
#define OS_WAIT_INFINITE   0
 symbol for infinite wait on semaphore

Typedefs

typedef struct os_sema_s os_sema_t
 Semaphore.

Functions

os_result_t os_sema_post_common (os_sema_t *sem, unsigned char in_interrupts)
 Releases the semaphore.
os_result_t os_sema_wait_timeouted (os_sema_t *sem, unsigned short timeout)
 Waits on the semaphore with timeout.
os_result_t os_sema_tryget (os_sema_t *sem)
 Try to obtain semaphore.
os_result_t os_sleep (unsigned short timeout)
 Makes running thread sleeping for specified time.

Detailed Description

Semaphores.

Author:
Piotr Romaniuk, (c) ELESOFTROM
Version:
1.1 Nov 8, 2013

A semaphore is one of synchronization object, it provides well-known mechanism for signalling between threads. The semaphore contains an internal counter initialized with a number at creation time. This value affects its further behaviour. Two operations on the semaphore are defined: post and wait.
Wait operation has two options:
1. if counter>0 then it is decremented and thread execution is continued,
2. if counter<=0 then the thread is waiting until [1].
Post operation increments the counter and if it is positive wakes up thread that is waiting on the semaphore.

The DioneOS provides the semaphores consistent with above theoretical model. The post operation has its special version (os_sema_post_intr()) designed for calls from ISR. The blocking wait operation has its unblocking variant (os_sema_tryget()) that checks if the wait would happen and if not it performs operation on the semaphore. Otherwise it return OS_WOULD_WAIT code and does not change the semaphore.
Additionaly, os_sema_wait() is equipped with timeout option, so waiting can be limited in time.

This module contain also a function (os_sleep()) for holding thread execution in specified time.

Note:
Some semaphore functions can throw exceptions (os_bug()) when critical conditions occur.
For example:
1. when calls of post/wait functions are unbalanced, the internal semaphore counter will finally overflow.
2. if preemption were disabled, a call of the blocking function would lock the system.

Define Documentation

#define os_sema_init (   sem,
  init_value 
)    DOC_HIDDEN

Initialization of the semaphore.

This should be done before semaphore is used.

Parameters:
[in]sempointer to semaphore structure
[in]init_valueinitial value of semaphore counter (0-means that semaphore is blocked, n>0 that n threads can go through os_sema_wait().
#define os_sema_post (   sem)    os_sema_post_common( sem, 0 )

Macro releases the semaphore outside ISR.

Note:
Use it only in regular context outside of ISR.
may throw os_bug if semaphore counter overflows
Parameters:
[in]semthe pointer to the semaphore structure
Returns:
it behaves like os_schedule(), so:
OS_STATUS_OK when scheduling is correct
OS_PREEMPT_DIS if preempt is disabled, immediate return without other tests it may be correct, e.g. os_sema_post() during preempt disabled
os_bug(OS_BUG_PREEMPT_LOCK) - when list of ready threads is empty
#define os_sema_post_intr (   sem)    os_sema_post_common( sem , 1 )

Macro releases the semaphore in ISR.

Note:
Use it only in ISR.
may throw os_bug if semaphore counter overflows.
Parameters:
[in]semthe pointer to the semaphore structure
Returns:
always returns OS_STATUS_OK
#define os_sema_wait (   sem)    os_sema_wait_timeouted( sem, 0 )

Waits on the semaphore.

Calling this may cause context switch.

Warning:
Do not call it when preemption is disabled - it will not block or throw os_bug (depending on setting in config.h)
Note:
may throw os_bug if os_ready_threads is empty, or when semaphore counter overflows
Parameters:
[in]semthe pointer to the semaphore structure
Returns:
OS_STATUS_OK when success
OS_PREEMPT_DIS when preemption is disabled and check this issue is disabled in config.h

Function Documentation

os_result_t os_sema_post_common ( os_sema_t *  sem,
unsigned char  in_interrupts 
)

Releases the semaphore.

Note:
do not use it, use os_sema_post() and os_sema_post_intr() instead
may throw os_bug if semaphore counter overflows
Parameters:
[in]semthe pointer to the semaphore structure
[in]in_interruptsflag signals if call is from ISR
Returns:
OS_STATUS_OK if it is called with is_interrupts=1, otherwise it behaves like os_schedule(), so:
OS_STATUS_OK when scheduling is correct
OS_PREEMPT_DIS if preempt is disabled, immediate return without other tests it may be correct, e.g. os_sema_post() during preempt disabled
os_bug(OS_BUG_PREEMPT_LOCK) - when list of ready threads is empty
os_result_t os_sema_tryget ( os_sema_t *  sem)

Try to obtain semaphore.

The function tries to obtain semaphore but never blocks (waits) on it. The result of operation is returned by return code.

Parameters:
[in]sempointer to the semaphore structure
Returns:
OS_STATUS_OK when semaphore has been obtained
OS_WOULD_WAIT if semaphore is busy and trial of waiting on it would block
os_result_t os_sema_wait_timeouted ( os_sema_t *  sem,
unsigned short  timeout 
)

Waits on the semaphore with timeout.

Calling this may cause context switch.

Warning:
Do not call it when preemption is disabled - it will not block or throw os_bug (depending on setting in config.h)
Note:
may throw os_bug if os_ready_threads is empty, or when semaphore counter overflows
Timeout may be shorter than specified in argument list by 1 unit or longer, depending on latencies in the system.
Parameters:
[in]semthe pointer to the semaphore structure
[in]timeoutwaiting timeout in os_tick units (if it is equal 0, it means that there is no timeout - OS_WAIT_INFINITE )
Returns:
OS_STATUS_OK when success
OS_PREEMPT_DIS when preemption is disabled and check this issue is disabled in config.h
OS_TIMEOUT when timeout has expired, note that semaphore could be released between timeout has elapsed and function returned. If it is important, in this case call os_sema_tryget(), but after you cannot obtain semaphore the release may happen so this looks again like uncertainty in return from the function.
os_result_t os_sleep ( unsigned short  timeout)

Makes running thread sleeping for specified time.

The function may be used when some waiting time is required in the thread. The thread is going sleep for specified time and after that is woken up.

Note:
the function uses internally os_sema_wait_timeouted(). Read notes in that function.
Parameters:
[in]timeoutthe time for which the thread will be sleeping (must be positive, i.e. larger than zero).
Returns:
always returns OS_STATUS_OK