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

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 2646 of file os-c-api.h.

os_evflags_destroy

#define os_evflags_destroy   os_evflags_destruct

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

Typedef Documentation

os_evflags_attr_t

typedef struct os_evflags_attr_s os_evflags_attr_t

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

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

)

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

{
  assert (evflags != nullptr);
  return (reinterpret_cast<event_flags&> (*evflags)).waiting ();
}

os_evflags_attr_init()

void os_evflags_attr_init

(

os_evflags_attr_t *

attr

)

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

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

os_evflags_clear()

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

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

{
  assert (evflags != nullptr);
  return (os_result_t)(reinterpret_cast<event_flags&> (*evflags))
      .clear (mask, oflags);
}

os_evflags_construct()

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

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

{
  assert (evflags != nullptr);
  if (attr == nullptr)
    {
      attr = (const os_evflags_attr_t*)&event_flags::initializer;
    }
  new (evflags) event_flags (name, (const event_flags::attributes&)*attr);
}

References os::rtos::event_flags::initializer.

os_evflags_delete()

void os_evflags_delete

(

os_evflags_t *

evflags

)

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

{
  assert (evflags != nullptr);
  delete reinterpret_cast<event_flags*> (evflags);
}

os_evflags_destruct()

void os_evflags_destruct

(

os_evflags_t *

evflags

)

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

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

os_evflags_get()

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

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

{
  assert (evflags != nullptr);
  return (os_flags_mask_t)(reinterpret_cast<event_flags&> (*evflags))
      .get (mask, mode);
}

os_evflags_get_name()

const char * os_evflags_get_name

(

os_evflags_t *

evflags

)

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

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

os_evflags_new()

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

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

{
  if (attr == nullptr)
    {
      attr = (const os_evflags_attr_t*)&event_flags::initializer;
    }
  return reinterpret_cast<os_evflags_t*> (
      new event_flags (name, (const event_flags::attributes&)*attr));
}

References os::rtos::event_flags::initializer.

os_evflags_raise()

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

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

{
  assert (evflags != nullptr);
  return (os_result_t)(reinterpret_cast<event_flags&> (*evflags))
      .raise (mask, oflags);
}

References raise().

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
	)

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

{
  assert (evflags != nullptr);
  return (os_result_t)(reinterpret_cast<event_flags&> (*evflags))
      .timed_wait (mask, timeout, oflags, mode);
}

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
	)

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

{
  assert (evflags != nullptr);
  return (os_result_t)(reinterpret_cast<event_flags&> (*evflags))
      .try_wait (mask, oflags, mode);
}

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
	)

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

{
  assert (evflags != nullptr);
  return (os_result_t)(reinterpret_cast<event_flags&> (*evflags))
      .wait (mask, oflags, mode);
}

References wait().