Synchronised event flags. More...

#include <cmsis-plus/rtos/os.h>

Inheritance diagram for os::rtos::event_flags:

Classes
class	attributes
	Event flags attributes. More...

Public Member Functions
Constructors & Destructor
	event_flags (const attributes &attr=initializer)
	Construct an event flags object instance.

	event_flags (const char *name, const attributes &attr=initializer)
	Construct a named event flags object instance.

	~event_flags ()
	Destruct the event flags object instance.

Operators
bool	operator== (const event_flags &rhs) const
	Compare event flags.

Public Member Functions
result_t	wait (flags::mask_t mask, flags::mask_t *oflags, flags::mode_t mode=flags::mode::all\|flags::mode::clear)
	Wait for event flags.

result_t	try_wait (flags::mask_t mask, flags::mask_t *oflags=nullptr, flags::mode_t mode=flags::mode::all\|flags::mode::clear)
	Try to wait for event flags.

result_t	timed_wait (flags::mask_t mask, clock::duration_t timeout, flags::mask_t *oflags=nullptr, flags::mode_t mode=flags::mode::all\|flags::mode::clear)
	Timed wait for event flags.

result_t	raise (flags::mask_t mask, flags::mask_t *oflags=nullptr)
	Raise event flags.

result_t	clear (flags::mask_t mask, flags::mask_t *oflags=nullptr)
	Clear event flags.

flags::mask_t	get (flags::mask_t mask, flags::mode_t mode=flags::mode::clear)
	Get (and possibly clear) event flags.

bool	waiting (void)
	Check if there are threads waiting.

Public Member Functions
const char *	name (void) const
	Get object name.

Static Public Member Functions
Operators
static void *	operator new (std::size_t bytes)
	Allocate space for a new object instance using the RTOS system allocator.

static void *	operator new (std::size_t bytes, void *ptr)
	Emplace a new object instance.

static void *	operator new[] (std::size_t bytes)
	Allocate space for an array of new object instances using the RTOS system allocator.

static void *	operator new[] (std::size_t bytes, void *ptr)
	Emplace an array of new object instances.

static void	operator delete (void *ptr, std::size_t bytes)
	Deallocate the dynamically allocated object instance. using the RTOS system allocator.

static void	operator delete[] (void *ptr, std::size_t bytes)
	Deallocate the dynamically allocated array of object. instances using the RTOS system allocator.

Static Public Attributes
static const attributes	initializer
	Default event flags initialiser.

Detailed Description

Synchronised event flags.

Synchronised set of flags that can be used to notify events between threads or between ISRs and threads.

Example

event_flags ev;
 
void
consumer(void)
{
  // Do something
  for (; some_condition();)
    {
      ev.wait(0x3)
      // ...
      // Both flags were raised
    }
  // Do something else.
}
 
void
producer1(void)
{
  // Do something
  ev.raise(0x1);
  // ...
  // Do something else.
}
 
void
producer2(void)
{
  // Do something
  ev.raise(0x2);
  // ...
  // Do something else.
}

POSIX compatibility: No POSIX similar functionality identified.

Definition at line 65 of file os-evflags.h.

Constructor & Destructor Documentation

◆ event_flags() [1/2]

os::rtos::event_flags::event_flags ( const attributes & attr = initializer )

Construct an event flags object instance.

Parameters

[in] attr Reference to attributes.

This constructor shall initialise an event flags object with attributes referenced by attr. If the attributes specified by attr are modified later, the event flags attributes shall not be affected. Upon successful initialisation, the state of the event flags object shall become initialised, with all flags cleared.

Only the event flags object itself may be used for performing synchronisation. It is not allowed to make copies of event flags objects.

In cases where default event flags attributes are appropriate, the variable event_flags::initializer can be used to initialise event flags. The effect shall be equivalent to creating an event flags object with the default constructor.

If the attr attributes are modified after the event_flags creation, the event_flags attributes shall not be affected.

Warning: Cannot be invoked from Interrupt Service Routines.

Definition at line 137 of file os-evflags.cpp.

◆ event_flags() [2/2]

os::rtos::event_flags::event_flags	(	const char *	name,
		const attributes &	attr = `initializer`
	)

