邮箱
邮箱接口
结构体 | |
| 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_uint32_t value, rt_int32_t timeout) |
| 等待方式发送邮件 | |
| rt_err_t | rt_mb_send (rt_mailbox_t mb, rt_uint32_t value) |
| 发送邮件 | |
| rt_err_t | rt_mb_recv (rt_mailbox_t mb, rt_uint32_t *value, rt_int32_t timeout) |
| 接收邮件 | |
详细描述
邮箱接口
邮箱是一种简单的线程间消息传递方式，在 RT-Thread 操作系统的实现中能够一次传递 4 字节邮件， 并且邮箱具备一定的存储功能，能够缓存一定数量的邮件数 (邮件数由创建、初始化邮箱时指定的 容量决定)。邮箱中一封邮件的最大长度是 4 字节，所以邮箱能够用于不超过 4 字节的消息传递， 当传送的消息长度大于这个数目时就不能再采用邮箱的方式。
函数说明
| rt_err_t rt_mb_init | ( | rt_mailbox_t | mb, |
| const char * | name, | ||
| void * | msgpool, | ||
| rt_size_t | size, | ||
| rt_uint8_t | flag | ||
| ) |
初始化邮箱
该函数将初始化邮箱并将其置于内核管理器的控制之下。
- 参数
mb 邮箱对象的句柄 name 邮箱的名称 msgpool 缓冲区指针 size 邮箱容量 flag 邮箱标志，它可以取数值：RT_IPC_FLAG_FIFO或RT_IPC_FLAG_PRIO
- 返回
- RT_EOK
- 示例:
- mailbox_sample.c.
| rt_err_t rt_mb_detach | ( | rt_mailbox_t | mb | ) |
脱离邮箱
该函数将将把静态初始化的邮箱对象从内核对象管理器中删除。使用该函数接口后， 内核先唤醒所有挂在该邮箱上的线程（线程获得返回值是 - RT_ERROR ），然后将 该邮箱对象从内核对象管理器中删除。
- 参数
mb 邮箱对象的句柄
- 返回
- RT_EOK
- 示例:
- mailbox_sample.c.
| rt_mailbox_t rt_mb_create | ( | const char * | name, |
| rt_size_t | size, | ||
| rt_uint8_t | flag | ||
| ) |
创建邮箱
调用该函数创建邮箱对象时会先从对象管理器中分配一个邮箱对象，然后给邮箱动态分配 一块内存空间用来存放邮件，这块内存的大小等于邮件大小（4 字节）与邮箱容量的乘积， 接着初始化接收邮件数目和发送邮件在邮箱中的偏移量。
- 参数
name 邮箱的名称 size 邮箱容量 flag 邮箱标志，它可以取值：RT_IPC_FLAG_FIFO 或 RT_IPC_FLAG_PRIO
- 返回
- 返回创建的邮箱对象，创建失败时返回 RT_NULL
| rt_err_t rt_mb_delete | ( | rt_mailbox_t | mb | ) |
删除邮箱
当用rt_mb_create()创建的邮箱不再被使用时，应该调用该函数删除它来释放相应的系统资源， 一旦操作完成，邮箱将被永久性的删除。删除邮箱时，如果有线程被挂起在该邮箱对象上， 内核先唤醒挂起在该邮箱上的所有线程（线程返回值是- RT_ERROR），然后再释放邮箱使用的 内存，最后删除邮箱对象。
- 参数
mb 邮箱对象的句柄
- 返回
- 错误代码
| rt_err_t rt_mb_send_wait | ( | rt_mailbox_t | mb, |
| rt_uint32_t | value, | ||
| rt_int32_t | timeout | ||
| ) |
等待方式发送邮件
用户也可以通过调用该函数接口向指定邮箱发送邮件。它与 rt_mb_send()的区别在于， 如果邮箱已经满了，那么发送线程将根据设定的timeout参数等待邮箱中因为收取邮件 而空出空间。如果设置的超时时间到达依然没有空出空间，这时发送线程将被唤醒返回 错误码。
- 参数
mb 邮箱对象的句柄 value 邮件内容 timeout 超时时间
- 返回
- RT_EOK 发送成功；-RT_ETIMEOUT 超时；-RT_ERROR 失败，返回错误号
| rt_err_t rt_mb_send | ( | rt_mailbox_t | mb, |
| rt_uint32_t | value | ||
| ) |
发送邮件
线程或者中断服务程序可以通过调用该函数给其他线程发送邮件。发送的邮件可以是 32 位 任意格式的数据，一个整型值或者一个指向缓冲区的指针。当邮箱中的邮件已经满时，发送 邮件的线程或者中断程序会收到- RT_EFULL 的返回值。
- 参数
mb 邮箱对象的句柄 value 邮件内容
- 返回
- RT_EOK 发送成功；-RT_EFULL 邮箱已经满了
- 示例:
- mailbox_sample.c.
| rt_err_t rt_mb_recv | ( | rt_mailbox_t | mb, |
| rt_uint32_t * | value, | ||
| rt_int32_t | timeout | ||
| ) |
接收邮件
只有当接收者接收的邮箱中有邮件时，接收者才能立即取到邮件并返回 RT_EOK 的返回值， 否则接收线程会根据超时时间设置，或挂起在邮箱的等待线程队列上，或直接返回。
- 参数
mb 邮箱对象的句柄 value 邮件内容 timeout 超时时间
- 返回
- RT_EOK 发送成功；-RT_ETIMEOUT 超时；-RT_ERROR 失败，返回错误号
- 示例:
- mailbox_sample.c.