RTEMS
|
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... | |
Message Queue Handler.
This handler encapsulates functionality which provides the foundation Message Queue services used in all of the APIs supported by RTEMS.
#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.
[out] | the_message_queue | The message queue to initialize the notification information. |
[out] | the_handler | The notification information for the message queue. |
Definition at line 593 of file coremsgimpl.h.
#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.
#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.
#define RTEMS_SCORE_COREMSG_ENABLE_BLOCKING_SEND |
#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 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.
[out] | the_message_queue | is the message queue control. |
size | is the message buffer storage area size to allocate. | |
arg | is the handler argument. |
NULL | The allocation failed. |
Definition at line 89 of file coremsgimpl.h.
typedef int 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.
Definition at line 69 of file coremsgimpl.h.
The possible blocking disciplines for a message queue.
This enumerated types defines the possible blocking disciplines for a message queue.
|
static |
Acquires the message queue.
[in,out] | the_message_queue | Rhe message queue to acquire. |
queue_context | The thread queue context. |
Definition at line 418 of file coremsgimpl.h.
|
static |
Acquires the message queue critical.
[in,out] | the_message_queue | The message queue to acquire critical. |
queue_context | The thread queue context. |
Definition at line 432 of file coremsgimpl.h.
|
static |
Allocates a message buffer from the inactive message buffer chain.
This function allocates a message buffer from the inactive message buffer chain.
the_message_queue | The message queue to operate upon. |
pointer | The allocated message buffer. |
NULL | The inactive message buffer chain is empty. |
Definition at line 485 of file coremsgimpl.h.
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.
[in,out] | the_message_queue | The message queue to operate upon. |
buffer | The starting address of the message to broadcast. | |
size | The size of the message being broadcast. | |
[out] | count | The variable that will contain the number of tasks that are sent this message. |
queue_context | The thread queue context used for _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical(). |
STATUS_SUCCESSFUL | The message was successfully broadcast. |
STATUS_MESSAGE_INVALID_SIZE | The message size was too big. |
Definition at line 24 of file coremsgbroadcast.c.
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.
[in,out] | the_message_queue | The message queue to close. |
[in,out] | queue_context | The thread queue context used for _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical(). |
Definition at line 34 of file coremsgclose.c.
|
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.
source | The source message buffer to be copied. | |
[out] | destination | The destination messag buffer to copy the source to. |
size | The size of the source buffer. |
Definition at line 464 of file coremsgimpl.h.
|
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.
[in,out] | the_message_queue | The message queue to operate upon. |
buffer | The buffer that is copied to the threads mutable_object. | |
size | The size of the buffer. | |
submit_type | Indicates whether the thread should be willing to block in the future. | |
queue_context | The thread queue context. |
thread | The Thread_Control for the first locked thread, if there is a locked thread. |
NULL | There are pending messages or no thread waiting to receive. |
Definition at line 612 of file coremsgimpl.h.
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.
[in,out] | the_message_queue | The message queue to flush. |
queue_context | The thread queue context with interrupts disabled. |
Definition at line 24 of file coremsgflush.c.
|
static |
Frees a message buffer to inactive message buffer chain.
This routine frees a message buffer to the inactive message buffer chain.
[in,out] | the_message_queue | The message queue to free the message buffer to. |
[out] | the_message | The message to be freed. |
Definition at line 502 of file coremsgimpl.h.
|
static |
Gets message priority.
This function returns the priority of the_message.
the_message | The message to obtain the priority from. |
priority | The priority of this message. |
0 | Message priority is disabled. |
Definition at line 523 of file coremsgimpl.h.
|
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.
[in,out] | the_message_queue | The message queue to get the first message from. |
pointer | The first message if the message queue is not empty. |
NULL | The message queue is empty. |
Definition at line 546 of file coremsgimpl.h.
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.
[out] | the_message_queue | is the message queue to initialize. |
discipline | is the blocking discipline for the message queue. | |
maximum_pending_messages | is the maximum number of messages that will be allowed to be pending at any given time. | |
maximum_message_size | is the size of the largest message that may be sent to this message queue instance. | |
allocate_buffers | is the message buffer storage area allocation handler. | |
arg | is the message buffer storage area allocation handler argument. |
STATUS_SUCCESSFUL | The message queue was initialized. |
STATUS_MESSAGE_QUEUE_INVALID_SIZE | Calculations with the maximum pending messages or maximum message size produced an integer overflow. |
STATUS_MESSAGE_QUEUE_NO_MEMORY | The message buffer storage area allocation failed. |
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.
[in,out] | the_message_queue | The message queue to insert a message in. |
[in,out] | the_message | The message to insert in the message queue. |
content_source | The message content source. | |
content_size | The message content size in bytes. | |
submit_type | Determines whether the message is prepended, appended, or enqueued in priority order. |
Definition at line 41 of file coremsginsert.c.
|
static |
Releases the message queue.
[in,out] | the_message_queue | The message queue to release. |
queue_context | The thread queue context. |
Definition at line 446 of file coremsgimpl.h.
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.
[in,out] | the_message_queue | The message queue to seize a message from. |
executing | The executing thread. | |
[out] | buffer | The starting address of the message buffer to to be filled in with a message. |
[out] | size_p | The size of the buffer, indicates the maximum size message that the caller can receive. |
wait | Indicates whether the calling thread is willing to block if the message queue is empty. | |
queue_context | The thread queue context used for _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical(). |
STATUS_SUCCESSFUL | The message was successfully seized from the message queue. |
STATUS_UNSATISFIED | Wait was set to false and there is currently no pending message. |
STATUS_TIMEOUT | A timeout occured. |
Definition at line 27 of file coremsgseize.c.
|
static |
Sends a message to the message queue.
[in,out] | the_message_queue | The message queue to send a message to. |
buffer | The starting address of the message to send. | |
sizeis | The size of the message being send. | |
wait | Indicates whether the calling thread is willing to block if the message queue is full. | |
queue_context | The thread queue context used for _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical(). |
STATUS_SUCCESSFUL | The message was successfully submitted to the message queue. |
STATUS_MESSAGE_INVALID_SIZE | The message size was too big. |
STATUS_TOO_MANY | No message buffers were available. |
STATUS_MESSAGE_QUEUE_WAIT_IN_ISR | The caller is in an ISR, do not block! |
STATUS_TIMEOUT | A timeout occured. |
Definition at line 357 of file coremsgimpl.h.
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.
[in,out] | the_message_queue | The message queue to operate upon. |
executing | The executing thread. | |
buffer | The starting address of the message to send. | |
size | The size of the message being send. | |
submit_type | Determines whether the message is prepended, appended, or enqueued in priority order. | |
wait | Indicates whether the calling thread is willing to block if the message queue is full. | |
queue_context | The thread queue context used for _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical(). |
STATUS_SUCCESSFUL | The message was successfully submitted to the message queue. |
STATUS_MESSAGE_INVALID_SIZE | The message size was too big. |
STATUS_TOO_MANY | No message buffers were available. |
STATUS_MESSAGE_QUEUE_WAIT_IN_ISR | The caller is in an ISR, do not block! |
STATUS_TIMEOUT | A timeout occured. |
Definition at line 29 of file coremsgsubmit.c.
|
static |
Sends an urgent message to the message queue.
[in,out] | the_message_queue | The message queue to send an urgent message to. |
buffer | The starting address of the message to send. | |
sizeis | The size of the message being send. | |
wait | Indicates whether the calling thread is willing to block if the message queue is full. | |
queue_context | The thread queue context used for _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical(). |
STATUS_SUCCESSFUL | The message was successfully submitted to the message queue. |
STATUS_MESSAGE_INVALID_SIZE | The message size was too big. |
STATUS_TOO_MANY | No message buffers were available. |
STATUS_MESSAGE_QUEUE_WAIT_IN_ISR | The caller is in an ISR, do not block! |
STATUS_TIMEOUT | A timeout occured. |
Definition at line 393 of file coremsgimpl.h.
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().
[out] | the_message_queue | is the message queue control. |
size | is the message buffer storage area size to allocate. | |
arg | is the unused handler argument. |
NULL | The allocation failed. |
Definition at line 44 of file coremsgwkspace.c.