os::rtos::message_queue_inclusive< T, N > Class Template Reference

Template of a POSIX compliant message queue with message type and local storage. More...

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

Inheritance diagram for os::rtos::message_queue_inclusive< T, N >:

Public Types
using	allocator_type = memory::allocator< thread::stack::allocation_element_t >
	Default RTOS allocator.
using	index_t = message_queue::size_t
	Type of list index storage.
using	msg_size_t = uint16_t
	Type of message size storage.
using	priority_t = uint8_t
	Type of message priority storage.
using	size_t = uint8_t
	Type of a queue size storage.
using	value_type = T
	Local type of message.

Public Member Functions
template<typename T >
constexpr std::size_t	compute_allocated_size_bytes (std::size_t msgs, std::size_t msg_size_bytes)
	Calculator for queue storage requirements.
Constructors & Destructor
	message_queue_inclusive (const attributes &attr=initializer)
	Construct a typed message queue object instance.
	message_queue_inclusive (const char *name, const attributes &attr=initializer)
	Construct a named typed message queue object instance.
virtual	~message_queue_inclusive () override
	Destruct the typed message queue object instance.
Public Member Functions
result_t	send (const value_type *msg, priority_t mprio=default_priority)
	Send a typed message to the queue.
result_t	try_send (const value_type *msg, priority_t mprio=default_priority)
	Try to send a typed message to the queue.
result_t	timed_send (const value_type *msg, clock::duration_t timeout, priority_t mprio=default_priority)
	Send a typed message to the queue with timeout.
result_t	receive (value_type *msg, priority_t *mprio=nullptr)
	Receive a typed message from the queue.
result_t	try_receive (value_type *msg, priority_t *mprio=nullptr)
	Try to receive a typed message from the queue.
result_t	timed_receive (value_type *msg, clock::duration_t timeout, priority_t *mprio=nullptr)
	Receive a typed message from the queue with timeout.
Operators
bool	operator== (const message_queue &rhs) const
	Compare memory queues.
Public Member Functions
result_t	send (const void *msg, std::size_t nbytes, priority_t mprio=default_priority)
	Send a message to the queue.
result_t	try_send (const void *msg, std::size_t nbytes, priority_t mprio=default_priority)
	Try to send a message to the queue.
result_t	timed_send (const void *msg, std::size_t nbytes, clock::duration_t timeout, priority_t mprio=default_priority)
	Send a message to the queue with timeout.
result_t	receive (void *msg, std::size_t nbytes, priority_t *mprio=nullptr)
	Receive a message from the queue.
result_t	try_receive (void *msg, std::size_t nbytes, priority_t *mprio=nullptr)
	Try to receive a message from the queue.
result_t	timed_receive (void *msg, std::size_t nbytes, clock::duration_t timeout, priority_t *mprio=nullptr)
	Receive a message from the queue with timeout.
std::size_t	capacity (void) const
	Get queue capacity.
std::size_t	length (void) const
	Get queue length.
std::size_t	msg_size (void) const
	Get message size.
bool	empty (void) const
	Check if the queue is empty.
bool	full (void) const
	Check if the queue is full.
result_t	reset (void)
	Reset the message queue.
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 constexpr priority_t	default_priority = 0
	Default message priority.
static const attributes	initializer
	Default message queue initialiser.
static constexpr msg_size_t	max_msg_size = 0xFFFF
	Maximum message size.
static constexpr priority_t	max_priority = 0xFF
	Maximum message priority.
static constexpr message_queue::size_t	max_size = 0xFF
	Maximum queue size.
static const std::size_t	msgs = N
	Local constant based on template definition.
static constexpr index_t	no_index = max_size
	Index value to represent an illegal index.

Detailed Description

template<typename T, std::size_t N>
class os::rtos::message_queue_inclusive< T, N >

If the queue size is known at compile time and the queue is used for the entire application life cycle, it might be preferred to allocate the queue storage statically inside the queue instance.

For convenience, message_queue_inclusive are also typed, so the message size is handled automatically.

Example

// Define the message type.
typedef struct {
  uint32_t id;
} msg_t;
 
// Define the queue size.
constexpr uint32_t queue_size = 5;
 
// The queue storage is allocated statically inside this instance.
message_queue_inclusive<msg_t, queue_size> mq;
 
void
consumer(void)
{
  // Do something
  msg_t msg;
  for (; some_condition();)
    {
      mq.receive(&msg);
      // Process message
      if (msg.id == 7)
        {
          // Something special
        }
    }
  // Do something else.
}
 
void
producer(void)
{
  // Do something
  msg_t msg;
  msg.id = 7;
  mq.send(&msg);
  // Do something else.
}

Definition at line 1042 of file os-mqueue.h.

Member Typedef Documentation

value_type

template<typename T , std::size_t N>

using os::rtos::message_queue_inclusive< T, N >::value_type = T

Definition at line 1048 of file os-mqueue.h.

Constructor & Destructor Documentation

message_queue_inclusive() [1/2]

template<typename T , std::size_t N>

os::rtos::message_queue_inclusive< T, N >::message_queue_inclusive ( const attributes &  attr = initializer )

inline

Parameters

[in]

attr

Reference to attributes.

This constructor shall initialise a message queue object with attributes referenced by attr. If the attributes specified by attr are modified later, the memory pool attributes shall not be affected. Upon successful initialisation, the state of the message queue object shall become initialised.