Construct a named event flags object instance.

Parameters

[in]	name	Pointer to name.
[in]	attr	Reference to attributes.

This constructor shall initialise a named event flags object with attributes referenced by attr. If the attributes specified by attr are modified later, the event flags attributes shall not be affected. Upon successful initialisation, the state of the event flags object shall become initialised, with all flags cleared.

Only the event flags object itself may be used for performing synchronisation. It is not allowed to make copies of event flags objects.

In cases where default event flags attributes are appropriate, the variable event_flags::initializer can be used to initialise event flags. The effect shall be equivalent to creating an event flags object with the default constructor.

If the attr attributes are modified after the event_flags creation, the event_flags attributes shall not be affected.

Warning: Cannot be invoked from Interrupt Service Routines.

Definition at line 171 of file os-evflags.cpp.

◆ ~event_flags()

os::rtos::event_flags::~event_flags ( )

Destruct the event flags object instance.

This destructor shall destroy the event flags object; the object becomes, in effect, uninitialised. An implementation may cause the destructor to set the object to an invalid value.

It shall be safe to destroy an initialised event flags object upon which no threads are currently blocked. Attempting to destroy an event flags object upon which other threads are currently blocked results in undefined behaviour.

Warning: Cannot be invoked from Interrupt Service Routines.

Definition at line 211 of file os-evflags.cpp.

Member Function Documentation

◆ clear()

result_t os::rtos::event_flags::clear	(	flags::mask_t	mask,
		flags::mask_t *	oflags = `nullptr`
	)

Clear event flags.

Parameters

[in]	mask	The OR-ed flags to clear.
[out]	oflags	Optional pointer where to store the previous value of the flags; may be `nullptr`.

Return values

result::ok	The flags were cleared.
EINVAL	The mask is zero.

Note: Can be invoked from Interrupt Service Routines.

Definition at line 588 of file os-evflags.cpp.

◆ get()

flags::mask_t os::rtos::event_flags::get	(	flags::mask_t	mask,
		flags::mode_t	mode = `flags::mode::clear`
	)

Get (and possibly clear) event flags.

Parameters

