原创 RT-Thread隐藏的宝藏之completion

completion 直接翻译过来是完成，所以我更愿意称 rt_completion 为 完成量。在 RT-Thread 的文档中心 中讲线程间通讯（IPC）时，只介绍了，信号量， 互斥量， 事件集，其实 rt_completion 可以认为是轻量级的二值信号量。

completion 的使用非常简单

1. 定义一个完成量

   struct rt_completion completion;

2. 初始化完成量

   rt_completion_init(&completion);

3. 等待完成量

   rt_completion_wait(&completion);

4. 释放完成量

   rt_completion_done(&completion);

completion 的 API 非常少，可以通过简单的代码去分析

1. 初始化完成量

   void rt_completion_init(struct rt_completion *completion) { rt_base_t level; RT_ASSERT(completion != RT_NULL); level = rt_hw_interrupt_disable(); completion->flag = RT_UNCOMPLETED; rt_list_init(&completion->suspended_list); rt_hw_interrupt_enable(level); }

   干了两件事：

   • 设置 flag 为 RT_UNCOMPLETED
   • 初始化完成量的链表

2. 等待完成量(以下代码有删减)

   rt_err_t rt_completion_wait(struct rt_completion *completion, rt_int32_t timeout) { result = RT_EOK; thread = rt_thread_self(); level = rt_hw_interrupt_disable(); if (completion->flag != RT_COMPLETED) { if (timeout == 0) { } else { /* reset thread error number */ thread->error = RT_EOK; /* suspend thread */ rt_thread_suspend(thread); /* add to suspended list */ rt_list_insert_before(&(completion->suspended_list), &(thread->tlist)); /* current context checking */ RT_DEBUG_NOT_IN_INTERRUPT; /* start timer */ if (timeout > 0) { /* reset the timeout of thread timer and start it */ rt_timer_control(&(thread->thread_timer), RT_TIMER_CTRL_SET_TIME, &timeout); rt_timer_start(&(thread->thread_timer)); } /* enable interrupt */ rt_hw_interrupt_enable(level); /* do schedule */ rt_schedule(); /* thread is waked up */ result = thread->error; level = rt_hw_interrupt_disable(); } } /* clean completed flag */ completion->flag = RT_UNCOMPLETED; return result; }

   主要做了以下工作：

   • 关中断：rt_hw_interrupt_disable();
   • 挂起当前线程：rt_thread_suspend(thread);
   • 把挂起状态插入到线程的链表中：rt_list_insert_before
   • 确保当前函数执行不是在中断中：RT_DEBUG_NOT_IN_INTERRUPT;
   • 设置并启动定时器：rt_timer_start(&(thread->thread_timer));
   • 开中断：rt_hw_interrupt_enable(level);
   • 开调度器：rt_schedule();
   • 获取当前线程状态：result = thread->error;
   • 设置完成量的标志位：completion->flag = RT_UNCOMPLETED;
   • 返回线程状态

这样就完成了线程的挂起。

1. 完成完成量(以下代码有删减)

   void rt_completion_done(struct rt_completion *completion) { level = rt_hw_interrupt_disable(); completion->flag = RT_COMPLETED; if (!rt_list_isempty(&(completion->suspended_list))) { /* there is one thread in suspended list */ struct rt_thread *thread; /* get thread entry */ thread = rt_list_entry(completion->suspended_list.next, struct rt_thread, tlist); /* resume it */ rt_thread_resume(thread); rt_hw_interrupt_enable(level); /* perform a schedule */ rt_schedule(); } }

   主要做了以下工作：

   • 关中断：rt_hw_interrupt_disable();
   • 设置 flag 为 RT_COMPLETED
   • 检查链表不为空：rt_list_isempty
   • 获取到当前等待完成量的句柄：rt_list_entry
   • 启动被挂起的线程：rt_thread_resume(thread);
   • 开中断：rt_hw_interrupt_enable(level);
   • 开调度：rt_schedule();

1. completion API 个数少，资源占用少，只能释放获取，不支持多次释放
2. semaphore API 个数多，资源占用较多，使用灵活，可以尝试获取，可以多次释放，

1. 标准版 RT-Thread 中的 completion 源码在 "\rt-thread\components\drivers\src\completion.c"在你要使用的文件中#include completion.h直接就可以使用。
2. Nano 版 RT-Thread 直接拷贝completion.c 和 completion.h 添加到工程就可以使用。