Only the message queue itself may be used for performing synchronisation. It is not allowed to make copies of message queue objects.

In cases where default message queue attributes are appropriate, the variable message_queue::initializer can be used to initialise message queue. The effect shall be equivalent to creating a message queue object with the simple constructor.

The storage shall be statically allocated inside the message queue object instance.

Passing a storage via the attributes is not allowed and might trigger an assert.

Note

These objects are better instantiated as global static objects. When instantiated on the thread stack, the stack should be sized accordingly, including the internal lists overhead.

Implemented as a wrapper over the parent constructor, automatically passing the message size and the storage details.

Warning

Cannot be invoked from Interrupt Service Routines.

Definition at line 1723 of file os-mqueue.h.

        : message_queue_inclusive{ nullptr, attr }
    {
    }

message_queue_inclusive() [2/2]

template<typename T , std::size_t N>

os::rtos::message_queue_inclusive< T, N >::message_queue_inclusive	(	const char *	name,
		const attributes &	attr = initializer
	)

Parameters

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

This constructor shall initialise a named message queue object with attributes referenced by attr. If the attributes specified by attr are modified later, the memory pool attributes shall not be affected. Upon successful initialisation, the state of the message queue object shall become initialised.

Only the message queue itself may be used for performing synchronisation. It is not allowed to make copies of message queue objects.

In cases where default message queue attributes are appropriate, the variable message_queue::initializer can be used to initialise message queue. The effect shall be equivalent to creating a message queue object with the simple constructor.

The storage shall be statically allocated inside the message queue object instance.

Passing a storage via the attributes is not allowed and might trigger an assert.

Note

These objects are better instantiated as global static objects. When instantiated on the thread stack, the stack should be sized accordingly, including the internal lists overhead.

Implemented as a wrapper over the parent constructor, automatically passing the message size and the storage details.

Warning

Cannot be invoked from Interrupt Service Routines.

Definition at line 1764 of file os-mqueue.h.

        : message_queue (name)
    {
      static_assert (sizeof (T) >= sizeof (void*),
                     "Messages of message_queue need to have at least the "
                     "size of a pointer");
 
      internal_construct_ (msgs, sizeof (value_type), attr, &arena_,
                           sizeof (arena_));
    }

References os::rtos::message_queue_inclusive< T, N >::msgs.

~message_queue_inclusive()

template<typename T , std::size_t N>

os::rtos::message_queue_inclusive< T, N >::~message_queue_inclusive

overridevirtual

This destructor shall destroy the message queue 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 message queue object upon which no threads are currently blocked. Attempting to destroy a message queue object upon which other threads are currently blocked results in undefined behaviour.

Implemented as a wrapper over the parent destructor.

Definition at line 1790 of file os-mqueue.h.

    {
    }

Member Function Documentation

capacity()

std::size_t os::rtos::message_queue::capacity ( void  ) const

inlineinherited

Parameters

None.

Returns

The max number of messages that can be queued.

POSIX compatibility

Note

Can be invoked from Interrupt Service Routines. Extension to standard, no POSIX similar functionality identified.

Definition at line 1305 of file os-mqueue.h.

    {
      return msgs_;
    }

Referenced by os::rtos::message_queue::full().

compute_allocated_size_bytes()

template<typename T >

constexpr std::size_t os::rtos::message_queue::compute_allocated_size_bytes ( std::size_t  msgs, std::size_t  msg_size_bytes  )

inlineconstexprinherited

Parameters

msgs	Number of messages.
msg_size_bytes	Size of message.

Returns

Total required storage in bytes, including internal alignment.

Definition at line 253 of file os-mqueue.h.

      {
        // Align each message
        return (msgs
                * ((msg_size_bytes + (sizeof (T) - 1)) & ~(sizeof (T) - 1)))
               // Align the indices array
               + ((2 * msgs * sizeof (index_t) + (sizeof (T) - 1))
                  & ~(sizeof (T) - 1))
               // Align the priority array
               + ((msgs * sizeof (priority_t) + (sizeof (T) - 1))
                  & ~(sizeof (T) - 1));
      }

Referenced by os::rtos::message_queue::message_queue(), and os::rtos::message_queue_allocated< Allocator >::message_queue_allocated().

empty()

bool os::rtos::message_queue::empty ( void  ) const

inlineinherited

Parameters

None.

Return values

true	The queue has no messages.
false	The queue has some messages.

POSIX compatibility

Extension to standard, no POSIX similar functionality identified.

Note

Can be invoked from Interrupt Service Routines.

Definition at line 1329 of file os-mqueue.h.

    {
      return (length () == 0);
    }

References os::rtos::message_queue::length().

full()

bool os::rtos::message_queue::full ( void  ) const

inlineinherited

Parameters

None.

Return values

true	The queue is full.
false	The queue is not full.

POSIX compatibility

Extension to standard, no POSIX similar functionality identified.

Note

Can be invoked from Interrupt Service Routines.

Definition at line 1341 of file os-mqueue.h.

    {
      return (length () == capacity ());
    }

References os::rtos::message_queue::capacity(), and os::rtos::message_queue::length().

length()

std::size_t os::rtos::message_queue::length ( void  ) const

inlineinherited

Parameters

None.

Returns

The number of messages in the queue.

POSIX compatibility

Extension to standard, no POSIX similar functionality identified.

Note

Can be invoked from Interrupt Service Routines.

