RTEMS
Files | Classes | Macros | Typedefs | Enumerations | Functions
Message Queue Handler

Message Queue Handler. More...

Files

file  coremsg.h
 Constants and Structures Associated with the Message Queue Handler.
 
file  coremsgbuffer.h
 This header file defines the buffer data structure used by the Message Queue Handler.
 
file  coremsgimpl.h
 Inlined Routines in the Core Message Handler.
 
file  coremsg.c
 Initialize a Message Queue.
 
file  coremsgbroadcast.c
 Broadcast a Message to the Message Queue.
 
file  coremsgclose.c
 Close a Message Queue.
 
file  coremsgflush.c
 Flush Messages Routine.
 
file  coremsginsert.c
 Insert a Message into the Message Queue.
 
file  coremsgseize.c
 Seize a Message from the Message Queue.
 
file  coremsgsubmit.c
 CORE Message Queue Submit.
 
file  coremsgwkspace.c
 This source file contains the implementation of _CORE_message_queue_Workspace_allocate().
 

Classes

struct  CORE_message_queue_Control
 Control block used to manage each message queue. More...
 
struct  CORE_message_queue_Buffer
 The structure is used to organize message buffers of a message queue. More...
 

Macros

#define RTEMS_SCORE_COREMSG_ENABLE_BLOCKING_SEND
 
#define RTEMS_SCORE_COREMSG_ENABLE_MESSAGE_PRIORITY
 
#define CORE_MESSAGE_QUEUE_SEND_REQUEST   INT_MAX
 Used when appending messages onto a message queue. More...
 
#define CORE_MESSAGE_QUEUE_URGENT_REQUEST   INT_MIN
 Used when prepending messages onto a message queue. More...
 
#define _CORE_message_queue_Set_notify(the_message_queue, the_handler)   do { } while ( 0 )
 Initializes notification information. More...
 

Typedefs

typedef struct CORE_message_queue_Control CORE_message_queue_Control
 
typedef int CORE_message_queue_Submit_types
 The modes in which a message may be submitted to a message queue. More...
 
typedef void *(* CORE_message_queue_Allocate_buffers) (CORE_message_queue_Control *the_message_queue, size_t size, const void *arg)
 This handler shall allocate the message buffer storage area for a message queue. More...
 

Enumerations

enum  CORE_message_queue_Disciplines { CORE_MESSAGE_QUEUE_DISCIPLINES_FIFO, CORE_MESSAGE_QUEUE_DISCIPLINES_PRIORITY }
 The possible blocking disciplines for a message queue. More...
 

Functions

void * _CORE_message_queue_Workspace_allocate (CORE_message_queue_Control *the_message_queue, size_t size, const void *arg)
 This handler allocates the message buffer storage area for a message queue from the RTEMS Workspace. More...
 
Status_Control _CORE_message_queue_Initialize (CORE_message_queue_Control *the_message_queue, CORE_message_queue_Disciplines discipline, uint32_t maximum_pending_messages, size_t maximum_message_size, CORE_message_queue_Allocate_buffers allocate_buffers, const void *arg)
 Initializes a message queue. More...
 
void _CORE_message_queue_Close (CORE_message_queue_Control *the_message_queue, Thread_queue_Context *queue_context)
 Closes a message queue. More...
 
uint32_t _CORE_message_queue_Flush (CORE_message_queue_Control *the_message_queue, Thread_queue_Context *queue_context)
 Flushes pending messages. More...
 
Status_Control _CORE_message_queue_Broadcast (CORE_message_queue_Control *the_message_queue, const void *buffer, size_t size, uint32_t *count, Thread_queue_Context *queue_context)
 Broadcasts a message to the message queue. More...
 
Status_Control _CORE_message_queue_Submit (CORE_message_queue_Control *the_message_queue, Thread_Control *executing, const void *buffer, size_t size, CORE_message_queue_Submit_types submit_type, bool wait, Thread_queue_Context *queue_context)
 Submits a message to the message queue. More...
 