[in]	mask	The OR-ed flags to get/clear; can be `flags::any`.
[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.

Select the requested event flags and return them. If requested, clear the selected bits in the event flags.

If the mask is flags::any, return the status of all event flags, without any masking or subsequent clearing.

Note: Can be invoked from Interrupt Service Routines.

Definition at line 627 of file os-evflags.cpp.

◆ name()

const char * os::rtos::internal::object_named::name ( void ) const

inlineinherited

Get object name.

Parameters: None.

Returns: A null terminated string.

All objects return a non-null string; anonymous objects return "-".

Note: Can be invoked from Interrupt Service Routines.

Definition at line 774 of file os-decls.h.

◆ operator delete()

void os::rtos::internal::object_named_system::operator delete	(	void *	ptr,
		std::size_t	bytes
	)

inlinestaticinherited

Deallocate the dynamically allocated object instance. using the RTOS system allocator.

Parameters

ptr	Pointer to object.
bytes	Number of bytes to deallocate.

Returns: Nothing.

The deallocation function (3.7.4.2) called by a delete-expression to render the value of ptr invalid.

ptr shall be a null pointer or its value shall be a value returned by an earlier call to the (possibly replaced) operator new() which has not been invalidated by an intervening call to operator delete(void*).

If ptr is null, does nothing. Otherwise, reclaims the storage allocated by the earlier call to operator new.

The storage is deallocated using the RTOS system allocator.

Warning: Cannot be invoked from Interrupt Service Routines.

Definition at line 137 of file os-inlines.h.

◆ operator delete[]()

void os::rtos::internal::object_named_system::operator delete[]	(	void *	ptr,
		std::size_t	bytes
	)

inlinestaticinherited

Deallocate the dynamically allocated array of object. instances using the RTOS system allocator.

Parameters

ptr	Pointer to array of objects.
bytes	Number of bytes to deallocate.

Returns: Nothing.

The deallocation function (3.7.4.2) called by the array form of a delete-expression to render the value of ptr invalid.

If ptr is null, does nothing. Otherwise, reclaims the storage allocated by the earlier call to operator new.

The storage is deallocated using the RTOS system allocator.

Warning: Cannot be invoked from Interrupt Service Routines.

Definition at line 158 of file os-inlines.h.

◆ operator new() [1/2]

void * os::rtos::internal::object_named_system::operator new ( std::size_t bytes )

inlinestaticinherited

Allocate space for a new object instance using the RTOS system allocator.

Parameters

bytes Number of bytes to allocate.

Returns: Pointer to allocated object.

The allocation function (3.7.4.1) called by a new-expression (5.3.4) to allocate a storage of size bytes suitably aligned to represent any object of that size. Return a non-null pointer to suitably aligned storage (3.7.4).

The storage is allocated using the RTOS system allocator.

Warning: Cannot be invoked from Interrupt Service Routines.

Definition at line 59 of file os-inlines.h.

◆ operator new() [2/2]

void * os::rtos::internal::object_named_system::operator new	(	std::size_t	bytes,
		void *	ptr
	)

inlinestaticinherited

Emplace a new object instance.

Parameters

bytes	Number of bytes to emplace.
ptr	Pointer to location to emplace the object.

Returns: Pointer to emplaced object.

The allocation function (3.7.4.1) called by a placement new-expression to allocate a storage of size bytes suitably aligned to represent any object of that size. Return a non-null pointer to suitably aligned storage (3.7.4).

The storage is allocated using the RTOS system allocator.

Warning: Cannot be invoked from Interrupt Service Routines.

Definition at line 96 of file os-inlines.h.

◆ operator new[]() [1/2]

void * os::rtos::internal::object_named_system::operator new[] ( std::size_t bytes )

inlinestaticinherited

Allocate space for an array of new object instances using the RTOS system allocator.

Parameters

bytes Number of bytes to allocate.

Returns: Pointer to allocated array.

The allocation function (3.7.4.1) called by the array form of a new-expression (5.3.4) to allocate a storage of size bytes suitably aligned to represent any array object of that size or smaller.

The storage is allocated using the RTOS system allocator.

Warning: Cannot be invoked from Interrupt Service Routines.

Definition at line 77 of file os-inlines.h.

◆ operator new[]() [2/2]

void * os::rtos::internal::object_named_system::operator new[]	(	std::size_t	bytes,
		void *	ptr
	)

inlinestaticinherited

Emplace an array of new object instances.

Parameters

bytes	Number of bytes to emplace.
ptr	Pointer to location to emplace the object.

Returns: Pointer to emplaced array.

The allocation function (3.7.4.1) called by the array form of a placement new-expression to allocate a storage of size bytes suitably aligned to represent any array object of that size or smaller.

The storage is allocated using the RTOS system allocator.

Warning: Cannot be invoked from Interrupt Service Routines.

Definition at line 113 of file os-inlines.h.

◆ operator==()

bool os::rtos::event_flags::operator== ( const event_flags & rhs ) const

Compare event flags.

Return values

true	The given event flags object is the same as this event flags.
false	The event flags are different.

◆ raise()

result_t os::rtos::event_flags::raise	(	flags::mask_t	mask,
		flags::mask_t *	oflags = `nullptr`
	)

Raise event flags.

Parameters

[in]	mask	The OR-ed flags to raise.
[out]	oflags	Optional pointer where to store the new value of the flags; may be `nullptr`.

Return values

result::ok	The flags were raised.
EINVAL	The mask is zero.
ENOTRECOVERABLE	Raise failed.

Set more bits in the thread current signal mask. Use OR at bit-mask level. Wake-up all waiting threads, if any.

Note: Can be invoked from Interrupt Service Routines.

Definition at line 553 of file os-evflags.cpp.

◆ timed_wait()

result_t os::rtos::event_flags::timed_wait	(	flags::mask_t	mask,
		clock::duration_t	timeout,
		flags::mask_t *	oflags = `nullptr`,
		flags::mode_t	mode = `flags::mode::all \| flags::mode::clear`
	)

Timed wait for event flags.

Parameters

[in]	mask	The expected flags (OR-ed bit-mask); if `flags::any`, any flag raised will do it.
[out]	oflags	Pointer where to store the current flags; may be `nullptr`.
[in]	mode	Mode bits to select if either all or any flags in the mask are expected, and if the flags should be cleared.
[in]	timeout	Timeout to wait.

Return values

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

If the flags::mode::all bit is set, the function expects all requested flags to be raised; otherwise, if the flags::mode::any bit is set, the function expects any single flag to be raised.

If the expected event flags are raised, the function returns instantly.

Otherwise suspend the execution of the current thread until all/any specified event flags are raised.

When the parameter mask is 0, the current thread is suspended until any event flag is raised. In this case, if any event flags are already raised, the function returns instantly.

The wait shall be terminated when the specified timeout expires.

The timeout shall expire after the number of time units (that is when the value of that clock equals or exceeds (now()+duration). The resolution of the timeout shall be the resolution of the clock on which it is based (the SysTick clock for CMSIS).

Under no circumstance shall the operation fail with a timeout if the event flags are already raised. The validity of the timeout need not be checked if the expected flags are already raised and the call can return immediately.

The clock used for timeouts can be specified via the clock attribute. By default, the clock derived from the scheduler timer is used, and the durations are expressed in ticks.

If the flags::mode::clear bit is set, the event flags that are returned are automatically cleared.

Warning: Cannot be invoked from Interrupt Service Routines.

Definition at line 436 of file os-evflags.cpp.

◆ try_wait()

result_t os::rtos::event_flags::try_wait	(	flags::mask_t	mask,
		flags::mask_t *	oflags = `nullptr`,
		flags::mode_t	mode = `flags::mode::all \| flags::mode::clear`
	)

Try to wait for event flags.

Parameters

[in]	mask	The expected flags (OR-ed bit-mask); if `flags::any`, any flag raised will do it.
[out]	oflags	Pointer where to store the current flags; may be `nullptr`.
[in]	mode	Mode bits to select if either all or any flags in the mask are expected, and if the flags should be cleared.

Return values

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

If the flags::mode::all bit is set, the function expects all requested flags to be raised; otherwise, if the flags::mode::any bit is set, the function expects any single flag to be raised.

The function does not blocks, if the expected event flags are not raised, but returns EGAIN.

Note: Can be invoked from Interrupt Service Routines.

Definition at line 354 of file os-evflags.cpp.

◆ wait()

result_t os::rtos::event_flags::wait	(	flags::mask_t	mask,
		flags::mask_t *	oflags,
		flags::mode_t	mode = `flags::mode::all \| flags::mode::clear`
	)

Wait for event flags.

Parameters

[in]	mask	The expected flags (OR-ed bit-mask); if `flags::any`, any flag raised will do it.
[out]	oflags	Pointer where to store the current flags; may be `nullptr`.
[in]	mode	Mode bits to select if either all or any flags in the mask are expected, and if the flags should be cleared.

Return values

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

If the flags::mode::all bit is set, the function expects all requested flags to be raised; otherwise, if the flags::mode::any bit is set, the function expects any single flag to be raised.

If the expected event flags are raised, the function returns instantly.

Otherwise suspend the execution of the current thread until all/any specified event flags are raised.

When the parameter mask is 0, the current thread is suspended until any event flag is raised. In this case, if any event flags are already raised, the function returns instantly.

If the flags::mode::clear bit is set, the event flags that are returned are automatically cleared.

Warning: Cannot be invoked from Interrupt Service Routines.

Definition at line 251 of file os-evflags.cpp.

◆ waiting()

bool os::rtos::event_flags::waiting ( void )

Check if there are threads waiting.

Parameters: None.

Return values

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

Note: Can be invoked from Interrupt Service Routines.

Definition at line 655 of file os-evflags.cpp.

The documentation for this class was generated from the following files:

Classes

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ event_flags() [1/2]

◆ event_flags() [2/2]

◆ ~event_flags()

Member Function Documentation

◆ clear()

◆ get()

◆ name()

◆ operator delete()

◆ operator delete[]()

◆ operator new() [1/2]

◆ operator new() [2/2]

◆ operator new[]() [1/2]

◆ operator new[]() [2/2]

◆ operator==()

◆ raise()

◆ timed_wait()

◆ try_wait()

◆ wait()

◆ waiting()