Mailbox

Collaboration diagram for Mailbox:

Data Structures
struct	rt_mailbox

Functions
rt_err_t	rt_mb_init (rt_mailbox_t mb, const char *name, void *msgpool, rt_size_t size, rt_uint8_t flag)
rt_err_t	rt_mb_detach (rt_mailbox_t mb)
rt_mailbox_t	rt_mb_create (const char *name, rt_size_t size, rt_uint8_t flag)
rt_err_t	rt_mb_delete (rt_mailbox_t mb)
rt_err_t	rt_mb_send (rt_mailbox_t mb, rt_ubase_t value)
rt_err_t	rt_mb_urgent (rt_mailbox_t mb, rt_ubase_t value)
rt_err_t	rt_mb_control (rt_mailbox_t mb, int cmd, void *arg)

Detailed Description

Function Documentation

rt_mb_init()

rt_err_t rt_mb_init	(	rt_mailbox_t	mb,
		const char *	name,
		void *	msgpool,
		rt_size_t	size,
		rt_uint8_t	flag
	)

Initialize a static mailbox object.

Note

For the static mailbox 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_mb_create() function will allocate memory space automatically and initialize the mailbox.

See also

rt_mb_create()

Parameters

mb	is a pointer to the mailbox to initialize. It is assumed that storage for the mailbox will be allocated in your application.
name	is a pointer to the name that given to the mailbox.
msgpool	the begin address of buffer to save received mail.
size	is the maximum number of mails in the mailbox. For example, when the mailbox buffer capacity is N, size is N/4.
flag	is the mailbox flag, which determines the queuing way of how multiple threads wait when the mailbox is not available. The mailbox 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 mailbox 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_mb_detach()

rt_err_t rt_mb_detach

(

rt_mailbox_t

mb

)

This function will detach a static mailbox object.

Note

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

See also

rt_mb_delete()

Parameters

mb	is a pointer to a mailbox 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 mailbox detach failed.

Warning

This function can ONLY detach a static mailbox initialized by the rt_mb_init() function. If the mailbox is created by the rt_mb_create() function, you MUST NOT USE this function to detach it, ONLY USE the rt_mb_delete() function to complete the deletion.

rt_mb_create()

rt_mailbox_t rt_mb_create	(	const char *	name,
		rt_size_t	size,
		rt_uint8_t	flag
	)

Creating a mailbox object.

Note

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

See also

rt_mb_init()

Parameters

name	is a pointer that given to the mailbox.
size	is the maximum number of mails in the mailbox. For example, when mailbox buffer capacity is N, size is N/4.
flag	is the mailbox flag, which determines the queuing way of how multiple threads wait when the mailbox is not available. The mailbox 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 mailbox will become non-real-time threads.

Returns

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

Warning

This function can ONLY be called from threads.

rt_mb_delete()

rt_err_t rt_mb_delete

(

rt_mailbox_t

mb

)

This function will delete a mailbox object and release the memory space.

Note

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

See also

rt_mb_detach()

Parameters

mb	is a pointer to a mailbox 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 mailbox detach failed.

Warning

This function can only delete mailbox created by the rt_mb_create() function. If the mailbox is initialized by the rt_mb_init() function, you MUST NOT USE this function to delete it, ONLY USE the rt_mb_detach() function to complete the detachment.

rt_mb_send()

rt_err_t rt_mb_send	(	rt_mailbox_t	mb,
		rt_ubase_t	value
	)

This function will send an mail to the mailbox object. If there is a thread suspended on the mailbox, the thread will be resumed.

Note

When using this function to send a mail, if the mailbox is fully used, this function will return an error code immediately without waiting time. By contrast, the rt_mb_send_wait() function is set a timeout to wait for the mail to be sent.

See also

rt_mb_send_wait()

Parameters

mb	is a pointer to the mailbox object to be sent.
value	is a value to the content of the mail you want to send.

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_mb_urgent()

rt_err_t rt_mb_urgent	(	rt_mailbox_t	mb,
		rt_ubase_t	value
	)

This function will send an urgent mail to the mailbox object.

Note

This function is almost the same as the rt_mb_send() function. The only difference is that when sending an urgent mail, the mail will be placed at the head of the mail queue so that the recipient can receive the urgent mail first.

See also

rt_mb_send()

Parameters

mb	is a pointer to the mailbox object to be sent.
value	is the content of the mail you want to send.

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_mb_control()

rt_err_t rt_mb_control	(	rt_mailbox_t	mb,
		int	cmd,
		void *	arg
	)

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

Note

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

Parameters

mb	is a pointer to a mailbox object.
cmd	is a command used to configure some attributions of the mailbox.
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.