Status_Control _CORE_message_queue_Seize (CORE_message_queue_Control *the_message_queue, Thread_Control *executing, void *buffer, size_t *size_p, bool wait, Thread_queue_Context *queue_context)
 Seizes a message from the message queue. More...
 
void _CORE_message_queue_Insert_message (CORE_message_queue_Control *the_message_queue, CORE_message_queue_Buffer *the_message, const void *content_source, size_t content_size, CORE_message_queue_Submit_types submit_type)
 Inserts a message into the message queue. More...
 
static __inline__ Status_Control _CORE_message_queue_Send (CORE_message_queue_Control *the_message_queue, const void *buffer, size_t size, bool wait, Thread_queue_Context *queue_context)
 Sends a message to the message queue. More...
 
static __inline__ Status_Control _CORE_message_queue_Urgent (CORE_message_queue_Control *the_message_queue, const void *buffer, size_t size, bool wait, Thread_queue_Context *queue_context)
 Sends an urgent message to the message queue. More...
 
static __inline__ void _CORE_message_queue_Acquire (CORE_message_queue_Control *the_message_queue, Thread_queue_Context *queue_context)
 Acquires the message queue. More...
 
static __inline__ void _CORE_message_queue_Acquire_critical (CORE_message_queue_Control *the_message_queue, Thread_queue_Context *queue_context)
 Acquires the message queue critical. More...
 
static __inline__ void _CORE_message_queue_Release (CORE_message_queue_Control *the_message_queue, Thread_queue_Context *queue_context)
 Releases the message queue. More...
 
static __inline__ void _CORE_message_queue_Copy_buffer (const void *source, void *destination, size_t size)
 Copies the source message buffer to the destination message buffer. More...
 
static __inline__ CORE_message_queue_Buffer_CORE_message_queue_Allocate_message_buffer (CORE_message_queue_Control *the_message_queue)
 Allocates a message buffer from the inactive message buffer chain. More...
 
static __inline__ void _CORE_message_queue_Free_message_buffer (CORE_message_queue_Control *the_message_queue, CORE_message_queue_Buffer *the_message)
 Frees a message buffer to inactive message buffer chain. More...
 
static __inline__ int _CORE_message_queue_Get_message_priority (const CORE_message_queue_Buffer *the_message)
 Gets message priority. More...
 
static __inline__ CORE_message_queue_Buffer_CORE_message_queue_Get_pending_message (CORE_message_queue_Control *the_message_queue)
 Gets first message of message queue and removes it. More...
 
static __inline__ Thread_Control_CORE_message_queue_Dequeue_receiver (CORE_message_queue_Control *the_message_queue, const void *buffer, size_t size, CORE_message_queue_Submit_types submit_type, Thread_queue_Context *queue_context)
 Gets the first locked thread waiting to receive and dequeues it. More...
 

Detailed Description

Message Queue Handler.

This handler encapsulates functionality which provides the foundation Message Queue services used in all of the APIs supported by RTEMS.

Macro Definition Documentation

◆ _CORE_message_queue_Set_notify

#define _CORE_message_queue_Set_notify (   the_message_queue,
  the_handler 
)    do { } while ( 0 )

Initializes notification information.

This routine initializes the notification information for the_message_queue.

Parameters
[out]the_message_queueThe message queue to initialize the notification information.
[out]the_handlerThe notification information for the message queue.

Definition at line 593 of file coremsgimpl.h.

◆ CORE_MESSAGE_QUEUE_SEND_REQUEST

#define CORE_MESSAGE_QUEUE_SEND_REQUEST   INT_MAX

Used when appending messages onto a message queue.

This is the priority constant used when appending messages onto a message queue.

Definition at line 49 of file coremsgimpl.h.

◆ CORE_MESSAGE_QUEUE_URGENT_REQUEST

#define CORE_MESSAGE_QUEUE_URGENT_REQUEST   INT_MIN

Used when prepending messages onto a message queue.

This is the priority constant used when prepending messages onto a message queue.

Definition at line 57 of file coremsgimpl.h.

◆ RTEMS_SCORE_COREMSG_ENABLE_BLOCKING_SEND

