RTEMS  5.0.0
Files | Data Structures | Macros | Typedefs | Enumerations | Functions
Message Queue Handler

Files

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  coremsgflushwait.c
 Flush Waiting Threads.
 
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.
 

Data Structures

struct  CORE_message_queue_Buffer
 Data types needed to manipulate the contents of message buffers. More...
 
struct  CORE_message_queue_Buffer_control
 The organization of a message buffer. More...
 
struct  CORE_message_queue_Control
 Control block used to manage each message queue. More...
 

Macros

#define RTEMS_SCORE_COREMSG_ENABLE_MESSAGE_PRIORITY
 
#define RTEMS_SCORE_COREMSG_ENABLE_BLOCKING_SEND
 
#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 )
 

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

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

bool _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)
 Initialize a message queue. More...
 
void _CORE_message_queue_Close (CORE_message_queue_Control *the_message_queue, Thread_queue_Context *queue_context)
 Close a message queue. More...
 
uint32_t _CORE_message_queue_Flush (CORE_message_queue_Control *the_message_queue, Thread_queue_Context *queue_context)
 Flush 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)
 Broadcast 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)
 Submit 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)
 Size a message from the message queue. More...
 
void _CORE_message_queue_Insert_message (CORE_message_queue_Control *the_message_queue, CORE_message_queue_Buffer_control *the_message, const void *content_source, size_t content_size, CORE_message_queue_Submit_types submit_type)
 Insert a message into the message queue. More...
 
RTEMS_INLINE_ROUTINE 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)
 
RTEMS_INLINE_ROUTINE 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)
 
RTEMS_INLINE_ROUTINE void _CORE_message_queue_Acquire (CORE_message_queue_Control *the_message_queue, Thread_queue_Context *queue_context)
 
RTEMS_INLINE_ROUTINE void _CORE_message_queue_Acquire_critical (CORE_message_queue_Control *the_message_queue, Thread_queue_Context *queue_context)
 
RTEMS_INLINE_ROUTINE void _CORE_message_queue_Release (CORE_message_queue_Control *the_message_queue, Thread_queue_Context *queue_context)
 
RTEMS_INLINE_ROUTINE void _CORE_message_queue_Copy_buffer (const void *source, void *destination, size_t size)
 
RTEMS_INLINE_ROUTINE CORE_message_queue_Buffer_control_CORE_message_queue_Allocate_message_buffer (CORE_message_queue_Control *the_message_queue)
 
RTEMS_INLINE_ROUTINE void _CORE_message_queue_Free_message_buffer (CORE_message_queue_Control *the_message_queue, CORE_message_queue_Buffer_control *the_message)
 
RTEMS_INLINE_ROUTINE int _CORE_message_queue_Get_message_priority (const CORE_message_queue_Buffer_control *the_message)
 
RTEMS_INLINE_ROUTINE CORE_message_queue_Buffer_control_CORE_message_queue_Get_pending_message (CORE_message_queue_Control *the_message_queue)
 
RTEMS_INLINE_ROUTINE 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)
 

Detailed Description

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 )

This routine initializes the notification information for the_message_queue.

◆ 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.

◆ 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.

◆ 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.

◆ RTEMS_SCORE_COREMSG_ENABLE_MESSAGE_PRIORITY

#define RTEMS_SCORE_COREMSG_ENABLE_MESSAGE_PRIORITY

This macro is defined when an API is enabled that requires that the Message Queue Handler include support for priority based enqueuing of messages.

Typedef Documentation

◆ 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.

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.

Function Documentation

◆ _CORE_message_queue_Allocate_message_buffer()

RTEMS_INLINE_ROUTINE CORE_message_queue_Buffer_control* _CORE_message_queue_Allocate_message_buffer ( CORE_message_queue_Control the_message_queue)

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

◆ _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 
)

Broadcast 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]the_message_queuepoints to the message queue
[in]bufferis the starting address of the message to broadcast
[in]sizeis the size of the message being broadcast
[out]countpoints to the variable that will contain the number of tasks that are sent this message
[in]queue_contextThe thread queue context used for _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical().
Return values

◆ _CORE_message_queue_Close()

void _CORE_message_queue_Close ( CORE_message_queue_Control the_message_queue,
Thread_queue_Context queue_context 
)

Close 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]the_message_queuepoints to the message queue to close
[in]queue_contextThe thread queue context used for _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical().

◆ _CORE_message_queue_Copy_buffer()

RTEMS_INLINE_ROUTINE void _CORE_message_queue_Copy_buffer ( const void *  source,
void *  destination,
size_t  size 
)

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

◆ _CORE_message_queue_Flush()

uint32_t _CORE_message_queue_Flush ( CORE_message_queue_Control the_message_queue,
Thread_queue_Context queue_context 
)

Flush 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]the_message_queuepoints to the message queue to flush
[in]queue_contextThe thread queue context with interrupts disabled.
Return values
Thismethod returns the number of message pending messages flushed.

◆ _CORE_message_queue_Free_message_buffer()

RTEMS_INLINE_ROUTINE void _CORE_message_queue_Free_message_buffer ( CORE_message_queue_Control the_message_queue,
CORE_message_queue_Buffer_control the_message 
)

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

◆ _CORE_message_queue_Get_message_priority()

RTEMS_INLINE_ROUTINE int _CORE_message_queue_Get_message_priority ( const CORE_message_queue_Buffer_control the_message)

This function returns the priority of the_message.

Note
It encapsulates the optional behavior that message priority is disabled if no API requires it.

◆ _CORE_message_queue_Get_pending_message()

RTEMS_INLINE_ROUTINE CORE_message_queue_Buffer_control* _CORE_message_queue_Get_pending_message ( CORE_message_queue_Control the_message_queue)

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

◆ _CORE_message_queue_Initialize()

bool _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 
)

Initialize 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 routine initializes the_message_queue based on the parameters passed.

Parameters
[in]the_message_queuepoints to the message queue to initialize
[in]disciplinethe blocking discipline
[in]maximum_pending_messagesis the maximum number of messages that will be allowed to pend at any given time
[in]maximum_message_sizeis the size of largest message that may be sent to this message queue instance
Return values
trueif the message queue can be initialized. In general, false will only be returned if memory for the pending messages cannot be allocated.

◆ _CORE_message_queue_Insert_message()

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

Insert 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]the_message_queuepoints to the message queue
[in]the_messageis the message to enqueue
[in]content_sourcethe message content source
[in]content_sizethe message content size in bytes
[in]submit_typedetermines whether the message is prepended, appended, or enqueued in priority order.

◆ _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 
)

Size 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]the_message_queuepoints to the message queue
[in]bufferis the starting address of the message buffer to to be filled in with a message
[in]size_pis a pointer to the size of the buffer and indicates the maximum size message that the caller can receive.
[in]waitindicates whether the calling thread is willing to block if the message queue is empty.
[in]queue_contextThe thread queue context used for _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical().
Return values
indicationof the successful completion or reason for failure. On success, the location pointed to size_p will contain the size of the received message.
Note
Returns message priority via return area in TCB.
  • INTERRUPT LATENCY:
    • available
    • wait

◆ _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 
)

Submit 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]the_message_queuepoints to the message queue
[in]bufferis the starting address of the message to send
[in]sizeis the size of the message being send
[in]submit_typedetermines whether the message is prepended, appended, or enqueued in priority order.
[in]waitindicates whether the calling thread is willing to block if the message queue is full.
[in]queue_contextThe thread queue context used for _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical().
Return values
indicationof the successful completion or reason for failure