Event flags

C API event flags definitions. More...

Classes
struct	os_evflags_attr_s
	Event flags attributes. More...
struct	os_evflags_s
	Event flags object storage. More...

Typedefs
typedef struct os_evflags_attr_s	os_evflags_attr_t
	Event flags attributes.
typedef struct os_evflags_s	os_evflags_t
	Event flags object storage.

Event Flags Attributes Functions
void	os_evflags_attr_init (os_evflags_attr_t *attr)
	Initialise the event flags attributes.

Event Flags Creation Functions
void	os_evflags_construct (os_evflags_t *evflags, const char *name, const os_evflags_attr_t *attr)
	Construct a statically allocated event flags object instance.
void	os_evflags_destruct (os_evflags_t *evflags)
	Destruct the statically allocated event flags object instance.
os_evflags_t *	os_evflags_new (const char *name, const os_evflags_attr_t *attr)
	Allocate an event flags object instance and construct it.
void	os_evflags_delete (os_evflags_t *evflags)
	Destruct the event flags object instance and deallocate it.

Event Flags Functions
const char *	os_evflags_get_name (os_evflags_t *evflags)
	Get the event flags name.
os_result_t	os_evflags_wait (os_evflags_t *evflags, os_flags_mask_t mask, os_flags_mask_t *oflags, os_flags_mode_t mode)
	Wait for event flags.
os_result_t	os_evflags_try_wait (os_evflags_t *evflags, os_flags_mask_t mask, os_flags_mask_t *oflags, os_flags_mode_t mode)
	Try to wait for event flags.
os_result_t	os_evflags_timed_wait (os_evflags_t *evflags, os_flags_mask_t mask, os_clock_duration_t timeout, os_flags_mask_t *oflags, os_flags_mode_t mode)
	Timed wait for event flags.
os_result_t	os_evflags_raise (os_evflags_t *evflags, os_flags_mask_t mask, os_flags_mask_t *oflags)
	Raise event flags.
os_result_t	os_evflags_clear (os_evflags_t *evflags, os_flags_mask_t mask, os_flags_mask_t *oflags)
	Clear event flags.
os_flags_mask_t	os_evflags_get (os_evflags_t *evflags, os_flags_mask_t mask, os_flags_mode_t mode)
	Get (and possibly clear) event flags.
bool	os_evflags_are_waiting (os_evflags_t *evflags)
	Check if there are threads waiting.

Compatibility Macros
#define	os_evflags_create   os_evflags_construct
#define	os_evflags_destroy   os_evflags_destruct

Detailed Description

C API event flags definitions.

For the complete definition, see

RTOS C++ API

Examples

int
os_main (int argc, char* argv[])
{
    {
      os_evflags_t ev1;
      os_evflags_construct (&ev1, "ev1", NULL);
 
      // Clear all flags.
      os_evflags_clear (&ev1, 0x0, NULL);
 
      os_evflags_raise (&ev1, 0x1, NULL);
      os_evflags_wait (&ev1, 0x1, NULL,
                       os_flags_mode_all | os_flags_mode_clear);
 
      os_evflags_raise (&ev1, 0x1, NULL);
      os_evflags_try_wait (&ev1, 0x1, NULL,
                           os_flags_mode_all | os_flags_mode_clear);
 
      os_evflags_raise (&ev1, 0x1, NULL);
      os_evflags_timed_wait (&ev1, 0x1, 1, NULL,
                             os_flags_mode_all | os_flags_mode_clear);
 
      os_evflags_get (&ev1, 0x1, os_flags_mode_clear);
 
      name = os_evflags_get_name (&ev1);
 
      os_evflags_destruct (&ev1);
    }
 
    {
      // Initialise custom event flags with a specific clock.
      os_evflags_attr_t aev2;
      os_evflags_attr_init (&aev2);
 
      aev2.clock = os_clock_get_rtclock ();
 
      os_evflags_t ev2;
      os_evflags_construct (&ev2, "ev2", &aev2);
 
      os_evflags_destruct (&ev2);
    }
}

Macro Definition Documentation

os_evflags_create

#define os_evflags_create   os_evflags_construct

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

os_evflags_destroy

#define os_evflags_destroy   os_evflags_destruct

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

Typedef Documentation

os_evflags_attr_t

typedef struct os_evflags_attr_s os_evflags_attr_t

Event flags attributes.

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

See also

os::rtos::event_flags::attributes

os_evflags_t

typedef struct os_evflags_s os_evflags_t

Event flags object storage.

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

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

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

See also

os::rtos::event_flags

Function Documentation

os_evflags_are_waiting()

bool os_evflags_are_waiting

(

os_evflags_t *

evflags

)

Check if there are threads waiting.

Parameters

[in]

evflags

Pointer to event flags object instance.

Return values

true	There are threads waiting.
false	There are no threads waiting.

Note

Can be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::event_flags::raise()

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

os_evflags_attr_init()

void os_evflags_attr_init

(

os_evflags_attr_t *

attr

)

Initialise the event flags attributes.

Parameters

[in]

attr

Pointer to event flags attributes object instance.

Returns

Nothing.

Warning

Cannot be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::event_flags::attributes

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

os_evflags_clear()

os_result_t os_evflags_clear	(	os_evflags_t *	evflags,
		os_flags_mask_t	mask,
		os_flags_mask_t *	oflags
	)

Clear event flags.

Parameters

[in]	evflags	Pointer to event flags object instance.
[in]	mask	The OR-ed flags to clear. Zero means 'all'.
[out]	oflags	Optional pointer where to store the previous value of the flags; may be NULL.

Return values

os_ok	The flags were cleared.
EINVAL	The mask is zero.

Note

Can be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::event_flags::clear()

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

os_evflags_construct()

