µOS++ IIIe / CMSIS++ / POSIX++ Reference  v6.3.11
“Perfekt ist nicht gut genug”
The third edition of µOS++ and CMSIS++, a proposal for the next generation CMSIS, written in C++.

C API semaphore definitions. More...

Classes

struct  os_semaphore_attr_s
 Semaphore attributes. More...
 
struct  os_semaphore_s
 Semaphore object storage. More...
 

Types

typedef struct os_semaphore_attr_s os_semaphore_attr_t
 Semaphore attributes. More...
 
typedef int16_t os_semaphore_count_t
 Type of variables holding semaphore counts. More...
 
typedef struct os_semaphore_s os_semaphore_t
 Semaphore object storage. More...
 

Compatibility Macros

#define os_semaphore_create   os_semaphore_construct
 
#define os_semaphore_binary_create   os_semaphore_binary_construct
 
#define os_semaphore_counting_create   os_semaphore_counting_construct
 
#define os_semaphore_destroy   os_semaphore_destruct
 

Semaphore Attributes Functions

void os_semaphore_attr_init (os_semaphore_attr_t *attr)
 Initialise the counting semaphore attributes. More...
 
void os_semaphore_attr_binary_init (os_semaphore_attr_t *attr, const os_semaphore_count_t initial_value)
 Initialise the binary semaphore attributes. More...
 
void os_semaphore_attr_counting_init (os_semaphore_attr_t *attr, const os_semaphore_count_t max_value, const os_semaphore_count_t initial_value)
 Initialise the counting semaphore attributes. More...
 
const os_semaphore_attr_tos_semaphore_attr_get_binary (void)
 Get a binary semaphore attributes object instance. More...
 

Semaphore Creation Functions

void os_semaphore_construct (os_semaphore_t *semaphore, const char *name, const os_semaphore_attr_t *attr)
 Construct a statically allocated semaphore object instance. More...
 
void os_semaphore_binary_construct (os_semaphore_t *semaphore, const char *name, const os_semaphore_count_t initial_value)
 Construct a statically allocated binary semaphore object instance. More...
 
void os_semaphore_counting_construct (os_semaphore_t *semaphore, const char *name, const os_semaphore_count_t max_value, const os_semaphore_count_t initial_value)
 Construct a statically allocated counting semaphore object instance. More...
 
void os_semaphore_destruct (os_semaphore_t *semaphore)
 Destruct the statically allocated semaphore object instance. More...
 
os_semaphore_tos_semaphore_new (const char *name, const os_semaphore_attr_t *attr)
 Allocated a semaphore object instance and construct it. More...
 
os_semaphore_tos_semaphore_binary_new (const char *name, const os_semaphore_count_t initial_value)
 Allocate a binary semaphore object instance and construct it. More...
 
os_semaphore_tos_semaphore_counting_new (const char *name, const os_semaphore_count_t max_value, const os_semaphore_count_t initial_value)
 Allocate a counting semaphore object instance and construct it. More...
 
void os_semaphore_delete (os_semaphore_t *semaphore)
 Destruct the semaphore object instance. More...
 

Semaphore Functions

const char * os_semaphore_get_name (os_semaphore_t *semaphore)
 Get the semaphore name. More...
 
os_result_t os_semaphore_post (os_semaphore_t *semaphore)
 Post (unlock) the semaphore. More...
 
os_result_t os_semaphore_wait (os_semaphore_t *semaphore)
 Lock the semaphore, possibly waiting. More...
 
os_result_t os_semaphore_try_wait (os_semaphore_t *semaphore)
 Try to lock the semaphore. More...
 
os_result_t os_semaphore_timed_wait (os_semaphore_t *semaphore, os_clock_duration_t timeout)
 Timed wait to lock the semaphore. More...
 
os_semaphore_count_t os_semaphore_get_value (os_semaphore_t *semaphore)
 Get the semaphore count value. More...
 
os_result_t os_semaphore_reset (os_semaphore_t *semaphore)
 Reset the semaphore. More...
 