#define RTEMS_SCORE_COREMSG_ENABLE_BLOCKING_SEND

This macro is defined when an API is enabled that requires the Message Queue Handler include support for blocking send operations.

Definition at line 59 of file coremsg.h.

◆ RTEMS_SCORE_COREMSG_ENABLE_MESSAGE_PRIORITY

#define RTEMS_SCORE_COREMSG_ENABLE_MESSAGE_PRIORITY

This define enables the support for priority based enqueuing of messages in the Message Queue Handler.

Definition at line 58 of file coremsgbuffer.h.

Typedef Documentation

◆ CORE_message_queue_Allocate_buffers

typedef void*( * CORE_message_queue_Allocate_buffers) (CORE_message_queue_Control *the_message_queue, size_t size, const void *arg)

This handler shall allocate the message buffer storage area for a message queue.

The handler shall set the CORE_message_queue_Control::free_message_buffers member.

Parameters
[out]the_message_queueis the message queue control.
sizeis the message buffer storage area size to allocate.
argis the handler argument.
Return values
NULLThe allocation failed.
Returns
Otherwise the pointer to the allocated message buffer storage area begin shall be returned.

Definition at line 89 of file coremsgimpl.h.

◆ CORE_message_queue_Submit_types

The modes in which a message may be submitted to a message queue.

The following type details the modes in which a message may be submitted to a message queue. The message may be posted in a send or urgent fashion.

Note
All other values are message priorities. Numerically smaller priorities indicate higher priority messages.

Definition at line 69 of file coremsgimpl.h.

Enumeration Type Documentation

◆ CORE_message_queue_Disciplines

The possible blocking disciplines for a message queue.

This enumerated types defines the possible blocking disciplines for a message queue.

Enumerator
CORE_MESSAGE_QUEUE_DISCIPLINES_FIFO 

This value indicates that blocking tasks are in FIFO order.

CORE_MESSAGE_QUEUE_DISCIPLINES_PRIORITY 

This value indicates that blocking tasks are in priority order.

Definition at line 69 of file coremsg.h.

Function Documentation

◆ _CORE_message_queue_Acquire()

static __inline__ void _CORE_message_queue_Acquire ( CORE_message_queue_Control the_message_queue,
Thread_queue_Context queue_context 
)
static

Acquires the message queue.

Parameters
[in,out]the_message_queueRhe message queue to acquire.
queue_contextThe thread queue context.

Definition at line 418 of file coremsgimpl.h.

◆ _CORE_message_queue_Acquire_critical()

static __inline__ void _CORE_message_queue_Acquire_critical ( CORE_message_queue_Control the_message_queue,
Thread_queue_Context queue_context 
)
static

Acquires the message queue critical.

Parameters
[in,out]the_message_queueThe message queue to acquire critical.
queue_contextThe thread queue context.

Definition at line 432 of file coremsgimpl.h.

◆ _CORE_message_queue_Allocate_message_buffer()

static __inline__ CORE_message_queue_Buffer* _CORE_message_queue_Allocate_message_buffer ( CORE_message_queue_Control the_message_queue)
static

Allocates a message buffer from the inactive message buffer chain.

This function allocates a message buffer from the inactive message buffer chain.

Parameters
the_message_queueThe message queue to operate upon.
Return values
pointerThe allocated message buffer.
NULLThe inactive message buffer chain is empty.

Definition at line 485 of file coremsgimpl.h.

◆ _CORE_message_queue_Broadcast()

Status_Control _CORE_message_queue_Broadcast ( CORE_message_queue_Control the_message_queue,
const void *  buffer,
size_t  size,
uint32_t *  count,
Thread_queue_Context queue_context 
)

Broadcasts a message to the message queue.

This package is the implementation of the CORE Message Queue Handler. This core object provides task synchronization and communication functions via messages passed to queue objects.

This function sends a message for every thread waiting on the queue and returns the number of threads made ready by the message.

