Message Queue

Collaboration diagram for Message Queue:

Data Structures
struct	rt_messagequeue

Functions
rt_err_t	rt_mq_init (rt_mq_t mq, const char *name, void *msgpool, rt_size_t msg_size, rt_size_t pool_size, rt_uint8_t flag)
rt_err_t	rt_mq_detach (rt_mq_t mq)
rt_mq_t	rt_mq_create (const char *name, rt_size_t msg_size, rt_size_t max_msgs, rt_uint8_t flag)
rt_err_t	rt_mq_delete (rt_mq_t mq)
rt_err_t	rt_mq_send (rt_mq_t mq, const void *buffer, rt_size_t size)
rt_err_t	rt_mq_urgent (rt_mq_t mq, const void *buffer, rt_size_t size)
rt_err_t	rt_mq_control (rt_mq_t mq, int cmd, void *arg)

Detailed Description

Function Documentation

rt_mq_init()

rt_err_t rt_mq_init	(	rt_mq_t	mq,
		const char *	name,
		void *	msgpool,
		rt_size_t	msg_size,
		rt_size_t	pool_size,
		rt_uint8_t	flag
	)

Initialize a static messagequeue object.

Note

For the static messagequeue object, its memory space is allocated by the compiler during compiling, and shall placed on the read-write data segment or on the uninitialized data segment. By contrast, the rt_mq_create() function will allocate memory space automatically and initialize the messagequeue.

See also

rt_mq_create()

Parameters

mq	is a pointer to the messagequeue to initialize. It is assumed that storage for the messagequeue will be allocated in your application.
name	is a pointer to the name that given to the messagequeue.
msgpool	is a pointer to the starting address of the memory space you allocated for the messagequeue in advance. In other words, msgpool is a pointer to the messagequeue buffer of the starting address.
msg_size	is the maximum length of a message in the messagequeue (Unit: Byte).
pool_size	is the size of the memory space allocated for the messagequeue in advance.
flag	is the messagequeue flag, which determines the queuing way of how multiple threads wait when the messagequeue is not available. The messagequeue flag can be ONE of the following values: RT_IPC_FLAG_PRIO The pending threads will queue in order of priority. RT_IPC_FLAG_FIFO The pending threads will queue in the first-in-first-out method (also known as first-come-first-served (FCFS) scheduling strategy). NOTE: RT_IPC_FLAG_FIFO is a non-real-time scheduling mode. It is strongly recommended to use RT_IPC_FLAG_PRIO to ensure the thread is real-time UNLESS your applications concern about the first-in-first-out principle, and you clearly understand that all threads involved in this messagequeue will become non-real-time threads.

Returns

Return the operation status. When the return value is RT_EOK, the initialization is successful. If the return value is any other values, it represents the initialization failed.

Warning

This function can ONLY be called from threads.

rt_mq_detach()

rt_err_t rt_mq_detach

(

rt_mq_t

mq

)

This function will detach a static messagequeue object.

Note

This function is used to detach a static messagequeue object which is initialized by rt_mq_init() function. By contrast, the rt_mq_delete() function will delete a messagequeue object. When the messagequeue is successfully detached, it will resume all suspended threads in the messagequeue list.

See also

rt_mq_delete()

Parameters

mq	is a pointer to a messagequeue object to be detached.

Returns

Return the operation status. When the return value is RT_EOK, the initialization is successful. If the return value is any other values, it means that the messagequeue detach failed.

Warning

This function can ONLY detach a static messagequeue initialized by the rt_mq_init() function. If the messagequeue is created by the rt_mq_create() function, you MUST NOT USE this function to detach it, and ONLY USE the rt_mq_delete() function to complete the deletion.

rt_mq_create()

rt_mq_t rt_mq_create	(	const char *	name,
		rt_size_t	msg_size,
		rt_size_t	max_msgs,
		rt_uint8_t	flag
	)

Creating a messagequeue object.

Note

For the messagequeue object, its memory space is allocated automatically. By contrast, the rt_mq_init() function will initialize a static messagequeue object.

See also

rt_mq_init()

Parameters

