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

Collaboration diagram for Message Queue Handler:

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_Attributes
	Control block used to manage the attributes of each message queue. More...
struct	CORE_message_queue_Control
	Control block used to manage each message queue. More...
Defines
#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.
#define	RTEMS_SCORE_COREMSG_ENABLE_NOTIFICATION
	This macro is defined when an API is enabled that requires that the Message Queue Handler include support for notification of enqueuing a message.
#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.
#define	CORE_MESSAGE_QUEUE_SEND_REQUEST INT_MAX
	Used when appending messages onto a message queue.
#define	CORE_MESSAGE_QUEUE_URGENT_REQUEST INT_MIN
	Used when prepending messages onto a message queue.
#define	CORE_MESSAGE_QUEUE_STATUS_LAST CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED_WAIT
	Core message queue last status value.
#define	_CORE_message_queue_Set_notify(the_message_queue, the_handler, the_argument)
	This routine initializes the notification information for the_message_queue.
Typedefs
typedef void(*	CORE_message_queue_API_mp_support_callout )(Thread_Control *, Objects_Id)
	Callout provides to support global/multiprocessor operations.
typedef int	CORE_message_queue_Submit_types
	The modes in which a message may be submitted to a message queue.
typedef void(*	CORE_message_queue_Notify_Handler )(void *)
	Type for a notification handler.
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...
enum	CORE_message_queue_Status { CORE_MESSAGE_QUEUE_STATUS_SUCCESSFUL, CORE_MESSAGE_QUEUE_STATUS_INVALID_SIZE, CORE_MESSAGE_QUEUE_STATUS_TOO_MANY, CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED, CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED_NOWAIT, CORE_MESSAGE_QUEUE_STATUS_WAS_DELETED, CORE_MESSAGE_QUEUE_STATUS_TIMEOUT, CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED_WAIT }
	The possible set of Core Message Queue handler return statuses. More...
Functions
bool	_CORE_message_queue_Initialize (CORE_message_queue_Control the_message_queue, CORE_message_queue_Attributes the_message_queue_attributes, uint32_t maximum_pending_messages, size_t maximum_message_size)
	Initialize a message queue.
void	_CORE_message_queue_Close (CORE_message_queue_Control *the_message_queue, Thread_queue_Flush_callout remote_extract_callout, uint32_t status)
	Close a message queue.
uint32_t	_CORE_message_queue_Flush (CORE_message_queue_Control *the_message_queue)
	Flush pending messages.
uint32_t	_CORE_message_queue_Flush_support (CORE_message_queue_Control *the_message_queue)
	Flush all outstanding messages.
CORE_message_queue_Status	_CORE_message_queue_Broadcast (CORE_message_queue_Control the_message_queue, const void buffer, size_t size, Objects_Id id, CORE_message_queue_API_mp_support_callout api_message_queue_mp_support, uint32_t *count)
	Broadcast a message to the message queue.
CORE_message_queue_Status	_CORE_message_queue_Submit (CORE_message_queue_Control the_message_queue, const void buffer, size_t size, Objects_Id id, CORE_message_queue_API_mp_support_callout api_message_queue_mp_support, CORE_message_queue_Submit_types submit_type, bool wait, Watchdog_Interval timeout)
	Submit a message to the message queue.
void	_CORE_message_queue_Seize (CORE_message_queue_Control the_message_queue, Objects_Id id, void buffer, size_t *size_p, bool wait, Watchdog_Interval timeout)
	Size a message from the message queue.
void	_CORE_message_queue_Insert_message (CORE_message_queue_Control the_message_queue, CORE_message_queue_Buffer_control the_message, CORE_message_queue_Submit_types submit_type)
	Insert a message into the message queue.
RTEMS_INLINE_ROUTINE CORE_message_queue_Status	_CORE_message_queue_Send (CORE_message_queue_Control the_message_queue, const void buffer, size_t size, Objects_Id id, CORE_message_queue_API_mp_support_callout api_message_queue_mp_support, bool wait, Watchdog_Interval timeout)
	This routine sends a message to the end of the specified message queue.
RTEMS_INLINE_ROUTINE CORE_message_queue_Status	_CORE_message_queue_Urgent (CORE_message_queue_Control the_message_queue, const void buffer, size_t size, Objects_Id id, CORE_message_queue_API_mp_support_callout api_message_queue_mp_support, bool wait, Watchdog_Interval timeout)
	This routine sends a message to the front of the specified message queue.
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.
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.
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.
RTEMS_INLINE_ROUTINE int	_CORE_message_queue_Get_message_priority (CORE_message_queue_Buffer_control *the_message)
	This function returns the priority of the_message.