Parameters
[in,out]the_message_queueThe message queue to operate upon.
bufferThe starting address of the message to broadcast.
sizeThe size of the message being broadcast.
[out]countThe variable that will contain the number of tasks that are sent this message.
queue_contextThe thread queue context used for _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical().
Return values
STATUS_SUCCESSFULThe message was successfully broadcast.
STATUS_MESSAGE_INVALID_SIZEThe message size was too big.

Definition at line 24 of file coremsgbroadcast.c.

◆ _CORE_message_queue_Close()

void _CORE_message_queue_Close ( CORE_message_queue_Control the_message_queue,
Thread_queue_Context queue_context 
)

Closes a message queue.

This package is the implementation of the CORE Message Queue Handler. This core object provides task synchronization and communication functions via messages passed to queue objects.

This function closes a message by returning all allocated space and flushing the_message_queue's task wait queue.

Parameters
[in,out]the_message_queueThe message queue to close.
[in,out]queue_contextThe thread queue context used for _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical().

Definition at line 34 of file coremsgclose.c.

◆ _CORE_message_queue_Copy_buffer()

static __inline__ void _CORE_message_queue_Copy_buffer ( const void *  source,
void *  destination,
size_t  size 
)
static

Copies the source message buffer to the destination message buffer.

This routine copies the contents of the source message buffer to the destination message buffer.

Parameters
sourceThe source message buffer to be copied.
[out]destinationThe destination messag buffer to copy the source to.
sizeThe size of the source buffer.

Definition at line 464 of file coremsgimpl.h.

◆ _CORE_message_queue_Dequeue_receiver()

static __inline__ Thread_Control* _CORE_message_queue_Dequeue_receiver ( CORE_message_queue_Control the_message_queue,
const void *  buffer,
size_t  size,
CORE_message_queue_Submit_types  submit_type,
Thread_queue_Context queue_context 
)
static

Gets the first locked thread waiting to receive and dequeues it.

This method dequeues the first locked thread waiting to receive a message, dequeues it and returns the corresponding Thread_Control.

Parameters
[in,out]the_message_queueThe message queue to operate upon.
bufferThe buffer that is copied to the threads mutable_object.
sizeThe size of the buffer.
submit_typeIndicates whether the thread should be willing to block in the future.
queue_contextThe thread queue context.
Return values
threadThe Thread_Control for the first locked thread, if there is a locked thread.
NULLThere are pending messages or no thread waiting to receive.

Definition at line 612 of file coremsgimpl.h.

◆ _CORE_message_queue_Flush()

uint32_t _CORE_message_queue_Flush ( CORE_message_queue_Control the_message_queue,
Thread_queue_Context queue_context 
)

Flushes pending messages.

This package is the implementation of the CORE Message Queue Handler. This core object provides task synchronization and communication functions via messages passed to queue objects.

This function flushes the_message_queue's pending message queue. The number of messages flushed from the queue is returned.

Parameters
[in,out]the_message_queueThe message queue to flush.
queue_contextThe thread queue context with interrupts disabled.
Returns
This method returns the number of message pending messages flushed.

Definition at line 24 of file coremsgflush.c.

◆ _CORE_message_queue_Free_message_buffer()

static __inline__ void _CORE_message_queue_Free_message_buffer ( CORE_message_queue_Control the_message_queue,
CORE_message_queue_Buffer the_message 
)
static

Frees a message buffer to inactive message buffer chain.

This routine frees a message buffer to the inactive message buffer chain.

Parameters
[in,out]the_message_queueThe message queue to free the message buffer to.
[out]the_messageThe message to be freed.

Definition at line 502 of file coremsgimpl.h.

◆ _CORE_message_queue_Get_message_priority()

static __inline__ int _CORE_message_queue_Get_message_priority ( const CORE_message_queue_Buffer the_message)
static

Gets message priority.

This function returns the priority of the_message.

Parameters
the_messageThe message to obtain the priority from.
Return values
priorityThe priority of this message.
0Message priority is disabled.
Note
It encapsulates the optional behavior that message priority is disabled if no API requires it.

Definition at line 523 of file coremsgimpl.h.

◆ _CORE_message_queue_Get_pending_message()

