os::rtos::event_flags Class Reference

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 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 56 of file os-evflags.h.

Constructor & Destructor Documentation

event_flags() [1/2]

os::rtos::event_flags::event_flags

(

const attributes &

attr = initializer

)

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 128 of file os-evflags.cpp.

        : event_flags{ nullptr, attr }
    {
    }

event_flags() [2/2]

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

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 163 of file os-evflags.cpp.

        : object_named_system{ name }
    {
#if defined(OS_TRACE_RTOS_EVFLAGS)
      trace::printf ("%s() @%p %s\n", __func__, this, this->name ());
#endif
 
      // Don't call this from interrupt handlers.
      os_assert_throw (!interrupts::in_handler_mode (), EPERM);
 
#if !defined(OS_USE_RTOS_PORT_EVENT_FLAGS)
      clock_ = attr.clock != nullptr ? attr.clock : &sysclock;
#endif
 
#if defined(OS_USE_RTOS_PORT_EVENT_FLAGS)
 
      port::event_flags::create (this);
 
#else
 
#endif
    }

References os::rtos::internal::attributes_clocked::clock, os::rtos::interrupts::in_handler_mode(), os_assert_throw, os::trace::printf(), and os::rtos::sysclock.

~event_flags()

os::rtos::event_flags::~event_flags

(

)

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 201 of file os-evflags.cpp.

    {
#if defined(OS_TRACE_RTOS_EVFLAGS)
      trace::printf ("%s() @%p %s\n", __func__, this, name ());
#endif
 
#if defined(OS_USE_RTOS_PORT_EVENT_FLAGS)
 
      port::event_flags::destroy (this);
 
#else
 
      // There must be no threads waiting for these flags.
      assert (list_.empty ());
 
#endif
    }

References os::rtos::internal::object_named::name(), and os::trace::printf().

Member Function Documentation

clear()

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

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 575 of file os-evflags.cpp.

    {
#if defined(OS_TRACE_RTOS_EVFLAGS)
      trace::printf ("%s(0x%X) @%p %s <0x%X \n", __func__, mask, this, name (),
                     event_flags_.mask ());
#endif
 
#if defined(OS_USE_RTOS_PORT_EVENT_FLAGS)
 
      os_assert_err (mask != 0, EINVAL);
 
      return port::event_flags::clear (this, mask, oflags);
 
#else
 
      result_t res = event_flags_.clear (mask, oflags);
 
#if defined(OS_TRACE_RTOS_EVFLAGS)
      trace::printf ("%s(0x%X) @%p %s >0x%X\n", __func__, mask, this, name (),
                     event_flags_.mask ());
#endif
 
      return res;
 
#endif
    }

References os::rtos::internal::object_named::name(), os_assert_err, and os::trace::printf().

get()

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

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 614 of file os-evflags.cpp.

    {
#if defined(OS_TRACE_RTOS_EVFLAGS)
      trace::printf ("%s(0x%X) @%p %s  \n", __func__, mask, this, name ());
#endif
 
#if defined(OS_USE_RTOS_PORT_EVENT_FLAGS)
 
      return port::event_flags::get (this, mask, mode);
 
#else
 
      flags::mask_t ret = event_flags_.get (mask, mode);
 
#if defined(OS_TRACE_RTOS_EVFLAGS)
      trace::printf ("%s(0x%X)=0x%X @%p %s \n", __func__, mask,
                     event_flags_.mask (), this, name ());
#endif
      // Return the selected flags.
      return ret;
 
#endif
    }

References os::rtos::internal::object_named::name(), and os::trace::printf().

name()

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

inlineinherited

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 753 of file os-decls.h.

      {
        return name_;
      }