os_semaphore_count_t os_semaphore_get_initial_value (os_semaphore_t *semaphore)
 Get the semaphore initial count value. More...
 
os_semaphore_count_t os_semaphore_get_max_value (os_semaphore_t *semaphore)
 Get the semaphore maximum count value. More...
 

Detailed Description

C API semaphore definitions.

For the complete definition, see
RTOS C++ API
Examples
int
os_main (int argc, char* argv[])
{
{
// Binary semaphore, start at 0.
name = os_semaphore_get_name (&sp1);
}
{
// Custom semaphore.
asp2.sm_initial_value = 3;
asp2.sm_max_value = 7;
os_semaphore_construct (&sp2, "sp2", &asp2);
}
{
// Counting semaphore, 7 resources, start at 7.
os_semaphore_counting_construct (&sp3, "sp3", 7, 7);
}
{
// Custom binary semaphore.
os_semaphore_construct (&sp4, "sp4", &asp4);
}
}

Macro Definition Documentation

#define os_semaphore_binary_create   os_semaphore_binary_construct

Definition at line 1912 of file os-c-api.h.

#define os_semaphore_counting_create   os_semaphore_counting_construct

Definition at line 1913 of file os-c-api.h.

#define os_semaphore_create   os_semaphore_construct

Definition at line 1911 of file os-c-api.h.

#define os_semaphore_destroy   os_semaphore_destruct

Definition at line 1914 of file os-c-api.h.

Types

Semaphore attributes.

Initialise this structure with os_semaphore_attr_init() and then set any of the individual members directly.

See also
os::rtos::semaphore::attributes
typedef int16_t os_semaphore_count_t

Type of variables holding semaphore counts.

See also
os::rtos::semaphore::count_t

Definition at line 1076 of file os-c-decls.h.

Semaphore object storage.

This C structure has the same size as the C++ os::rtos::semaphore object and must be initialised with os_semaphore_create().

Later on a pointer to it can be used both in C and C++ to refer to the semaphore object instance.

The members of this structure are hidden and should not be used directly, but only through specific functions.

See also
os::rtos::semaphore

Function Documentation

void os_semaphore_attr_binary_init ( os_semaphore_attr_t attr,
const os_semaphore_count_t  initial_value 
)

Initialise the binary semaphore attributes.

Parameters
[in]attrPointer to semaphore attributes object instance.
[in]initial_valueInitial count value.
Returns
Nothing.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::semaphore::attributes_binary

Definition at line 2123 of file os-c-wrapper.cpp.

void os_semaphore_attr_counting_init ( os_semaphore_attr_t attr,
const os_semaphore_count_t  max_value,
const os_semaphore_count_t  initial_value 
)

Initialise the counting semaphore attributes.

Parameters
[in]attrPointer to semaphore attributes object instance.
[in]max_valueMaximum count value.
[in]initial_valueInitial count value.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::semaphore::attributes_counting

Definition at line 2140 of file os-c-wrapper.cpp.

const os_semaphore_attr_t* os_semaphore_attr_get_binary ( void  )

Get a binary semaphore attributes object instance.

Returns
Pointer to semaphore attributes object instance.
Note
Can be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::semaphore::initializer_binary

Definition at line 2158 of file os-c-wrapper.cpp.

void os_semaphore_attr_init ( os_semaphore_attr_t attr)

Initialise the counting semaphore attributes.

Parameters
[in]attrPointer to semaphore attributes object instance.
Returns
Nothing.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::semaphore::attributes

Definition at line 2107 of file os-c-wrapper.cpp.

void os_semaphore_binary_construct ( os_semaphore_t semaphore,
const char *  name,
const os_semaphore_count_t  initial_value 
)

Construct a statically allocated binary semaphore object instance.

Parameters
[in]semaphorePointer to semaphore object instance storage.
[in]namePointer to name (may be NULL).
[in]initial_valueInitial count value.
Returns
Nothing.
Note
Must be paired with os_semaphore_destruct().
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::semaphore_binary