static __inline__ CORE_message_queue_Buffer* _CORE_message_queue_Get_pending_message ( CORE_message_queue_Control the_message_queue)
static

Gets first message of message queue and removes it.

This function removes the first message from the_message_queue and returns a pointer to it.

Parameters
[in,out]the_message_queueThe message queue to get the first message from.
Return values
pointerThe first message if the message queue is not empty.
NULLThe message queue is empty.

Definition at line 546 of file coremsgimpl.h.

◆ _CORE_message_queue_Initialize()

Status_Control _CORE_message_queue_Initialize ( CORE_message_queue_Control the_message_queue,
CORE_message_queue_Disciplines  discipline,
uint32_t  maximum_pending_messages,
size_t  maximum_message_size,
CORE_message_queue_Allocate_buffers  allocate_buffers,
const void *  arg 
)

Initializes a message queue.

Parameters
[out]the_message_queueis the message queue to initialize.
disciplineis the blocking discipline for the message queue.
maximum_pending_messagesis the maximum number of messages that will be allowed to be pending at any given time.
maximum_message_sizeis the size of the largest message that may be sent to this message queue instance.
allocate_buffersis the message buffer storage area allocation handler.
argis the message buffer storage area allocation handler argument.
Return values
STATUS_SUCCESSFULThe message queue was initialized.
STATUS_MESSAGE_QUEUE_INVALID_SIZECalculations with the maximum pending messages or maximum message size produced an integer overflow.
STATUS_MESSAGE_QUEUE_NO_MEMORYThe message buffer storage area allocation failed.

Definition at line 33 of file coremsg.c.

◆ _CORE_message_queue_Insert_message()

void _CORE_message_queue_Insert_message ( CORE_message_queue_Control the_message_queue,
CORE_message_queue_Buffer the_message,
const void *  content_source,
size_t  content_size,
CORE_message_queue_Submit_types  submit_type 
)

Inserts a message into the message queue.

Copies the specified content into the message storage space and then inserts the message into the message queue according to the submit type.

Parameters
[in,out]the_message_queueThe message queue to insert a message in.
[in,out]the_messageThe message to insert in the message queue.
content_sourceThe message content source.
content_sizeThe message content size in bytes.
submit_typeDetermines whether the message is prepended, appended, or enqueued in priority order.

Definition at line 41 of file coremsginsert.c.

◆ _CORE_message_queue_Release()

static __inline__ void _CORE_message_queue_Release ( CORE_message_queue_Control the_message_queue,
Thread_queue_Context queue_context 
)
static

Releases the message queue.

Parameters
[in,out]the_message_queueThe message queue to release.
queue_contextThe thread queue context.

Definition at line 446 of file coremsgimpl.h.

◆ _CORE_message_queue_Seize()

Status_Control _CORE_message_queue_Seize ( CORE_message_queue_Control the_message_queue,
Thread_Control executing,
void *  buffer,
size_t *  size_p,
bool  wait,
Thread_queue_Context queue_context 
)

Seizes a message from the message queue.

This package is the implementation of the CORE Message Queue Handler. This core object provides task synchronization and communication functions via messages passed to queue objects.

This kernel routine dequeues a message, copies the message buffer to a given destination buffer, and frees the message buffer to the inactive message pool. The thread will be blocked if wait is true, otherwise an error will be given to the thread if no messages are available.

Parameters
[in,out]the_message_queueThe message queue to seize a message from.
executingThe executing thread.
[out]bufferThe starting address of the message buffer to to be filled in with a message.
[out]size_pThe size of the buffer, indicates the maximum size message that the caller can receive.
waitIndicates whether the calling thread is willing to block if the message queue is empty.
queue_contextThe thread queue context used for _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical().
Return values
STATUS_SUCCESSFULThe message was successfully seized from the message queue.
STATUS_UNSATISFIEDWait was set to false and there is currently no pending message.
STATUS_TIMEOUTA timeout occured.
Note
Returns message priority via return area in TCB.
  • INTERRUPT LATENCY:
    • available
    • wait

Definition at line 27 of file coremsgseize.c.