Referenced by os::memory::lifo::lifo(), os::memory::malloc_memory_resource::malloc_memory_resource(), os::rtos::message_queue_typed< T, Allocator >::message_queue_typed(), os::memory::block_pool::~block_pool(), ~event_flags(), os::memory::first_fit_top::~first_fit_top(), os::memory::lifo::~lifo(), os::memory::malloc_memory_resource::~malloc_memory_resource(), os::rtos::memory_pool::~memory_pool(), os::rtos::message_queue::~message_queue(), os::rtos::mutex::~mutex(), os::rtos::semaphore::~semaphore(), os::rtos::thread::~thread(), os::rtos::timer::~timer(), os::rtos::memory_pool::alloc(), os::rtos::thread::cancel(), clear(), os::rtos::mutex::consistent(), os::rtos::thread::detach(), os::memory::new_delete_memory_resource::do_allocate(), os::memory::block_pool::do_allocate(), os::memory::first_fit_top::do_allocate(), os::memory::lifo::do_allocate(), os::memory::malloc_memory_resource::do_allocate(), os::rtos::thread::flags_raise(), os::rtos::memory_pool::free(), get(), os::rtos::thread::interrupt(), os::rtos::thread::join(), os::rtos::thread::kill(), os::rtos::internal::terminated_threads_list::link(), os::rtos::mutex::lock(), os::rtos::memory::memory_resource::out_of_memory_handler(), os::rtos::semaphore::post(), os::rtos::mutex::prio_ceiling(), os::rtos::mutex::prio_ceiling(), os::rtos::thread::priority(), os::rtos::thread::priority_inherited(), raise(), os::rtos::message_queue::receive(), os::rtos::memory_pool::reset(), os::rtos::message_queue::reset(), os::rtos::mutex::reset(), os::rtos::semaphore::reset(), os::rtos::thread::resume(), os::rtos::message_queue::send(), os::rtos::clock::sleep_for(), os::rtos::timer::start(), os::rtos::timer::stop(), os::rtos::memory_pool::timed_alloc(), os::rtos::mutex::timed_lock(), os::rtos::message_queue::timed_receive(), os::rtos::message_queue::timed_send(), os::rtos::semaphore::timed_wait(), timed_wait(), os::rtos::memory::memory_resource::trace_print_statistics(), os::rtos::memory_pool::try_alloc(), os::rtos::mutex::try_lock(), os::rtos::message_queue::try_receive(), os::rtos::message_queue::try_send(), try_wait(), os::rtos::semaphore::try_wait(), os::rtos::internal::ready_threads_list::unlink_head(), os::rtos::mutex::unlock(), wait(), os::rtos::semaphore::wait(), and waiting().

operator delete()

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

inlinestaticinherited

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 120 of file os-inlines.h.

      {
        assert (!interrupts::in_handler_mode ());
 
        rtos::memory::allocator<char> ().deallocate (static_cast<char*> (ptr),
                                                     bytes);
      }

References os::rtos::memory::allocator_stateless_default_resource< T >::deallocate(), and os::rtos::interrupts::in_handler_mode().

operator delete[]()

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

inlinestaticinherited

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 141 of file os-inlines.h.

      {
        // Forward array deallocation to single element deallocation.
        operator delete (ptr, bytes);
      }

operator new() [1/2]

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

inlinestaticinherited

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 43 of file os-inlines.h.

      {
        assert (!interrupts::in_handler_mode ());
 
        return rtos::memory::allocator<char> ().allocate (bytes);
      }

References os::rtos::memory::allocator_stateless_default_resource< T >::allocate(), and os::rtos::interrupts::in_handler_mode().

operator new() [2/2]

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

inlinestaticinherited

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 80 of file os-inlines.h.

      {
        return ptr;
      }

operator new[]() [1/2]

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

inlinestaticinherited

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 61 of file os-inlines.h.

      {
        // Forward array allocation to single element allocation.
        return operator new (bytes);
      }

operator new[]() [2/2]

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

inlinestaticinherited

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 97 of file os-inlines.h.

      {
        // Forward array allocation to single element allocation.
        return operator new (bytes, ptr);
      }

operator==()

bool os::rtos::event_flags::operator==

(

const event_flags &

rhs

)

const

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
	)

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 540 of file os-evflags.cpp.

    {
#if defined(OS_TRACE_RTOS_EVFLAGS)
      trace::printf ("%s(0x%X) @%p %s <0x%X \n", __func__, mask, this, name (),
                     event_flags_.mask ());
#endif
 
#if defined(OS_USE_RTOS_PORT_EVENT_FLAGS)
 
      os_assert_err (mask != 0, EINVAL);
 
      return port::event_flags::raise (this, mask, oflags);
 
#else
 
      result_t res = event_flags_.raise (mask, oflags);
 
      // Wake-up all threads, if any.
      // Need not be inside the critical section,
      // the list is protected by inner `resume_one()`.
      list_.resume_all ();
 
#if defined(OS_TRACE_RTOS_EVFLAGS)
      trace::printf ("%s(0x%X) @%p %s >0x%X\n", __func__, mask, this, name (),
                     event_flags_.mask ());
#endif
      return res;
 
#endif
    }

