µOS++ IIIe Reference  v6.3.15
“Perfekt ist nicht gut genug”
The third edition of µOS++, a POSIX inspired open source system, written in C++.
os::rtos::event_flags Class Reference

Synchronised event flags. More...

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

Inherits os::rtos::internal::object_named_system.

Classes

class  attributes
 Event flags attributes. More...
 

Public Member Functions

Constructors & Destructor
 event_flags (const attributes &attr=initializer)
 Construct an event flags object instance. More...
 
 event_flags (const char *name, const attributes &attr=initializer)
 Construct a named event flags object instance. More...
 
 ~event_flags ()
 Destruct the event flags object instance. More...
 
Operators
bool operator== (const event_flags &rhs) const
 Compare event flags. More...
 
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. More...
 
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. More...
 
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. More...
 
result_t raise (flags::mask_t mask, flags::mask_t *oflags=nullptr)
 Raise event flags. More...
 
result_t clear (flags::mask_t mask, flags::mask_t *oflags=nullptr)
 Clear event flags. More...
 
flags::mask_t get (flags::mask_t mask, flags::mode_t mode=flags::mode::clear)
 Get (and possibly clear) event flags. More...
 
bool waiting (void)
 Check if there are threads waiting. More...
 
Public Member Functions
const char * name (void) const
 Get object name. More...
 

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. More...
 
static void * operator new (std::size_t bytes, void *ptr)
 Emplace a new object instance. More...
 
static void * operator new[] (std::size_t bytes)
 Allocate space for an array of new object instances using the RTOS system allocator. More...
 
static void * operator new[] (std::size_t bytes, void *ptr)
 Emplace an array of new object instances. More...
 
static void operator delete (void *ptr, std::size_t bytes)
 Deallocate the dynamically allocated object instance. using the RTOS system allocator. More...
 
static void operator delete[] (void *ptr, std::size_t bytes)
 Deallocate the dynamically allocated array of object. instances using the RTOS system allocator. More...
 

Static Public Attributes

static const attributes initializer
 Default event flags initialiser. More...
 

Detailed Description

Synchronised event flags.

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

Example
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 55 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]attrReference 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.

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 125 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]namePointer to name.
[in]attrReference 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.

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 156 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 196 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]maskThe OR-ed flags to clear.
[out]oflagsOptional pointer where to store the previous value of the flags; may be nullptr.
Return values
result::okThe flags were cleared.
EINVALThe mask is zero.
Note
Can be invoked from Interrupt Service Routines.

Definition at line 575 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]maskThe OR-ed flags to get/clear; can be flags::any.
[in]modeMode 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 614 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 760 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
ptrPointer to object.
bytesNumber 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 134 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
ptrPointer to array of objects.
bytesNumber 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 155 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
bytesNumber 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 56 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
bytesNumber of bytes to emplace.
ptrPointer 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 93 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
bytesNumber 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 74 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
bytesNumber of bytes to emplace.
ptrPointer 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 110 of file os-inlines.h.

◆ operator==()

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

Compare event flags.

Return values
trueThe given event flags object is the same as this event flags.
falseThe 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]maskThe OR-ed flags to raise.
[out]oflagsOptional pointer where to store the new value of the flags; may be nullptr.
Return values
result::okThe flags were raised.
EINVALThe mask is zero.
ENOTRECOVERABLERaise 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 538 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]maskThe expected flags (OR-ed bit-mask); if flags::any, any flag raised will do it.
[out]oflagsPointer where to store the current flags; may be nullptr.
[in]modeMode bits to select if either all or any flags in the mask are expected, and if the flags should be cleared.
[in]timeoutTimeout to wait.
Return values
result::okAll expected flags are raised.
EPERMCannot be invoked from an Interrupt Service Routines.
ETIMEDOUTThe expected condition did not occur during the entire timeout duration.
EINVALThe mask is outside of the permitted range.
EINTRThe operation was interrupted.
ENOTRECOVERABLEWait 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 421 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]maskThe expected flags (OR-ed bit-mask); if flags::any, any flag raised will do it.
[out]oflagsPointer where to store the current flags; may be nullptr.
[in]modeMode bits to select if either all or any flags in the mask are expected, and if the flags should be cleared.
Return values
result::okAll expected flags were raised.
EINVALThe mask is outside of the permitted range.
EWOULDBLOCKThe expected condition did not occur.
ENOTRECOVERABLEWait 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 339 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]maskThe expected flags (OR-ed bit-mask); if flags::any, any flag raised will do it.
[out]oflagsPointer where to store the current flags; may be nullptr.
[in]modeMode bits to select if either all or any flags in the mask are expected, and if the flags should be cleared.
Return values
result::okAll expected flags were raised.
EPERMCannot be invoked from an Interrupt Service Routines.
EINVALThe mask is outside of the permitted range.
EINTRThe operation was interrupted.
ENOTRECOVERABLEWait 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 236 of file os-evflags.cpp.

◆ waiting()

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

Check if there are threads waiting.

Parameters
None.
Return values
trueThere are threads waiting.
falseThere are no threads waiting.
Note
Can be invoked from Interrupt Service Routines.

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


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