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

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

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

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

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

)

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 1962 of file os-c-wrapper.cpp.

{
  assert (attr != nullptr);
  new (attr) condition_variable::attributes ();
}

os_condvar_broadcast()

os_result_t os_condvar_broadcast

(

os_condvar_t *

condvar

)

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 2082 of file os-c-wrapper.cpp.

{
  assert (condvar != nullptr);
  return (os_result_t)(reinterpret_cast<condition_variable&> (*condvar))
      .broadcast ();
}

os_condvar_construct()

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

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 1977 of file os-c-wrapper.cpp.

{
  assert (condvar != nullptr);
  if (attr == nullptr)
    {
      attr = (const os_condvar_attr_t*)&condition_variable::initializer;
    }
  new (condvar)
      condition_variable (name, (const condition_variable::attributes&)*attr);
}

References os::rtos::condition_variable::initializer.

os_condvar_delete()

void os_condvar_delete

(

os_condvar_t *

condvar

)

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 2042 of file os-c-wrapper.cpp.

{
  assert (condvar != nullptr);
  delete reinterpret_cast<condition_variable*> (condvar);
}

os_condvar_destruct()

void os_condvar_destruct

(

os_condvar_t *

condvar

)

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 1998 of file os-c-wrapper.cpp.

{
  assert (condvar != nullptr);
  (reinterpret_cast<condition_variable&> (*condvar)).~condition_variable ();
}

os_condvar_get_name()

const char * os_condvar_get_name

(

os_condvar_t *

condvar

)

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 2055 of file os-c-wrapper.cpp.

{
  assert (condvar != nullptr);
  return (reinterpret_cast<condition_variable&> (*condvar)).name ();
}

os_condvar_new()

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

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 2018 of file os-c-wrapper.cpp.

{
  if (attr == nullptr)
    {
      attr = (const os_condvar_attr_t*)&condition_variable::initializer;
    }
  return reinterpret_cast<os_condvar_t*> (new condition_variable (
      name, (const condition_variable::attributes&)*attr));
}

References os::rtos::condition_variable::initializer.

os_condvar_signal()

os_result_t os_condvar_signal

(

os_condvar_t *

condvar

)

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 2068 of file os-c-wrapper.cpp.

{
  assert (condvar != nullptr);
  return (os_result_t)(reinterpret_cast<condition_variable&> (*condvar))
      .signal ();
}

os_condvar_timed_wait()

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

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 2110 of file os-c-wrapper.cpp.

{
  assert (condvar != nullptr);
  return (os_result_t)(reinterpret_cast<condition_variable&> (*condvar))
      .timed_wait (reinterpret_cast<rtos::mutex&> (*mutex), timeout);
}

os_condvar_wait()

os_result_t os_condvar_wait	(	os_condvar_t *	condvar,
		os_mutex_t *	mutex
	)

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 2096 of file os-c-wrapper.cpp.

{
  assert (condvar != nullptr);
  return (os_result_t)(reinterpret_cast<condition_variable&> (*condvar))
      .wait (reinterpret_cast<rtos::mutex&> (*mutex));
}

References wait().