References os::rtos::internal::object_named::name(), os_assert_err, and os::trace::printf().

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
	)

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 425 of file os-evflags.cpp.

    {
#if defined(OS_TRACE_RTOS_EVFLAGS)
      trace::printf ("%s(0x%X,%u,%u) @%p %s <0x%X\n", __func__, mask, timeout,
                     mode, this, name (), event_flags_.mask ());
#endif
 
      // Don't call this from interrupt handlers.
      os_assert_throw (!interrupts::in_handler_mode (), EPERM);
      // Don't call this from critical regions.
      os_assert_throw (!scheduler::locked (), EPERM);
 
#if defined(OS_USE_RTOS_PORT_EVENT_FLAGS)
 
      return port::event_flags::timed_wait (this, mask, timeout, oflags, mode);
 
#else
 
      // Extra test before entering the loop, with its inherent weight.
      // Trade size for speed.
      {
        // ----- Enter critical section ---------------------------------------
        interrupts::critical_section ics;
 
        if (event_flags_.check_raised (mask, oflags, mode))
          {
#if defined(OS_TRACE_RTOS_EVFLAGS)
            trace::printf ("%s(0x%X,%u,%u) @%p %s >0x%X\n", __func__, mask,
                           timeout, mode, this, name (), event_flags_.mask ());
#endif
            return result::ok;
          }
        // ----- Exit critical section ----------------------------------------
      }
 
      thread& crt_thread = this_thread::thread ();
 
      // Prepare a list node pointing to the current thread.
      // Do not worry for being on stack, it is temporarily linked to the
      // list and guaranteed to be removed before this function returns.
      internal::waiting_thread_node node{ crt_thread };
 
      internal::clock_timestamps_list& clock_list = clock_->steady_list ();
      clock::timestamp_t timeout_timestamp = clock_->steady_now () + timeout;
 
      // Prepare a timeout node pointing to the current thread.
      internal::timeout_thread_node timeout_node{ timeout_timestamp,
                                                  crt_thread };
 
      for (;;)
        {
          {
            // ----- Enter critical section -----------------------------------
            interrupts::critical_section ics;
 
            if (event_flags_.check_raised (mask, oflags, mode))
              {
#if defined(OS_TRACE_RTOS_EVFLAGS)
                trace::printf ("%s(0x%X,%u,%u) @%p %s >0x%X\n", __func__, mask,
                               timeout, mode, this, name (),
                               event_flags_.mask ());
#endif
                return result::ok;
              }
 
            // Add this thread to the event flags waiting list,
            // and the clock timeout list.
            scheduler::internal_link_node (list_, node, clock_list,
                                           timeout_node);
            // state::suspended set in above link().
            // ----- Exit critical section ------------------------------------
          }
 
          port::scheduler::reschedule ();
 
          // Remove the thread from the event flags waiting list,
          // if not already removed by raise() and from the clock
          // timeout list, if not already removed by the timer.
          scheduler::internal_unlink_node (node, timeout_node);
 
          if (crt_thread.interrupted ())
            {
#if defined(OS_TRACE_RTOS_EVFLAGS)
              trace::printf ("%s(0x%X,%u,%u) EINTR @%p %s 0x%X \n", __func__,
                             mask, timeout, mode, this, name ());
#endif
              return EINTR;
            }
 
          if (clock_->steady_now () >= timeout_timestamp)
            {
#if defined(OS_TRACE_RTOS_EVFLAGS)
              trace::printf ("%s(0x%X,%u,%u) ETIMEDOUT @%p %s 0x%X \n",
                             __func__, mask, timeout, mode, this, name ());
#endif
              return ETIMEDOUT;
            }
        }
 
      /* NOTREACHED */
      return ENOTRECOVERABLE;
 
#endif
    }

References os::rtos::interrupts::in_handler_mode(), os::rtos::thread::interrupted(), os::rtos::scheduler::locked(), os::rtos::internal::object_named::name(), os::rtos::result::ok, os_assert_throw, os::trace::printf(), os::rtos::port::scheduler::reschedule(), and os::rtos::this_thread::thread().

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
	)

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 343 of file os-evflags.cpp.

    {
#if defined(OS_TRACE_RTOS_EVFLAGS)
      trace::printf ("%s(0x%X,%u) @%p %s <0x%X\n", __func__, mask, mode, this,
                     name (), event_flags_.mask ());
#endif
 
#if defined(OS_USE_RTOS_PORT_EVENT_FLAGS)
 
      return port::event_flags::try_wait (this, mask, oflags, mode);
 
#else
 
      // Don't call this from high priority interrupts.
      assert (port::interrupts::is_priority_valid ());
 
      {
        // ----- Enter critical section ---------------------------------------
        interrupts::critical_section ics;
 
        if (event_flags_.check_raised (mask, oflags, mode))
          {
#if defined(OS_TRACE_RTOS_EVFLAGS)
            trace::printf ("%s(0x%X,%u) @%p %s >0x%X\n", __func__, mask, mode,
                           this, name (), event_flags_.mask ());
#endif
            return result::ok;
          }
        else
          {
#if defined(OS_TRACE_RTOS_EVFLAGS)
            trace::printf ("%s(0x%X,%u) EWOULDBLOCK @%p %s \n", __func__, mask,
                           mode, this, name ());
#endif
            return EWOULDBLOCK;
          }
        // ----- Exit critical section ----------------------------------------
      }
 
#endif
    }