void os_evflags_construct	(	os_evflags_t *	evflags,
		const char *	name,
		const os_evflags_attr_t *	attr
	)

Construct a statically allocated event flags object instance.

Parameters

[in]	evflags	Pointer to event flags object instance storage.
[in]	name	Pointer to name (may be NULL).
[in]	attr	Pointer to attributes (may be NULL).

Returns

Nothing.

Note

Must be paired with os_evflags_destruct().

Warning

Cannot be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::event_flags

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

os_evflags_delete()

void os_evflags_delete

(

os_evflags_t *

evflags

)

Destruct the event flags object instance and deallocate it.

Parameters

[in]

evflags

Pointer to dynamically allocated event flags object instance.

Returns

Nothing.

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

Note

Equivalent of C++ delete ptr_evflags.

Must be paired with os_evflags_new().

Warning

Cannot be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::event_flags

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

os_evflags_destruct()

void os_evflags_destruct

(

os_evflags_t *

evflags

)

Destruct the statically allocated event flags object instance.

Parameters

[in]

evflags

Pointer to event flags object instance.

Returns

Nothing.

Note

Must be paired with os_evflags_construct().

Warning

Cannot be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::event_flags

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

os_evflags_get()

os_flags_mask_t os_evflags_get	(	os_evflags_t *	evflags,
		os_flags_mask_t	mask,
		os_flags_mode_t	mode
	)

Get (and possibly clear) event flags.

Parameters

[in]	evflags	Pointer to event flags object instance.
[in]	mask	The OR-ed flags to get/clear; may be zero.
[in]	mode	Mode bits to select if the flags should be cleared (the other bits are ignored).

Returns

The selected bits from the flags mask.

Note

Can be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::event_flags::get()

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

os_evflags_get_name()

const char * os_evflags_get_name

(

os_evflags_t *

evflags

)

Get the event flags name.

Parameters

[in]

evflags

Pointer to event flags object instance.

Returns

Null terminated string.

Note

Can be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::event_flags::name()

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

os_evflags_new()

os_evflags_t * os_evflags_new	(	const char *	name,
		const os_evflags_attr_t *	attr
	)

Allocate an event flags object instance and construct it.

Parameters

[in]	name	Pointer to name (may be NULL).
[in]	attr	Pointer to attributes (may be NULL).

Returns

Pointer to new event flags object instance.

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

Note

Equivalent of C++ new event_flags(...).

Must be paired with os_evflags_delete().

Warning

Cannot be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::event_flags

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

os_evflags_raise()

os_result_t os_evflags_raise	(	os_evflags_t *	evflags,
		os_flags_mask_t	mask,
		os_flags_mask_t *	oflags
	)

Raise event flags.

Parameters

[in]	evflags	Pointer to event flags object instance.
[in]	mask	The OR-ed flags to raise.
[out]	oflags	Optional pointer where to store the new value of the flags; may be NULL.

Return values

os_ok	The flags were raised.
EINVAL	The mask is zero.
ENOTRECOVERABLE	Raise failed.

Note

Can be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::event_flags::raise()

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

os_evflags_timed_wait()

os_result_t os_evflags_timed_wait	(	os_evflags_t *	evflags,
		os_flags_mask_t	mask,
		os_clock_duration_t	timeout,
		os_flags_mask_t *	oflags,
		os_flags_mode_t	mode
	)

Timed wait for event flags.

Parameters

[in]	evflags	Pointer to event flags object instance.
[in]	mask	The expected flags (OR-ed bit-mask); may be zero.
[out]	oflags	Pointer where to store the current flags; may be NULL.
[in]	mode	Mode bits to select if either all or any flags are expected, and if the flags should be cleared.
[in]	timeout	Timeout to wait.

Return values

os_ok	All expected flags are raised.
EPERM	Cannot be invoked from an Interrupt Service Routines.
ETIMEDOUT	The expected condition did not occur during the entire timeout duration.
EINVAL	The mask is outside of the permitted range.
EINTR	The operation was interrupted.
ENOTRECOVERABLE	Wait failed.

Warning

Cannot be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::event_flags::timed_wait()

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

os_evflags_try_wait()

os_result_t os_evflags_try_wait	(	os_evflags_t *	evflags,
		os_flags_mask_t	mask,
		os_flags_mask_t *	oflags,
		os_flags_mode_t	mode
	)

Try to wait for event flags.

Parameters

[in]	evflags	Pointer to event flags object instance.
[in]	mask	The expected flags (OR-ed bit-mask); may be zero.
[out]	oflags	Pointer where to store the current flags; may be NULL.
[in]	mode	Mode bits to select if either all or any flags are expected, and if the flags should be cleared.

Return values

os_ok	All expected flags were raised.
EINVAL	The mask is outside of the permitted range.
EWOULDBLOCK	The expected condition did not occur.
ENOTRECOVERABLE	Wait failed.

Note

Can be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::event_flags::try_wait()

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

os_evflags_wait()

os_result_t os_evflags_wait	(	os_evflags_t *	evflags,
		os_flags_mask_t	mask,
		os_flags_mask_t *	oflags,
		os_flags_mode_t	mode
	)

Wait for event flags.

Parameters

[in]	evflags	Pointer to event flags object instance.
[in]	mask	The expected flags (OR-ed bit-mask); may be zero.
[out]	oflags	Pointer where to store the current flags; may be NULL.
[in]	mode	Mode bits to select if either all or any flags are expected, and if the flags should be cleared.

Return values

os_ok	All expected flags were raised.
EPERM	Cannot be invoked from an Interrupt Service Routines.
EINVAL	The mask is outside of the permitted range.
EINTR	The operation was interrupted.
ENOTRECOVERABLE	Wait failed.

Warning

Cannot be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::event_flags::wait()

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