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...

Typedefs
typedef struct os_condvar_attr_s	os_condvar_attr_t
	Condition variable attributes.

typedef struct os_condvar_s	os_condvar_t
	Condition variable object storage.

Condition Variable Attributes Functions
void	os_condvar_attr_init (os_condvar_attr_t *attr)
	Initialise the condition variable attributes.

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.

void	os_condvar_destruct (os_condvar_t *condvar)
	Destruct the statically allocated condition variable object instance.

os_condvar_t *	os_condvar_new (const char name, const os_condvar_attr_t attr)
	Allocate a condition variable object instance and construct it.

void	os_condvar_delete (os_condvar_t *condvar)
	Destruct the condition variable object instance and deallocate it.

Condition Variable Functions
const char *	os_condvar_get_name (os_condvar_t *condvar)
	Get the condition variable name.

os_result_t	os_condvar_signal (os_condvar_t *condvar)
	Notify one thread waiting for a condition variable.

os_result_t	os_condvar_broadcast (os_condvar_t *condvar)
	Notify all threads waiting for a condition variable.

os_result_t	os_condvar_wait (os_condvar_t condvar, os_mutex_t mutex)
	Wait for a condition variable to be notified.

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.

Compatibility Macros
#define	os_condvar_create os_condvar_construct

#define	os_condvar_destroy os_condvar_destruct

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_t cv1;
      os_condvar_construct (&cv1, "cv1", NULL);
 
      os_condvar_signal (&cv1);
 
      os_condvar_broadcast (&cv1);
 
      // TODO: test os_condvar_wait()
 
      name = os_condvar_get_name (&cv1);
 
      os_condvar_destruct (&cv1);
    }
}

Macro Definition Documentation

◆ os_condvar_create

#define os_condvar_create os_condvar_construct

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

◆ os_condvar_destroy

#define os_condvar_destroy os_condvar_destruct

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

Typedef Documentation

◆ os_condvar_attr_t

typedef struct os_condvar_attr_s 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] attr Pointer 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 1782 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] condvar Pointer to condition variable object instance.

Return values

os_ok	All waiting threads signalled.
EPERM	Cannot 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 1901 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]	condvar	Pointer to condition variable object instance storage.
[in]	name	Pointer to name (may be NULL).
[in]	attr	Pointer 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 1797 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] condvar Pointer 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 1862 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] condvar Pointer 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 1818 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] condvar Pointer 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 1875 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]	name	Pointer to name (may be NULL).
[in]	attr	Pointer 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 1838 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] condvar Pointer to condition variable object instance.

Return values

os_ok	The thread was signalled.
EPERM	Cannot 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 1888 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]	condvar	Pointer to condition variable object instance.
[in]	mutex	Pointer to the associated mutex.
[in]	timeout	Timeout to wait.

Return values

os_ok	The condition change was signalled.
EPERM	Cannot 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.
ENOTRECOVERABLE	The state protected by the mutex is not recoverable.
EOWNERDEAD	The 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.
ETIMEDOUT	The 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 1928 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]	condvar	Pointer to condition variable object instance.
[in]	mutex	Pointer to the associated mutex.

Return values

os_ok	The condition change was signalled.
EPERM	Cannot 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.
ENOTRECOVERABLE	The state protected by the mutex is not recoverable.
EOWNERDEAD	The 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 1914 of file os-c-wrapper.cpp.

Classes

Typedefs

Condition Variable Attributes Functions

Condition Variable Creation Functions

Condition Variable Functions

Compatibility Macros

Detailed Description

Macro Definition Documentation

◆ os_condvar_create

◆ os_condvar_destroy

Typedef Documentation

◆ os_condvar_attr_t

◆ os_condvar_t

Function Documentation

◆ os_condvar_attr_init()

◆ os_condvar_broadcast()

◆ os_condvar_construct()

◆ os_condvar_delete()

◆ os_condvar_destruct()

◆ os_condvar_get_name()

◆ os_condvar_new()

◆ os_condvar_signal()

◆ os_condvar_timed_wait()

◆ os_condvar_wait()