RT-Thread 隐藏的宝藏之 completion

1. completion 是什么

completion 直接翻译过来是完成，所以我们可以称 rt_completion 为 完成量。在 RT-Thread 的文档中心 中讲线程间同步时，介绍了 信号量， 互斥量， 事件集 。 rt_completion 的作用也是实现线程间的同步，他是一个 轻量级的二值信号量。

2. completion 怎么使用

completion 的使用非常简单

1. 定义一个完成量

   struct rt_completion completion;
   

2. 初始化完成量

   rt_completion_init(&completion);
   

3. 等待完成量

   rt_completion_wait(&completion);
   

4. 释放完成量

   rt_completion_done(&completion);
   

3. 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;
   • 返回线程状态

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

3. 释放完成量(以下代码有删减)

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

4. completion 与信号量的对比

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

5. completion 如何加入工程

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