Definition at line 2197 of file os-c-wrapper.cpp.

os_semaphore_t* os_semaphore_binary_new ( const char *  name,
const os_semaphore_count_t  initial_value 
)

Allocate a binary semaphore object instance and construct it.

Parameters
[in]namePointer to name (may be NULL).
[in]initial_valueInitial count value.
Returns
Pointer to new semaphore object instance.

Dynamically allocate the binary semaphore object instance using the RTOS system allocator and construct it.

Note
Equivalent of C++ new semaphore_binary(...).
Must be paired with os_semaphore_delete().
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::semaphore_binary

Definition at line 2283 of file os-c-wrapper.cpp.

void os_semaphore_construct ( os_semaphore_t semaphore,
const char *  name,
const os_semaphore_attr_t attr 
)

Construct a statically allocated semaphore object instance.

Parameters
[in]semaphorePointer to semaphore object instance storage.
[in]namePointer to name (may be NULL).
[in]attrPointer to attributes (may be NULL).
Returns
Nothing.
Note
Must be paired with os_semaphore_destruct().
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::semaphore

Definition at line 2174 of file os-c-wrapper.cpp.

void os_semaphore_counting_construct ( os_semaphore_t semaphore,
const char *  name,
const os_semaphore_count_t  max_value,
const os_semaphore_count_t  initial_value 
)

Construct a statically allocated counting semaphore object instance.

Parameters
[in]semaphorePointer to semaphore object instance storage.
[in]namePointer to name (may be NULL).
[in]max_valueMaximum count value.
[in]initial_valueInitial count value.
Returns
Nothing.
Note
Must be paired with os_semaphore_destruct().
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::semaphore_counting

Definition at line 2216 of file os-c-wrapper.cpp.

os_semaphore_t* os_semaphore_counting_new ( const char *  name,
const os_semaphore_count_t  max_value,
const os_semaphore_count_t  initial_value 
)

Allocate a counting semaphore object instance and construct it.

Parameters
[in]namePointer to name (may be NULL).
[in]max_valueMaximum count value.
[in]initial_valueInitial count value.
Returns
Pointer to new semaphore object instance.

Dynamically allocate the counting semaphore object instance using the RTOS system allocator and construct it.

Note
Equivalent of C++ new semaphore_counting(...).
Must be paired with os_semaphore_delete().
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::semaphore_counting

Definition at line 2305 of file os-c-wrapper.cpp.

void os_semaphore_delete ( os_semaphore_t semaphore)

Destruct the semaphore object instance.

Parameters
[in]semaphorePointer to semaphore object instance.
Returns
Nothing.

Destruct the semaphore and deallocate the dynamically allocated space using the RTOS system allocator.

Note
Equivalent of C++ delete ptr_semaphore.
Must be paired with os_semaphore_new() or os_semaphore_binary_new() or os_semaphore_counting_new().
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::semaphore

Definition at line 2329 of file os-c-wrapper.cpp.

void os_semaphore_destruct ( os_semaphore_t semaphore)

Destruct the statically allocated semaphore object instance.

Parameters
[in]semaphorePointer to semaphore object instance.
Returns
Nothing.
Note
Must be paired with os_semaphore_construct() or os_semaphore_binary_construct() or os_semaphore_counting_construct().
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::semaphore

Definition at line 2237 of file os-c-wrapper.cpp.

os_semaphore_count_t os_semaphore_get_initial_value ( os_semaphore_t semaphore)

Get the semaphore initial count value.

Parameters
[in]semaphorePointer to semaphore object instance.
Returns
The numeric value set from attributes.
Note
Can be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::semaphore::initial_value()

Definition at line 2450 of file os-c-wrapper.cpp.

os_semaphore_count_t os_semaphore_get_max_value ( os_semaphore_t semaphore)

Get the semaphore maximum count value.

Parameters
[in]semaphorePointer to semaphore object instance.
Returns
The numeric value set from attributes.
Note
Can be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::semaphore::max_value()

Definition at line 2465 of file os-c-wrapper.cpp.

