µOS++ IIIe Reference  v6.3.15
“Perfekt ist nicht gut genug”
The third edition of µOS++, a POSIX inspired open source system, written in C++.
Condition variables

C API condition variable definitions. More...

Classes

struct  os_condvar_attr_s
 Condition variable attributes. More...
 
struct  os_condvar_s
 Condition variable object storage. More...
 

Types

typedef struct os_condvar_attr_s os_condvar_attr_t
 Condition variable attributes. More...
 
typedef struct os_condvar_s os_condvar_t
 Condition variable object storage. More...
 

Compatibility Macros

#define os_condvar_create   os_condvar_construct
 
#define os_condvar_destroy   os_condvar_destruct
 

Condition Variable Attributes Functions

void os_condvar_attr_init (os_condvar_attr_t *attr)
 Initialise the condition variable attributes. More...
 

Condition Variable Creation Functions

void os_condvar_construct (os_condvar_t *condvar, const char *name, const os_condvar_attr_t *attr)
 Construct a statically allocated condition variable object instance. More...
 
void os_condvar_destruct (os_condvar_t *condvar)
 Destruct the statically allocated condition variable object instance. More...
 
os_condvar_tos_condvar_new (const char *name, const os_condvar_attr_t *attr)
 Allocate a condition variable object instance and construct it. More...
 
void os_condvar_delete (os_condvar_t *condvar)
 Destruct the condition variable object instance and deallocate it. More...
 

Condition Variable Functions

const char * os_condvar_get_name (os_condvar_t *condvar)
 Get the condition variable name. More...
 
os_result_t os_condvar_signal (os_condvar_t *condvar)
 Notify one thread waiting for a condition variable. More...
 
os_result_t os_condvar_broadcast (os_condvar_t *condvar)
 Notify all threads waiting for a condition variable. More...
 
os_result_t os_condvar_wait (os_condvar_t *condvar, os_mutex_t *mutex)
 Wait for a condition variable to be notified. More...
 
os_result_t os_condvar_timed_wait (os_condvar_t *condvar, os_mutex_t *mutex, os_clock_duration_t timeout)
 Timed wait for a condition variable to be notified. More...
 

Detailed Description

C API condition variable definitions.

For the complete definition, see
RTOS C++ API
Examples
int
os_main (int argc, char* argv[])
{
{
os_condvar_construct (&cv1, "cv1", NULL);
// TODO: test os_condvar_wait()
name = os_condvar_get_name (&cv1);
}
}

Macro Definition Documentation

◆ os_condvar_create

#define os_condvar_create   os_condvar_construct

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

◆ os_condvar_destroy

#define os_condvar_destroy   os_condvar_destruct

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

Types

◆ os_condvar_attr_t

Condition variable attributes.

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

See also
os::rtos::condition_variable::attributes

◆ os_condvar_t

typedef struct os_condvar_s os_condvar_t

Condition variable object storage.

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

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

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

See also
os::rtos::condition_variable

Function Documentation

◆ os_condvar_attr_init()

void os_condvar_attr_init ( os_condvar_attr_t attr)

Initialise the condition variable attributes.

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

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

◆ os_condvar_broadcast()

os_result_t os_condvar_broadcast ( os_condvar_t condvar)

Notify all threads waiting for a condition variable.

Parameters
[in]condvarPointer to condition variable object instance.
Return values
os_okAll waiting threads signalled.
EPERMCannot be invoked from an Interrupt Service Routines.
Errors
The function shall not fail with an error code of EINTR.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::condition_variable::broadcast()

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

◆ os_condvar_construct()

void os_condvar_construct ( os_condvar_t condvar,
const char *  name,
const os_condvar_attr_t attr 
)

Construct a statically allocated condition variable object instance.