name	is a pointer that given to the messagequeue.
msg_size	is the maximum length of a message in the messagequeue (Unit: Byte).
max_msgs	is the maximum number of messages in the messagequeue.
flag	is the messagequeue flag, which determines the queuing way of how multiple threads wait when the messagequeue is not available. The messagequeue flag can be ONE of the following values: RT_IPC_FLAG_PRIO The pending threads will queue in order of priority. RT_IPC_FLAG_FIFO The pending threads will queue in the first-in-first-out method (also known as first-come-first-served (FCFS) scheduling strategy). NOTE: RT_IPC_FLAG_FIFO is a non-real-time scheduling mode. It is strongly recommended to use RT_IPC_FLAG_PRIO to ensure the thread is real-time UNLESS your applications concern about the first-in-first-out principle, and you clearly understand that all threads involved in this messagequeue will become non-real-time threads.

Returns

Return a pointer to the messagequeue object. When the return value is RT_NULL, it means the creation failed.

Warning

This function can NOT be called in interrupt context. You can use macor RT_DEBUG_NOT_IN_INTERRUPT to check it.

rt_mq_delete()

rt_err_t rt_mq_delete

(

rt_mq_t

mq

)

This function will delete a messagequeue object and release the memory.

Note

This function is used to delete a messagequeue object which is created by the rt_mq_create() function. By contrast, the rt_mq_detach() function will detach a static messagequeue object. When the messagequeue is successfully deleted, it will resume all suspended threads in the messagequeue list.

See also

rt_mq_detach()

Parameters

mq	is a pointer to a messagequeue object to be deleted.

Returns

Return the operation status. When the return value is RT_EOK, the operation is successful. If the return value is any other values, it means that the messagequeue detach failed.

Warning

This function can ONLY delete a messagequeue initialized by the rt_mq_create() function. If the messagequeue is initialized by the rt_mq_init() function, you MUST NOT USE this function to delete it, ONLY USE the rt_mq_detach() function to complete the detachment. for example,the rt_mq_create() function, it cannot be called in interrupt context.

rt_mq_send()

rt_err_t rt_mq_send	(	rt_mq_t	mq,
		const void *	buffer,
		rt_size_t	size
	)

This function will send a message to the messagequeue object. If there is a thread suspended on the messagequeue, the thread will be resumed.

Note

When using this function to send a message, if the messagequeue is fully used, the current thread will wait for a timeout. By contrast, when the messagequeue is fully used, the rt_mq_send_wait() function will return an error code immediately without waiting.

See also

rt_mq_send_wait()

Parameters

mq	is a pointer to the messagequeue object to be sent.
buffer	is the content of the message.
size	is the length of the message(Unit: Byte).

Returns

Return the operation status. When the return value is RT_EOK, the operation is successful. If the return value is any other values, it means that the messagequeue detach failed.

Warning

This function can be called in interrupt context and thread context.

rt_mq_urgent()

rt_err_t rt_mq_urgent	(	rt_mq_t	mq,
		const void *	buffer,
		rt_size_t	size
	)

This function will send an urgent message to the messagequeue object.

Note

This function is almost the same as the rt_mq_send() function. The only difference is that when sending an urgent message, the message is placed at the head of the messagequeue so that the recipient can receive the urgent message first.

See also

rt_mq_send()

Parameters

mq	is a pointer to the messagequeue object to be sent.
buffer	is the content of the message.
size	is the length of the message(Unit: Byte).

Returns

Return the operation status. When the return value is RT_EOK, the operation is successful. If the return value is any other values, it means that the mailbox detach failed.

rt_mq_control()

rt_err_t rt_mq_control	(	rt_mq_t	mq,
		int	cmd,
		void *	arg
	)

This function will set some extra attributions of a messagequeue object.

Note

Currently this function only supports the RT_IPC_CMD_RESET command to reset the messagequeue.

Parameters

mq	is a pointer to a messagequeue object.
cmd	is a command used to configure some attributions of the messagequeue.
arg	is the argument of the function to execute the command.

Returns

Return the operation status. When the return value is RT_EOK, the operation is successful. If the return value is any other values, it means that this function failed to execute.