◆ _CORE_message_queue_Send()

static __inline__ Status_Control _CORE_message_queue_Send ( CORE_message_queue_Control the_message_queue,
const void *  buffer,
size_t  size,
bool  wait,
Thread_queue_Context queue_context 
)
static

Sends a message to the message queue.

Parameters
[in,out]the_message_queueThe message queue to send a message to.
bufferThe starting address of the message to send.
sizeisThe size of the message being send.
waitIndicates whether the calling thread is willing to block if the message queue is full.
queue_contextThe thread queue context used for _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical().
Return values
STATUS_SUCCESSFULThe message was successfully submitted to the message queue.
STATUS_MESSAGE_INVALID_SIZEThe message size was too big.
STATUS_TOO_MANYNo message buffers were available.
STATUS_MESSAGE_QUEUE_WAIT_IN_ISRThe caller is in an ISR, do not block!
STATUS_TIMEOUTA timeout occured.

Definition at line 357 of file coremsgimpl.h.

◆ _CORE_message_queue_Submit()

Status_Control _CORE_message_queue_Submit ( CORE_message_queue_Control the_message_queue,
Thread_Control executing,
const void *  buffer,
size_t  size,
CORE_message_queue_Submit_types  submit_type,
bool  wait,
Thread_queue_Context queue_context 
)

Submits a message to the message queue.

This routine implements the send and urgent message functions. It processes a message that is to be submitted to the designated message queue. The message will either be processed as a send message which it will be inserted at the rear of the queue or it will be processed as an urgent message which will be inserted at the front of the queue.

Parameters
[in,out]the_message_queueThe message queue to operate upon.
executingThe executing thread.
bufferThe starting address of the message to send.
sizeThe size of the message being send.
submit_typeDetermines whether the message is prepended, appended, or enqueued in priority order.
waitIndicates whether the calling thread is willing to block if the message queue is full.
queue_contextThe thread queue context used for _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical().
Return values
STATUS_SUCCESSFULThe message was successfully submitted to the message queue.
STATUS_MESSAGE_INVALID_SIZEThe message size was too big.
STATUS_TOO_MANYNo message buffers were available.
STATUS_MESSAGE_QUEUE_WAIT_IN_ISRThe caller is in an ISR, do not block!
STATUS_TIMEOUTA timeout occured.

Definition at line 29 of file coremsgsubmit.c.

◆ _CORE_message_queue_Urgent()

static __inline__ Status_Control _CORE_message_queue_Urgent ( CORE_message_queue_Control the_message_queue,
const void *  buffer,
size_t  size,
bool  wait,
Thread_queue_Context queue_context 
)
static

Sends an urgent message to the message queue.

Parameters
[in,out]the_message_queueThe message queue to send an urgent message to.
bufferThe starting address of the message to send.
sizeisThe size of the message being send.
waitIndicates whether the calling thread is willing to block if the message queue is full.
queue_contextThe thread queue context used for _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical().
Return values
STATUS_SUCCESSFULThe message was successfully submitted to the message queue.
STATUS_MESSAGE_INVALID_SIZEThe message size was too big.
STATUS_TOO_MANYNo message buffers were available.
STATUS_MESSAGE_QUEUE_WAIT_IN_ISRThe caller is in an ISR, do not block!
STATUS_TIMEOUTA timeout occured.

Definition at line 393 of file coremsgimpl.h.

◆ _CORE_message_queue_Workspace_allocate()

void* _CORE_message_queue_Workspace_allocate ( CORE_message_queue_Control the_message_queue,
size_t  size,
const void *  arg 
)

This handler allocates the message buffer storage area for a message queue from the RTEMS Workspace.

The handler sets the CORE_message_queue_Control::free_message_buffers to _Workspace_Free().

Parameters
[out]the_message_queueis the message queue control.
sizeis the message buffer storage area size to allocate.
argis the unused handler argument.
Return values
NULLThe allocation failed.
Returns
Otherwise the pointer to the allocated message buffer storage area begin is returned.

Definition at line 44 of file coremsgwkspace.c.