Parameters
[in]condvarPointer to condition variable object instance storage.
[in]namePointer to name (may be NULL).
[in]attrPointer to attributes (may be NULL).
Errors
The constructor shall fail if:
  • EAGAIN - The system lacked the necessary resources (other than memory) to create the condition variable.
  • ENOMEM - Insufficient memory exists to initialise the condition variable.
The constructor shall not fail with an error code of EINTR.
Returns
Nothing.
Note
Must be paired with os_condvar_destruct().
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::condition_variable

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

◆ os_condvar_delete()

void os_condvar_delete ( os_condvar_t condvar)

Destruct the condition variable object instance and deallocate it.

Parameters
[in]condvarPointer to dynamically allocated condition variable object instance.
Returns
Nothing.

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

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

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

◆ os_condvar_destruct()

void os_condvar_destruct ( os_condvar_t condvar)

Destruct the statically allocated condition variable object instance.

Parameters
[in]condvarPointer to condition variable object instance.
Returns
Nothing.
Note
Must be paired with os_condvar_construct().
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::condition_variable

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

◆ os_condvar_get_name()

const char* os_condvar_get_name ( os_condvar_t condvar)

Get the condition variable name.

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

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

◆ os_condvar_new()

os_condvar_t* os_condvar_new ( const char *  name,
const os_condvar_attr_t attr 
)

Allocate a condition variable object instance and construct it.

Parameters
[in]namePointer to name (may be NULL).
[in]attrPointer to attributes (may be NULL).
Errors
The constructor shall fail if:
  • EAGAIN - The system lacked the necessary resources (other than memory) to create the condition variable.
  • ENOMEM - Insufficient memory exists to initialise the condition variable.
The constructor shall not fail with an error code of EINTR.
Returns
Pointer to new condition variable object instance.

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

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

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

◆ os_condvar_signal()

os_result_t os_condvar_signal ( os_condvar_t condvar)

Notify one thread waiting for a condition variable.

Parameters
[in]condvarPointer to condition variable object instance.
Return values
os_okThe thread was signalled.
EPERMCannot be invoked from an Interrupt Service Routines.
Errors
The function shall not fail with an error code of EINTR.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::condition_variable::signal()

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

◆ os_condvar_timed_wait()

os_result_t os_condvar_timed_wait ( os_condvar_t condvar,
os_mutex_t mutex,
os_clock_duration_t  timeout 
)

Timed wait for a condition variable to be notified.

Parameters
[in]condvarPointer to condition variable object instance.
[in]mutexPointer to the associated mutex.
[in]timeoutTimeout to wait.
Return values
os_okThe condition change was signalled.
EPERMCannot be invoked from an Interrupt Service Routines, or the mutex type is mutex::type::errorcheck or the mutex is a robust mutex, and the current thread does not own the mutex.
ENOTRECOVERABLEThe state protected by the mutex is not recoverable.
EOWNERDEADThe mutex is a robust mutex and the process containing the previous owning thread terminated while holding the mutex lock. The mutex lock shall be acquired by the calling thread and it is up to the new owner to make the state consistent.
ETIMEDOUTThe timeout has passed.
Errors
The function shall not fail with an error code of EINTR.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::condition_variable::timed_wait()

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

◆ os_condvar_wait()

os_result_t os_condvar_wait ( os_condvar_t condvar,
os_mutex_t mutex 
)

Wait for a condition variable to be notified.

Parameters
[in]condvarPointer to condition variable object instance.
[in]mutexPointer to the associated mutex.
Return values
os_okThe condition change was signalled.
EPERMCannot be invoked from an Interrupt Service Routines, or the mutex type is mutex::type::errorcheck or the mutex is a robust mutex, and the current thread does not own the mutex.
ENOTRECOVERABLEThe state protected by the mutex is not recoverable.
EOWNERDEADThe mutex is a robust mutex and the process containing the previous owning thread terminated while holding the mutex lock. The mutex lock shall be acquired by the calling thread and it is up to the new owner to make the state consistent.
Errors
The function shall not fail with an error code of EINTR.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::condition_variable::wait()

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