Definition at line 1293 of file os-mqueue.h.

    {
      return count_;
    }

Referenced by os::rtos::message_queue::empty(), and os::rtos::message_queue::full().

msg_size()

std::size_t os::rtos::message_queue::msg_size ( void  ) const

inlineinherited

Parameters

None.

Returns

The message size, in bytes.

POSIX compatibility

Extension to standard, no POSIX similar functionality identified.

Note

Can be invoked from Interrupt Service Routines.

Definition at line 1317 of file os-mqueue.h.

    {
      return msg_size_bytes_;
    }

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(), os::rtos::event_flags::~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(), os::rtos::event_flags::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(), os::rtos::event_flags::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(), os::rtos::event_flags::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(), os::rtos::event_flags::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(), os::rtos::event_flags::try_wait(), os::rtos::semaphore::try_wait(), os::rtos::internal::ready_threads_list::unlink_head(), os::rtos::mutex::unlock(), os::rtos::event_flags::wait(), os::rtos::semaphore::wait(), and os::rtos::event_flags::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::message_queue::operator== ( const message_queue &  rhs ) const

inlineinherited

Return values

true	The given memory queue is the same as this memory queue.
false	The memory queues are different.

Identical message queues should have the same memory address.

POSIX compatibility

Extension to standard, no POSIX similar functionality identified.

Definition at line 1281 of file os-mqueue.h.

    {
      return this == &rhs;
    }

receive() [1/2]

template<typename T , std::size_t N>

result_t os::rtos::message_queue_inclusive< T, N >::receive ( value_type *  msg, priority_t *  mprio = nullptr  )

inline

Parameters

[out]	msg	The address where to store the dequeued message.
[out]	mprio	The address where to store the message priority. The default is nullptr.

Return values

result::ok	The message was received.
EINVAL	A parameter is invalid or outside of a permitted range.
EMSGSIZE	The specified message length, nbytes, is greater than the message size attribute of the message queue.
EPERM	Cannot be invoked from an Interrupt Service Routines.
ENOTRECOVERABLE	The message could not be dequeued (extension to POSIX).
EBADMSG	The implementation has detected a data corruption problem with the message.
EINTR	The operation was interrupted.

Wrapper over the parent method, automatically passing the message size.

See also

message_queue::receive().

Definition at line 1852 of file os-mqueue.h.

    {
      return message_queue::receive (reinterpret_cast<char*> (msg),
                                     sizeof (value_type), mprio);
    }

References os::rtos::message_queue::receive().

receive() [2/2]

result_t os::rtos::message_queue::receive ( void *  msg, std::size_t  nbytes, priority_t *  mprio = nullptr  )

inherited

Parameters

[out]	msg	The address where to store the dequeued message.
[in]	nbytes	The size of the destination buffer. Must be lower than the value used when creating the queue.
[out]	mprio	The address where to store the message priority. The default is nullptr.

Return values

result::ok	The message was received.
EINVAL	A parameter is invalid or outside of a permitted range.
EMSGSIZE	The specified message length, nbytes, is greater than the message size attribute of the message queue.
EPERM	Cannot be invoked from an Interrupt Service Routines.
ENOTRECOVERABLE	The message could not be dequeued (extension to POSIX).
EBADMSG	The implementation has detected a data corruption problem with the message.
EINTR	The operation was interrupted.

The receive() function shall receive the oldest of the highest priority message(s) from the message queue. If the size of the buffer in bytes, specified by the nbytes argument, is less than the msg_size_bytes attribute of the message queue, the function shall fail and return an error. Otherwise, the selected message shall be removed from the queue and copied to the buffer pointed to by the msg argument.

If the value of nbytes is greater than message_queue::max_size, the result is implementation-defined.

If the argument mprio is not nullptr, the priority of the selected message shall be stored in the location referenced by mprio.

If the message queue is empty, receive() shall block until a message is enqueued on the message queue or until receive() is cancelled/interrupted. If more than one thread is waiting to receive a message when a message arrives at an empty queue and the Priority Scheduling option is supported, then the thread of highest priority that has been waiting the longest shall be selected to receive the message. Otherwise, it is unspecified which waiting thread receives the message.

POSIX compatibility

Inspired by mq_receive() with O_NONBLOCK not set, from <mqueue.h> (IEEE Std 1003.1, 2013 Edition).

Warning

Cannot be invoked from Interrupt Service Routines.