References os::rtos::internal::object_named::name(), os::rtos::result::ok, and os::trace::printf().

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
	)

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 241 of file os-evflags.cpp.

    {
#if defined(OS_TRACE_RTOS_EVFLAGS)
      trace::printf ("%s(0x%X,%u) @%p %s <0x%X\n", __func__, mask, mode, this,
                     name (), event_flags_.mask ());
#endif
 
      // Don't call this from interrupt handlers.
      os_assert_throw (!interrupts::in_handler_mode (), EPERM);
      // Don't call this from critical regions.
      os_assert_throw (!scheduler::locked (), EPERM);
 
#if defined(OS_USE_RTOS_PORT_EVENT_FLAGS)
 
      return port::event_flags::wait (this, mask, oflags, mode);
 
#else
 
      {
        // ----- Enter critical section ---------------------------------------
        interrupts::critical_section ics;
 
        if (event_flags_.check_raised (mask, oflags, mode))
          {
#if defined(OS_TRACE_RTOS_EVFLAGS)
            trace::printf ("%s(0x%X,%u) @%p %s >0x%X\n", __func__, mask, mode,
                           this, name (), event_flags_.mask ());
#endif
            return result::ok;
          }
        // ----- Exit critical section ----------------------------------------
      }
 
      thread& crt_thread = this_thread::thread ();
 
      // Prepare a list node pointing to the current thread.
      // Do not worry for being on stack, it is temporarily linked to the
      // list and guaranteed to be removed before this function returns.
      internal::waiting_thread_node node{ crt_thread };
 
      for (;;)
        {
          {
            // ----- Enter critical section -----------------------------------
            interrupts::critical_section ics;
 
            if (event_flags_.check_raised (mask, oflags, mode))
              {
#if defined(OS_TRACE_RTOS_EVFLAGS)
                trace::printf ("%s(0x%X,%u) @%p %s >0x%X\n", __func__, mask,
                               mode, this, name (), event_flags_.mask ());
#endif
                return result::ok;
              }
 
            // Add this thread to the event flags waiting list.
            scheduler::internal_link_node (list_, node);
            // state::suspended set in above link().
            // ----- Exit critical section ------------------------------------
          }
 
          port::scheduler::reschedule ();
 
          {
            // ----- Enter critical section -----------------------------------
            interrupts::critical_section ics;
 
            // Remove the thread from the event flags waiting list,
            // if not already removed by raise().
            scheduler::internal_unlink_node (node);
            // ----- Exit critical section ------------------------------------
          }
 
          if (crt_thread.interrupted ())
            {
#if defined(OS_TRACE_RTOS_EVFLAGS)
              trace::printf ("%s(0x%X,%u) EINTR @%p %s\n", __func__, mask,
                             mode, this, name ());
#endif
              return EINTR;
            }
        }
 
      /* NOTREACHED */
      return ENOTRECOVERABLE;
 
#endif
    }

References os::rtos::interrupts::in_handler_mode(), os::rtos::thread::interrupted(), os::rtos::scheduler::locked(), os::rtos::internal::object_named::name(), os::rtos::result::ok, os_assert_throw, os::trace::printf(), os::rtos::port::scheduler::reschedule(), and os::rtos::this_thread::thread().

waiting()

bool os::rtos::event_flags::waiting

(

void

)

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 642 of file os-evflags.cpp.

    {
#if defined(OS_TRACE_RTOS_EVFLAGS)
      trace::printf ("%s() @%p %s\n", __func__, this, name ());
#endif
 
#if defined(OS_USE_RTOS_PORT_EVENT_FLAGS)
 
      return port::event_flags::waiting (this);
 
#else
 
      // Don't call this from high priority interrupts.
      assert (port::interrupts::is_priority_valid ());
 
      {
        // ----- Enter critical section ---------------------------------------
        interrupts::critical_section ics;
 
        return !list_.empty ();
        // ----- Exit critical section ----------------------------------------
      }
 
#endif
    }

References os::rtos::internal::object_named::name(), and os::trace::printf().

---

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

• os-evflags.h
• os-evflags.cpp