邮箱

提供固定长度消息传递服务 更多...

结构体
struct	rt_mailbox
	邮箱结构体 更多...

类型定义
typedef struct rt_mailbox *	rt_mailbox_t
	邮箱类型指针定义

函数
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_wait (rt_mailbox_t mb, rt_ubase_t value, rt_int32_t timeout)
	带超时等待向邮箱中发送消息 更多...
rt_err_t	rt_mb_urgent (rt_mailbox_t mb, rt_ubase_t value)
	向邮箱中发送紧急消息 更多...
rt_err_t	rt_mb_recv (rt_mailbox_t mb, rt_ubase_t *value, rt_int32_t timeout)
	从邮箱接收消息 更多...
rt_err_t	rt_mb_control (rt_mailbox_t mb, int cmd, void *arg)
	控制邮箱的特性或行为 更多...

详细描述

提供固定长度消息传递服务

RT-Thread 邮箱特性：

• 每个邮箱支持 4/8 字节定长消息
• 支持超时等待机制
• 提供紧急消息发送功能
• 零拷贝消息传递（指针传递）

典型应用场景：

• 小数据量线程间通信
• 中断与线程间的紧急通知

函数说明

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
	)

初始化静态邮箱对象

用于初始化由用户分配内存的邮箱，适用于静态分配场景

参数

[in]	mb	邮箱对象指针
[in]	name	邮箱名称
[in]	msgpool	消息池缓冲区地址
[in]	size	消息池中可存放的消息数
[in]	flag	等待标志位 标志位 含义 RT_IPC_FLAG_FIFO 先进先出方式等待 RT_IPC_FLAG_PRIO 按线程优先级等待（高优先级先获取）

返回值

RT_EOK	成功
!RT_EOK	失败

注解

• 邮箱名称的最大长度由 rtconfig.h 中定义的 RT_NAME_MAX 宏指定， 多余部分会被自动截掉

rt_mb_detach()

rt_err_t rt_mb_detach

(

rt_mailbox_t

mb

)

脱离静态邮箱对象

释放由 rt_mb_init() 初始化的静态邮箱对象

参数

[in]

mb

邮箱对象指针

返回值

RT_EOK	成功
!RT_EOK	失败

警告

• 需要脱离的静态邮箱对象必须由 rt_mb_init() 初始化

rt_mb_create()

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

创建动态邮箱对象

创建时自动申请邮箱控制块及消息池的内存，适用于动态分配场景

参数

[in]	name	邮箱名称
[in]	size	邮箱最多可容纳的消息数量
[in]	flag	等待标志位 标志位 含义 RT_IPC_FLAG_FIFO 先进先出方式等待 RT_IPC_FLAG_PRIO 按线程优先级等待（高优先级先获取）

返回值

!RT_NULL	成功
RT_NULL	失败

注解

• 邮箱名称的最大长度由 rtconfig.h 中定义的 RT_NAME_MAX 宏指定， 多余部分会被自动截掉

rt_mb_delete()

rt_err_t rt_mb_delete

(

rt_mailbox_t

mb

)

删除动态邮箱对象

销毁由 rt_mb_create() 创建的邮箱对象，并释放相关内存

参数

[in]

mb

邮箱对象指针

返回值

RT_EOK	成功
!RT_EOK	失败

警告

• 需要删除的动态邮箱对象必须由 rt_mb_create() 创建

rt_mb_send_wait()

rt_err_t rt_mb_send_wait	(	rt_mailbox_t	mb,
		rt_ubase_t	value,
		rt_int32_t	timeout
	)

带超时等待向邮箱中发送消息

若邮箱已满，当前线程将挂起等待指定时间，直到邮箱有空间或超时

参数

[in]	mb	邮箱对象指针
[in]	value	要发送的消息值
[in]	timeout	超时时间 标志位 含义 RT_WAITING_FOREVER 永久等待 RT_WAITING_NO 不等待立即返回 其他数值 timeout * 系统 tick 超时时间

返回值

RT_EOK	成功
-RT_ETIMEOUT	超时
!RT_EOK	失败

rt_mb_urgent()

rt_err_t rt_mb_urgent	(	rt_mailbox_t	mb,
		rt_ubase_t	value
	)

向邮箱中发送紧急消息

紧急消息将插入邮箱队列头部，优先被接收

参数

[in]	mb	邮箱对象指针
[in]	value	要发送的消息值

返回值

RT_EOK	成功
-RT_EFULL	邮箱已满
!RT_EOK	其它错误

警告

• 紧急消息机制可打乱 FIFO 发送顺序，需谨慎使用

rt_mb_recv()

rt_err_t rt_mb_recv	(	rt_mailbox_t	mb,
		rt_ubase_t *	value,
		rt_int32_t	timeout
	)

从邮箱接收消息

若邮箱为空，当前线程将阻塞等待指定时间直至接收到消息或超时

参数

[in]	mb	邮箱对象指针
[out]	value	指向接收值的指针
[in]	timeout	超时时间 标志位 含义 RT_WAITING_FOREVER 永久等待 RT_WAITING_NO 不等待立即返回 其他数值 timeout * 系统 tick 超时时间

返回值

RT_EOK	成功
-RT_ETIMEOUT	超时
!RT_EOK	失败

rt_mb_control()

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

控制邮箱的特性或行为

用于执行特定控制命令

参数

[in]	mb	邮箱对象指针
[in]	cmd	控制命令
[in]	arg	控制命令的参数

返回值

RT_EOK	成功
!RT_EOK	失败