Definition at line 1269 of file os-mqueue.cpp.

    {
#if defined(OS_TRACE_RTOS_MQUEUE)
      trace::printf ("%s(%p,%u) @%p %s\n", __func__, msg, nbytes, this,
                     name ());
#endif
 
      // Don't call this from interrupt handlers.
      os_assert_err (!interrupts::in_handler_mode (), EPERM);
      // Don't call this from critical regions.
      os_assert_err (!scheduler::locked (), EPERM);
 
      os_assert_err (msg != nullptr, EINVAL);
      os_assert_err (nbytes <= msg_size_bytes_, EMSGSIZE);
 
#if defined(OS_USE_RTOS_PORT_MESSAGE_QUEUE)
 
      return port::message_queue::receive (this, msg, nbytes, mprio);
 
#else
 
      // Extra test before entering the loop, with its inherent weight.
      // Trade size for speed.
      {
        // ----- Enter critical section ---------------------------------------
        interrupts::critical_section ics;
 
        if (internal_try_receive_ (msg, nbytes, mprio))
          {
            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 (internal_try_receive_ (msg, nbytes, mprio))
              {
                return result::ok;
              }
 
            // Add this thread to the message queue receive waiting list.
            scheduler::internal_link_node (receive_list_, node);
            // state::suspended set in above link().
            // ----- Exit critical section ------------------------------------
          }
 
          port::scheduler::reschedule ();
 
          // Remove the thread from the message queue receive waiting list,
          // if not already removed by send().
          scheduler::internal_unlink_node (node);
 
          if (crt_thread.interrupted ())
            {
#if defined(OS_TRACE_RTOS_MQUEUE)
              trace::printf ("%s(%p,%u) EINTR @%p %s\n", __func__, msg, nbytes,
                             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_err, os::trace::printf(), os::rtos::port::scheduler::reschedule(), and os::rtos::this_thread::thread().

Referenced by os::rtos::message_queue_typed< T, Allocator >::receive(), and os::rtos::message_queue_inclusive< T, N >::receive().

reset()

result_t os::rtos::message_queue::reset ( void  )

inherited

Parameters

None.

Return values

result::ok	The queue was reset.
EPERM	Cannot be invoked from an Interrupt Service Routines.

Clear both send and receive counter and return the queue to the initial state.

POSIX compatibility

Extension to standard, no POSIX similar functionality identified.

Warning

Cannot be invoked from Interrupt Service Routines.

Definition at line 1596 of file os-mqueue.cpp.

    {
#if defined(OS_TRACE_RTOS_MQUEUE)
      trace::printf ("%s() @%p %s\n", __func__, this, name ());
#endif
 
      // Don't call this from interrupt handlers.
      os_assert_err (!interrupts::in_handler_mode (), EPERM);
 
#if defined(OS_USE_RTOS_PORT_MESSAGE_QUEUE)
 
      return port::message_queue::reset (this);
 
#else
 
      {
        // ----- Enter critical section ---------------------------------------
        interrupts::critical_section ics;
 
        internal_init_ ();
        return result::ok;
        // ----- Exit critical section ----------------------------------------
      }
 
#endif
    }

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

send() [1/2]

template<typename T , std::size_t N>

result_t os::rtos::message_queue_inclusive< T, N >::send ( const value_type *  msg, priority_t  mprio = default_priority  )

inline

Parameters

[in]	msg	The address of the message to enqueue.
[in]	mprio	The message priority. The default is 0.

Return values

result::ok	The message was enqueued.
EINVAL	A parameter is invalid or outside of a permitted range.
EMSGSIZE	The specified message length, nbytes, exceeds the message size attribute of the message queue.
EPERM	Cannot be invoked from an Interrupt Service Routines.
ENOTRECOVERABLE	The message could not be enqueue (extension to POSIX).
EINTR	The operation was interrupted.

Wrapper over the parent method, automatically passing the message size.

See also

message_queue::send().

Definition at line 1803 of file os-mqueue.h.

    {
      return message_queue::send (reinterpret_cast<const char*> (msg),
                                  sizeof (value_type), mprio);
    }

References os::rtos::message_queue::send().

send() [2/2]

result_t os::rtos::message_queue::send ( const void *  msg, std::size_t  nbytes, priority_t  mprio = default_priority  )

inherited

Parameters

[in]	msg	The address of the message to enqueue.
[in]	nbytes	The length of the message. Must be not higher than the value used when creating the queue.
[in]	mprio	The message priority. The default is 0.

Return values

result::ok	The message was enqueued.
EINVAL	A parameter is invalid or outside of a permitted range.
EMSGSIZE	The specified message length, nbytes, exceeds the message size attribute of the message queue.
EPERM	Cannot be invoked from an Interrupt Service Routines.
ENOTRECOVERABLE	The message could not be enqueue (extension to POSIX).
EINTR	The operation was interrupted.

The send() function shall add the message pointed to by the argument msg to the message queue. The nbytes argument specifies the length of the message, in bytes, pointed to by msg. The value of nbytes shall be less than or equal to the msg_size_bytes parameter of the message queue object, or send() shall fail.

If the specified message queue is not full, send() shall behave as if the message is inserted into the message queue at the position indicated by the mprio argument. A message with a larger numeric value of mprio shall be inserted before messages with lower values of mprio. A message shall be inserted after other messages in the queue, if any, with equal mprio. The value of mprio shall be less than message_queue::max_priority.

If the specified message queue is full, send() shall block until space becomes available to enqueue the message, or until send() is cancelled/interrupted. If more than one thread is waiting to send when space becomes available in the message queue and the Priority Scheduling option is supported, then the thread of the highest priority that has been waiting the longest shall be unblocked to send its message. Otherwise, it is unspecified which waiting thread is unblocked.

POSIX compatibility

Inspired by mq_send() with O_NONBLOCK not set, from <mqueue.h> (IEEE Std 1003.1, 2013 Edition).

Warning

Cannot be invoked from Interrupt Service Routines.

Definition at line 929 of file os-mqueue.cpp.

    {
#if defined(OS_TRACE_RTOS_MQUEUE)
      trace::printf ("%s(%p,%d,%d) @%p %s\n", __func__, msg, nbytes, mprio,
                     this, name ());
#endif
 
      // Don't call this from interrupt handlers.
      os_assert_err (!interrupts::in_handler_mode (), EPERM);
      // Don't call this from critical regions.
      os_assert_err (!scheduler::locked (), EPERM);
 
      os_assert_err (msg != nullptr, EINVAL);
      os_assert_err (nbytes <= msg_size_bytes_, EMSGSIZE);
 
#if defined(OS_USE_RTOS_PORT_MESSAGE_QUEUE)
 
      return port::message_queue::send (this, msg, nbytes, mprio);
 
#else
 
      {
        // ----- Enter critical section ---------------------------------------
        interrupts::critical_section ics;
 
        if (internal_try_send_ (msg, nbytes, mprio))
          {
            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 (internal_try_send_ (msg, nbytes, mprio))
              {
                return result::ok;
              }
 
            // Add this thread to the message queue send waiting list.
            scheduler::internal_link_node (send_list_, node);
            // state::suspended set in above link().
            // ----- Exit critical section ------------------------------------
          }
 
          port::scheduler::reschedule ();
 
          // Remove the thread from the message queue send waiting list,
          // if not already removed by receive().
          scheduler::internal_unlink_node (node);
 
          if (crt_thread.interrupted ())
            {
#if defined(OS_TRACE_RTOS_MQUEUE)
              trace::printf ("%s(%p,%d,%d) EINTR @%p %s\n", __func__, msg,
                             nbytes, mprio, 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_err, os::trace::printf(), os::rtos::port::scheduler::reschedule(), and os::rtos::this_thread::thread().

Referenced by os::rtos::message_queue_typed< T, Allocator >::send(), and os::rtos::message_queue_inclusive< T, N >::send().

timed_receive() [1/2]

template<typename T , std::size_t N>

result_t os::rtos::message_queue_inclusive< T, N >::timed_receive ( value_type *  msg, clock::duration_t  timeout, priority_t *  mprio = nullptr  )

inline

Parameters

[out]	msg	The address where to store the dequeued message.
[in]	timeout	The timeout duration.
[out]	mprio	The address where to store the message priority. The default is nullptr.

Return values

result::ok	The message was received.
EINVAL	A parameter is invalid or outside of a permitted range.
EMSGSIZE	The specified message length, nbytes, is greater than the message size attribute of the message queue.
EPERM	Cannot be invoked from an Interrupt Service Routines.
ENOTRECOVERABLE	The message could not be dequeued (extension to POSIX).
EBADMSG	The implementation has detected a data corruption problem with the message.
EINTR	The operation was interrupted.
ETIMEDOUT	No message arrived on the queue before the specified timeout expired.

Wrapper over the parent method, automatically passing the message size.

See also

message_queue::timed_receive().

Definition at line 1883 of file os-mqueue.h.

    {
      return message_queue::timed_receive (
          reinterpret_cast<char*> (msg), sizeof (value_type), timeout, mprio);
    }

References os::rtos::message_queue::timed_receive().

timed_receive() [2/2]

result_t os::rtos::message_queue::timed_receive ( void *  msg, std::size_t  nbytes, clock::duration_t  timeout, priority_t *  mprio = nullptr  )

inherited

Parameters

[out]	msg	The address where to store the dequeued message.
[in]	nbytes	The size of the destination buffer. Must be lower than the value used when creating the queue.
[in]	timeout	The timeout duration.
[out]	mprio	The address where to store the message priority. The default is nullptr.

Return values

result::ok	The message was received.
EINVAL	A parameter is invalid or outside of a permitted range.
EMSGSIZE	The specified message length, nbytes, is greater than the message size attribute of the message queue.
EPERM	Cannot be invoked from an Interrupt Service Routines.
ENOTRECOVERABLE	The message could not be dequeued (extension to POSIX).
EBADMSG	The implementation has detected a data corruption problem with the message.
EINTR	The operation was interrupted.
ETIMEDOUT	No message arrived on the queue before the specified timeout expired.

The timed_receive() function shall receive the oldest of the highest priority message(s) from the message queue. If the size of the buffer in bytes, specified by the nbytes argument, is less than the msg_size_bytes attribute of the message queue, the function shall fail and return an error. Otherwise, the selected message shall be removed from the queue and copied to the buffer pointed to by the msg argument.

If the value of nbytes is greater than message_queue::max_size, the result is implementation-defined.

If the argument mprio is not nullptr, the priority of the selected message shall be stored in the location referenced by mprio.

If the message queue is empty, timed_receive() shall block until a message is enqueued on the message queue or until timed_receive() is cancelled/interrupted. If more than one thread is waiting to receive a message when a message arrives at an empty queue and the Priority Scheduling option is supported, then the thread of highest priority that has been waiting the longest shall be selected to receive the message. Otherwise, it is unspecified which waiting thread receives the message.

The timed_receive() function shall receive the oldest of the highest priority messages from the message queue as described for the receive() function. However, if no message exists on the queue to satisfy the receive, the wait for such a message 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.

Under no circumstance shall the operation fail with a timeout if a message can be removed from the message queue 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.

Compatible with POSIX mq_receive() with O_NONBLOCK set. http://pubs.opengroup.org/onlinepubs/9699919799/functions/mq_receive.html#

POSIX compatibility

Inspired by mq_timedreceive() with O_NONBLOCK not set, from <mqueue.h> (IEEE Std 1003.1, 2013 Edition).
Differences from the standard:

• the timeout is not expressed as an absolute time point, but as a relative number of timer ticks (by default, the SysTick clock for CMSIS).

Warning

Cannot be invoked from Interrupt Service Routines.

Definition at line 1484 of file os-mqueue.cpp.

    {
#if defined(OS_TRACE_RTOS_MQUEUE)
      trace::printf ("%s(%p,%u,%u) @%p %s\n", __func__, msg, nbytes, timeout,
                     this, name ());
#endif
 
      // Don't call this from interrupt handlers.
      os_assert_err (!interrupts::in_handler_mode (), EPERM);
      // Don't call this from critical regions.
      os_assert_err (!scheduler::locked (), EPERM);
 
      os_assert_err (msg != nullptr, EINVAL);
      os_assert_err (nbytes <= msg_size_bytes_, EMSGSIZE);
 
#if defined(OS_USE_RTOS_PORT_MESSAGE_QUEUE)
 
      return port::message_queue::timed_receive (this, msg, nbytes, timeout,
                                                 mprio);
 
#else
 
      // Extra test before entering the loop, with its inherent weight.
      // Trade size for speed.
      {
        // ----- Enter critical section ---------------------------------------
        interrupts::critical_section ics;
 
        if (internal_try_receive_ (msg, nbytes, mprio))
          {
            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 (internal_try_receive_ (msg, nbytes, mprio))
              {
                return result::ok;
              }
 
            // Add this thread to the message queue receive waiting list,
            // and the clock timeout list.
            scheduler::internal_link_node (receive_list_, node, clock_list,
                                           timeout_node);
            // state::suspended set in above link().
            // ----- Exit critical section ------------------------------------
          }
 
          port::scheduler::reschedule ();
 
          // Remove the thread from the semaphore waiting list,
          // if not already removed by send()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_MQUEUE)
              trace::printf ("%s(%p,%u,%u) EINTR @%p %s\n", __func__, msg,
                             nbytes, timeout, this, name ());
#endif
              return EINTR;
            }
 
          if (clock_->steady_now () >= timeout_timestamp)
            {
#if defined(OS_TRACE_RTOS_MQUEUE)
              trace::printf ("%s(%p,%u,%u) ETIMEDOUT @%p %s\n", __func__, msg,
                             nbytes, timeout, 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_err, os::trace::printf(), os::rtos::port::scheduler::reschedule(), and os::rtos::this_thread::thread().

Referenced by os::rtos::message_queue_typed< T, Allocator >::timed_receive(), and os::rtos::message_queue_inclusive< T, N >::timed_receive().

timed_send() [1/2]

template<typename T , std::size_t N>

result_t os::rtos::message_queue_inclusive< T, N >::timed_send ( const value_type *  msg, clock::duration_t  timeout, priority_t  mprio = default_priority  )

inline

Parameters

[in]	msg	The address of the message to enqueue.
[in]	timeout	The timeout duration.
[in]	mprio	The message priority. The default is 0.

Return values

result::ok	The message was enqueued.
EINVAL	A parameter is invalid or outside of a permitted range.
EMSGSIZE	The specified message length, nbytes, exceeds the message size attribute of the message queue.
EPERM	Cannot be invoked from an Interrupt Service Routines.
ETIMEDOUT	The timeout expired before the message could be added to the queue.
ENOTRECOVERABLE	The message could not be enqueue (extension to POSIX).
EINTR	The operation was interrupted.

Wrapper over the parent method, automatically passing the message size.

See also

message_queue::timed_send().

Definition at line 1835 of file os-mqueue.h.

    {
      return message_queue::timed_send (reinterpret_cast<const char*> (msg),
                                        sizeof (value_type), timeout, mprio);
    }

References os::rtos::message_queue::timed_send().

timed_send() [2/2]

result_t os::rtos::message_queue::timed_send ( const void *  msg, std::size_t  nbytes, clock::duration_t  timeout, priority_t  mprio = default_priority  )

inherited

Parameters

[in]	msg	The address of the message to enqueue.
[in]	nbytes	The length of the message. Must be not higher than the value used when creating the queue.
[in]	timeout	The timeout duration.
[in]	mprio	The message priority. The default is 0.

Return values

result::ok	The message was enqueued.
EINVAL	A parameter is invalid or outside of a permitted range.
EMSGSIZE	The specified message length, nbytes, exceeds the message size attribute of the message queue.
EPERM	Cannot be invoked from an Interrupt Service Routines.
ETIMEDOUT	The timeout expired before the message could be added to the queue.
ENOTRECOVERABLE	The message could not be enqueue (extension to POSIX).
EINTR	The operation was interrupted.

The timed_send() function shall add the message pointed to by the argument msg to the message queue. The nbytes argument specifies the length of the message, in bytes, pointed to by msg. The value of nbytes shall be less than or equal to the msg_size_bytes attribute of the message queue object, or timed_send() shall fail.

If the message queue is not full, timed_send() shall behave as if the message is inserted into the message queue at the position indicated by the mprio argument. A message with a larger numeric value of mprio shall be inserted before messages with lower values of mprio. A message shall be inserted after other messages in the queue, if any, with equal mprio. The value of mprio shall be less than message_queue::max_priority.

If the message queue is full, the wait for sufficient room in the queue 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()+timeout). The resolution of the timeout shall be the resolution of the clock on which it is based.

Under no circumstance shall the operation fail with a timeout if there is sufficient room in the queue to add the message 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.

POSIX compatibility

Inspired by mq_timedsend() with O_NONBLOCK not set, from <mqueue.h> (IEEE Std 1003.1, 2013 Edition).
Differences from the standard:

• the timeout is not expressed as an absolute time point, but as a relative number of timer ticks (by default, the SysTick clock for CMSIS).

Warning

Cannot be invoked from Interrupt Service Routines.

Definition at line 1129 of file os-mqueue.cpp.

    {
#if defined(OS_TRACE_RTOS_MQUEUE)
      trace::printf ("%s(%p,%u,%u,%u) @%p %s\n", __func__, msg, nbytes, mprio,
                     timeout, this, name ());
#endif
 
      // Don't call this from interrupt handlers.
      os_assert_err (!interrupts::in_handler_mode (), EPERM);
      // Don't call this from critical regions.
      os_assert_err (!scheduler::locked (), EPERM);
 
      os_assert_err (msg != nullptr, EINVAL);
      os_assert_err (nbytes <= msg_size_bytes_, EMSGSIZE);
 
#if defined(OS_USE_RTOS_PORT_MESSAGE_QUEUE)
 
      return port::message_queue::timed_send (this, msg, nbytes, timeout,
                                              mprio);
 
#else
 
      // Extra test before entering the loop, with its inherent weight.
      // Trade size for speed.
      {
        // ----- Enter critical section ---------------------------------------
        interrupts::critical_section ics;
 
        if (internal_try_send_ (msg, nbytes, mprio))
          {
            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 (internal_try_send_ (msg, nbytes, mprio))
              {
                return result::ok;
              }
 
            // Add this thread to the semaphore waiting list,
            // and the clock timeout list.
            scheduler::internal_link_node (send_list_, node, clock_list,
                                           timeout_node);
            // state::suspended set in above link().
            // ----- Exit critical section ------------------------------------
          }
 
          port::scheduler::reschedule ();
 
          // Remove the thread from the message queue send waiting list,
          // if not already removed by receive() 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_MQUEUE)
              trace::printf ("%s(%p,%u,%u,%u) EINTR @%p %s\n", __func__, msg,
                             nbytes, mprio, timeout, this, name ());
#endif
              return EINTR;
            }
 
          if (clock_->steady_now () >= timeout_timestamp)
            {
#if defined(OS_TRACE_RTOS_MQUEUE)
              trace::printf ("%s(%p,%u,%u,%u) ETIMEDOUT @%p %s\n", __func__,
                             msg, nbytes, mprio, timeout, 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_err, os::trace::printf(), os::rtos::port::scheduler::reschedule(), and os::rtos::this_thread::thread().

Referenced by os::rtos::message_queue_typed< T, Allocator >::timed_send(), and os::rtos::message_queue_inclusive< T, N >::timed_send().

try_receive() [1/2]

template<typename T , std::size_t N>

result_t os::rtos::message_queue_inclusive< T, N >::try_receive ( value_type *  msg, priority_t *  mprio = nullptr  )

inline

Parameters

[out]	msg	The address where to store the dequeued message. be lower than the value used when creating the queue.
[out]	mprio	The address where to store the message priority. The default is nullptr.

Return values

result::ok	The message was received.
EINVAL	A parameter is invalid or outside of a permitted range.
EMSGSIZE	The specified message length, nbytes, is greater than the message size attribute of the message queue.
ENOTRECOVERABLE	The message could not be dequeued (extension to POSIX).
EBADMSG	The implementation has detected a data corruption problem with the message.
EWOULDBLOCK	The specified message queue is empty.

Wrapper over the parent method, automatically passing the message size.

See also

message_queue::try_receive().

Definition at line 1867 of file os-mqueue.h.

    {
      return message_queue::try_receive (reinterpret_cast<char*> (msg),
                                         sizeof (value_type), mprio);
    }

References os::rtos::message_queue::try_receive().

try_receive() [2/2]

result_t os::rtos::message_queue::try_receive ( void *  msg, std::size_t  nbytes, priority_t *  mprio = nullptr  )

inherited

Parameters

[out]	msg	The address where to store the dequeued message.
[in]	nbytes	The size of the destination buffer. Must be lower than the value used when creating the queue.
[out]	mprio	The address where to store the message priority. The default is nullptr.

Return values

result::ok	The message was received.
EINVAL	A parameter is invalid or outside of a permitted range.
EMSGSIZE	The specified message length, nbytes, is greater than the message size attribute of the message queue.
ENOTRECOVERABLE	The message could not be dequeued (extension to POSIX).
EBADMSG	The implementation has detected a data corruption problem with the message.
EWOULDBLOCK	The specified message queue is empty.

The try_receive() function shall try to receive the oldest of the highest priority message(s) from the message queue. If the size of the buffer in bytes, specified by the nbytes argument, is less than the msg_size_bytes attribute of the message queue, the function shall fail and return an error. Otherwise, the selected message shall be removed from the queue and copied to the buffer pointed to by the msg argument.

If the value of nbytes is greater than message_queue::max_size, the result is implementation-defined.

If the argument mprio is not nullptr, the priority of the selected message shall be stored in the location referenced by mprio.

If the message queue is empty, no message shall be removed from the queue, and try_receive() shall return an error.

POSIX compatibility

Inspired by mq_receive() with O_NONBLOCK set, from <mqueue.h> (IEEE Std 1003.1, 2013 Edition).
Differences from the standard:

• for consistency reasons, EWOULDBLOCK is used, instead of EAGAIN

Note

Can be invoked from Interrupt Service Routines.

Definition at line 1383 of file os-mqueue.cpp.

    {
#if defined(OS_TRACE_RTOS_MQUEUE)
      trace::printf ("%s(%p,%u) @%p %s\n", __func__, msg, nbytes, this,
                     name ());
#endif
 
      os_assert_err (msg != nullptr, EINVAL);
      os_assert_err (nbytes <= msg_size_bytes_, EMSGSIZE);
 
#if defined(OS_USE_RTOS_PORT_MESSAGE_QUEUE)
 
      return port::message_queue::try_receive (this, msg, nbytes, mprio);
 
#else
 
      // Don't call this from high priority interrupts.
      assert (port::interrupts::is_priority_valid ());
 
      {
        // ----- Enter critical section ---------------------------------------
        interrupts::critical_section ics;
 
        if (internal_try_receive_ (msg, nbytes, mprio))
          {
            return result::ok;
          }
        else
          {
            return EWOULDBLOCK;
          }
        // ----- Exit critical section ----------------------------------------
      }
 
#endif
    }

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

Referenced by os::rtos::message_queue_typed< T, Allocator >::try_receive(), and os::rtos::message_queue_inclusive< T, N >::try_receive().

try_send() [1/2]

template<typename T , std::size_t N>

result_t os::rtos::message_queue_inclusive< T, N >::try_send ( const value_type *  msg, priority_t  mprio = default_priority  )

inline

Parameters

[in]	msg	The address of the message to enqueue. higher than the value used when creating the queue.
[in]	mprio	The message priority. The default is 0.

Return values

result::ok	The message was enqueued.
EWOULDBLOCK	The specified message queue is full.
EINVAL	A parameter is invalid or outside of a permitted range.
EMSGSIZE	The specified message length, nbytes, exceeds the message size attribute of the message queue.
ENOTRECOVERABLE	The message could not be enqueue (extension to POSIX).

Wrapper over the parent method, automatically passing the message size.

See also

message_queue::try_send().

Definition at line 1819 of file os-mqueue.h.

    {
      return message_queue::try_send (reinterpret_cast<const char*> (msg),
                                      sizeof (value_type), mprio);
    }

References os::rtos::message_queue::try_send().

try_send() [2/2]

result_t os::rtos::message_queue::try_send ( const void *  msg, std::size_t  nbytes, priority_t  mprio = default_priority  )

inherited

Parameters

[in]	msg	The address of the message to enqueue.
[in]	nbytes	The length of the message. Must be not higher than the value used when creating the queue.
[in]	mprio	The message priority. The default is 0.

Return values

result::ok	The message was enqueued.
EWOULDBLOCK	The specified message queue is full.
EINVAL	A parameter is invalid or outside of a permitted range.
EMSGSIZE	The specified message length, nbytes, exceeds the message size attribute of the message queue.
ENOTRECOVERABLE	The message could not be enqueue (extension to POSIX).

The try_send() function shall try to add the message pointed to by the argument msg to the message queue. The nbytes argument specifies the length of the message, in bytes, pointed to by msg. The value of nbytes shall be less than or equal to the msg_size_bytes parameter of the message queue object, or try_send() shall fail.

If the message queue is not full, try_send() shall behave as if the message is inserted into the message queue at the position indicated by the mprio argument. A message with a larger numeric value of mprio shall be inserted before messages with lower values of mprio. A message shall be inserted after other messages in the queue, if any, with equal mprio. The value of mprio shall be less than message_queue::max_priority.

If the message queue is full, the message shall not be queued and try_send() shall return an error.

POSIX compatibility

Inspired by mq_send() with O_NONBLOCK set, from <mqueue.h> (IEEE Std 1003.1, 2013 Edition).
Differences from the standard:

• for consistency reasons, EWOULDBLOCK is used, instead of EAGAIN

Note

Can be invoked from Interrupt Service Routines.

Definition at line 1042 of file os-mqueue.cpp.

    {
#if defined(OS_TRACE_RTOS_MQUEUE)
      trace::printf ("%s(%p,%u,%u) @%p %s\n", __func__, msg, nbytes, mprio,
                     this, name ());
#endif
 
      os_assert_err (msg != nullptr, EINVAL);
      os_assert_err (nbytes <= msg_size_bytes_, EMSGSIZE);
 
#if defined(OS_USE_RTOS_PORT_MESSAGE_QUEUE)
 
      return port::message_queue::try_send (this, msg, nbytes, mprio);
 
#else
      // Don't call this from high priority interrupts.
      assert (port::interrupts::is_priority_valid ());
 
      {
        // ----- Enter critical section ---------------------------------------
        interrupts::critical_section ics;
 
        if (internal_try_send_ (msg, nbytes, mprio))
          {
            return result::ok;
          }
        else
          {
            return EWOULDBLOCK;
          }
        // ----- Exit critical section ----------------------------------------
      }
 
#endif
    }

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

Referenced by os::rtos::message_queue_typed< T, Allocator >::try_send(), and os::rtos::message_queue_inclusive< T, N >::try_send().

Member Data Documentation

msgs

template<typename T , std::size_t N>

const std::size_t os::rtos::message_queue_inclusive< T, N >::msgs = N

static

Definition at line 1053 of file os-mqueue.h.

Referenced by os::rtos::message_queue_inclusive< T, N >::message_queue_inclusive().

---

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

• os-mqueue.h