const char* os_semaphore_get_name ( os_semaphore_t semaphore)

Get the semaphore name.

Parameters
[in]semaphorePointer to semaphore object instance.
Returns
Null terminated string.
Note
Can be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::semaphore::name()

Definition at line 2344 of file os-c-wrapper.cpp.

os_semaphore_count_t os_semaphore_get_value ( os_semaphore_t semaphore)

Get the semaphore count value.

Parameters
[in]semaphorePointer to semaphore object instance.
Returns
The semaphore count value.
Note
Can be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::semaphore::value()

Definition at line 2420 of file os-c-wrapper.cpp.

os_semaphore_t* os_semaphore_new ( const char *  name,
const os_semaphore_attr_t attr 
)

Allocated a semaphore object instance and construct it.

Parameters
[in]namePointer to name (may be NULL).
[in]attrPointer to attributes (may be NULL).
Returns
Pointer to new semaphore object instance.

Dynamically allocate the semaphore object instance using the RTOS system allocator and construct it.

Note
Equivalent of C++ new semaphore(...).
Must be paired with os_semaphore_delete().
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::semaphore

Definition at line 2258 of file os-c-wrapper.cpp.

os_result_t os_semaphore_post ( os_semaphore_t semaphore)

Post (unlock) the semaphore.

Parameters
[in]semaphorePointer to semaphore object instance.
Return values
os_okThe semaphore was posted.
EAGAINThe maximum count value was exceeded.
ENOTRECOVERABLEThe semaphore could not be posted (extension to POSIX).
Note
Can be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::semaphore::post()

Definition at line 2359 of file os-c-wrapper.cpp.

os_result_t os_semaphore_reset ( os_semaphore_t semaphore)

Reset the semaphore.

Parameters
[in]semaphorePointer to semaphore object instance.
Return values
os_okThe semaphore was reset.
EPERMCannot be invoked from an Interrupt Service Routines.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::semaphore::reset()

Definition at line 2435 of file os-c-wrapper.cpp.

os_result_t os_semaphore_timed_wait ( os_semaphore_t semaphore,
os_clock_duration_t  timeout 
)

Timed wait to lock the semaphore.

Parameters
[in]semaphorePointer to semaphore object instance.
[in]timeoutTimeout to wait.
Return values
os_okThe calling process successfully performed the semaphore lock operation.
EPERMCannot be invoked from an Interrupt Service Routines.
EINVALInvalid timeout (POSIX limits the timeout to 1000 million ns)
ETIMEDOUTThe semaphore could not be locked before the specified timeout expired.
ENOTRECOVERABLESemaphore wait failed (extension to POSIX).
EDEADLKA deadlock condition was detected.
EINTRThe operation was interrupted.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::semaphore::timed_wait()

Definition at line 2404 of file os-c-wrapper.cpp.

os_result_t os_semaphore_try_wait ( os_semaphore_t semaphore)

Try to lock the semaphore.

Parameters
[in]semaphorePointer to semaphore object instance.
Return values
os_okThe calling process successfully performed the semaphore lock operation.
EPERMCannot be invoked from an Interrupt Service Routines.
EWOULDBLOCKThe semaphore was already locked.
ENOTRECOVERABLESemaphore wait failed (extension to POSIX).
EDEADLKA deadlock condition was detected.
EINTRThe operation was interrupted.
Note
Can be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::semaphore::try_wait()

Definition at line 2389 of file os-c-wrapper.cpp.

os_result_t os_semaphore_wait ( os_semaphore_t semaphore)

Lock the semaphore, possibly waiting.

Parameters
[in]semaphorePointer to semaphore object instance.
Return values
os_okThe calling process successfully performed the semaphore lock operation.
EPERMCannot be invoked from an Interrupt Service Routines.
ENOTRECOVERABLESemaphore wait failed (extension to POSIX).
EDEADLKA deadlock condition was detected.
EINTRThe operation was interrupted.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::semaphore::wait()

Definition at line 2374 of file os-c-wrapper.cpp.