RTEMS_INLINE_ROUTINE void	_CORE_message_queue_Set_message_priority (CORE_message_queue_Buffer_control *the_message, int priority)
	This function sets the priority of the_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.
RTEMS_INLINE_ROUTINE bool	_CORE_message_queue_Is_priority (CORE_message_queue_Attributes *the_attribute)
	This function returns true if the priority attribute is enabled in the attribute_set and false otherwise.
RTEMS_INLINE_ROUTINE void	_CORE_message_queue_Append_unprotected (CORE_message_queue_Control the_message_queue, CORE_message_queue_Buffer_control the_message)
	This routine places the_message at the rear of the outstanding messages on the_message_queue.
RTEMS_INLINE_ROUTINE void	_CORE_message_queue_Prepend_unprotected (CORE_message_queue_Control the_message_queue, CORE_message_queue_Buffer_control the_message)
	This routine places the_message at the front of the outstanding messages on the_message_queue.
RTEMS_INLINE_ROUTINE bool	_CORE_message_queue_Is_null (CORE_message_queue_Control *the_message_queue)
	This function returns true if the_message_queue is true and false otherwise.

Detailed Description

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

Define Documentation

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

Referenced by _CORE_message_queue_Send().

#define CORE_MESSAGE_QUEUE_STATUS_LAST CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED_WAIT

Core message queue last status value.

This is the last status value.

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

Referenced by _CORE_message_queue_Urgent().

Typedef Documentation

typedef void( * CORE_message_queue_API_mp_support_callout)(Thread_Control *, Objects_Id)

Callout provides to support global/multiprocessor operations.

The following type defines the callout which the API provides to support global/multiprocessor operations on message_queues.

typedef void(* CORE_message_queue_Notify_Handler)(void *)

Type for a notification handler.

The following defines the type for a Notification handler. A notification handler is invoked when the message queue makes a 0->1 transition on pending messages.

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.

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

Enumeration Type Documentation

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

enum CORE_message_queue_Status

The possible set of Core Message Queue handler return statuses.

This enumerated type defines the possible set of Core Message Queue handler return statuses.

Enumerator:

CORE_MESSAGE_QUEUE_STATUS_SUCCESSFUL	This value indicates the operation completed sucessfully.
CORE_MESSAGE_QUEUE_STATUS_INVALID_SIZE	This value indicates that the message was too large for this queue.
CORE_MESSAGE_QUEUE_STATUS_TOO_MANY	This value indicates that there are too many messages pending.
CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED	This value indicates that a receive was unsuccessful.
CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED_NOWAIT	This value indicates that a blocking send was unsuccessful.
CORE_MESSAGE_QUEUE_STATUS_WAS_DELETED	This value indicates that the message queue being blocked upon was deleted while the thread was waiting.
CORE_MESSAGE_QUEUE_STATUS_TIMEOUT	This value indicates that the thread had to timeout while waiting to receive a message because one did not become available.
CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED_WAIT	This value indicates that a blocking receive was unsuccessful.

Function Documentation

CORE_message_queue_Status _CORE_message_queue_Broadcast	(	CORE_message_queue_Control *	the_message_queue,
		const void *	buffer,
		size_t	size,
		Objects_Id	id,
		CORE_message_queue_API_mp_support_callout	api_message_queue_mp_support,
		uint32_t *	count
	)

Broadcast a message to the message queue.

DESCRIPTION: 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_queue	points to the message queue
[in]	buffer	is the starting address of the message to broadcast
[in]	size	is the size of the message being broadcast
[in]	id	is the RTEMS object Id associated with this message queue. It is used when unblocking a remote thread.
[in]	api_message_queue_mp_support	is the routine to invoke if a thread that is unblocked is actually a remote thread.
[out]	count	points to the variable that will contain the number of tasks that are sent this message

Return values:

@a	*count will contain the number of messages sent
indication	of the successful completion or reason for failure

void _CORE_message_queue_Close	(	CORE_message_queue_Control *	the_message_queue,
		Thread_queue_Flush_callout	remote_extract_callout,
		uint32_t	status
	)

Close a message queue.

DESCRIPTION: 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_queue	points to the message queue to close
[in]	remote_extract_callout	is the routine to call for each thread that is extracted from the set of waiting threads
[in]	status	is the status that each waiting thread will return from it's blocking service

uint32_t _CORE_message_queue_Flush ( CORE_message_queue_Control * the_message_queue )

Flush pending messages.

DESCRIPTION: 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_queue points to the message queue to flush

Return values:

This	method returns the number of message pending messages flushed.

uint32_t _CORE_message_queue_Flush_support ( CORE_message_queue_Control * the_message_queue )

Flush all outstanding messages.

This routine flushes all outstanding messages and returns them to the inactive message chain.

Parameters:

[in] the_message_queue points to the message queue to flush

Return values:

This	method returns the number of pending messages flushed.

INTERRUPT LATENCY: + single case

RTEMS_INLINE_ROUTINE int _CORE_message_queue_Get_message_priority ( 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.

References CORE_message_queue_Buffer_control::priority.

bool _CORE_message_queue_Initialize	(	CORE_message_queue_Control *	the_message_queue,
		CORE_message_queue_Attributes *	the_message_queue_attributes,
		uint32_t	maximum_pending_messages,
		size_t	maximum_message_size
	)

Initialize a message queue.

DESCRIPTION:

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_queue	points to the message queue to initialize
[in]	the_message_queue_attributes	points to the attributes that will be used with this message queue instance
[in]	maximum_pending_messages	is the maximum number of messages that will be allowed to pend at any given time
[in]	maximum_message_size	is the size of largest message that may be sent to this message queue instance

Return values:

true	if the message queue can be initialized. In general, false will only be returned if memory for the pending messages cannot be allocated.

void _CORE_message_queue_Insert_message	(	CORE_message_queue_Control *	the_message_queue,
		CORE_message_queue_Buffer_control *	the_message,
		CORE_message_queue_Submit_types	submit_type
	)

Insert a message into the message queue.

This kernel routine inserts the specified message into the message queue. It is assumed that the message has been filled in before this routine is called.

Parameters:

[in]	the_message_queue	points to the message queue
[in]	the_message	is the message to enqueue
[in]	submit_type	determines whether the message is prepended, appended, or enqueued in priority order.

INTERRUPT LATENCY: + insert

void _CORE_message_queue_Seize	(	CORE_message_queue_Control *	the_message_queue,
		Objects_Id	id,
		void *	buffer,
		size_t *	size_p,
		bool	wait,
		Watchdog_Interval	timeout
	)

Size a message from the message queue.

DESCRIPTION: 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_queue	points to the message queue
[in]	id	is the RTEMS object Id associated with this message queue. It is used when unblocking a remote thread.
[in]	buffer	is the starting address of the message buffer to to be filled in with a message
[in]	size_p	is a pointer to the size of the buffer and indicates the maximum size message that the caller can receive.
[in]	wait	indicates whether the calling thread is willing to block if the message queue is empty.
[in]	timeout	is the maximum number of clock ticks that the calling thread is willing to block if the message queue is empty.

Return values:

indication of 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

RTEMS_INLINE_ROUTINE void _CORE_message_queue_Set_message_priority	(	CORE_message_queue_Buffer_control *	the_message,
		int	priority
	)

This function sets the priority of the_message.

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

References CORE_message_queue_Buffer_control::priority.

CORE_message_queue_Status _CORE_message_queue_Submit	(	CORE_message_queue_Control *	the_message_queue,
		const void *	buffer,
		size_t	size,
		Objects_Id	id,
		CORE_message_queue_API_mp_support_callout	api_message_queue_mp_support,
		CORE_message_queue_Submit_types	submit_type,
		bool	wait,
		Watchdog_Interval	timeout
	)

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_queue	points to the message queue
[in]	buffer	is the starting address of the message to send
[in]	size	is the size of the message being send
[in]	id	is the RTEMS object Id associated with this message queue. It is used when unblocking a remote thread.
[in]	api_message_queue_mp_support	is the routine to invoke if a thread that is unblocked is actually a remote thread.
[in]	submit_type	determines whether the message is prepended, appended, or enqueued in priority order.
[in]	wait	indicates whether the calling thread is willing to block if the message queue is full.
[in]	timeout	is the maximum number of clock ticks that the calling thread is willing to block if the message queue is full.

Return values:

indication of the successful completion or reason for failure

Referenced by _CORE_message_queue_Send(), and _CORE_message_queue_Urgent().

Data Structures

Defines

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation