RT-Thread隐藏的宝藏之completion

sunsili

RT-Thread隐藏的宝藏之completion                                                        


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

2.  completion 怎么使用
completion 的使用非常简单

• 定义一个完成量
  struct rt_completion completion;
• 初始化完成量
  rt_completion_init(&completion);
• 等待完成量
  rt_completion_wait(&completion);
• 释放完成量
  rt_completion_done(&completion);
  

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

• 初始化完成量
  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
  • 初始化完成量的链表
    
• 等待完成量(以下代码有删减)
  
  1. rt_err_t rt_completion_wait(struct rt_completion *completion,
     
  2.                             rt_int32_t            timeout)
     
  3. {
     
  4.     result = RT_EOK;
     
  5.     thread = rt_thread_self();
     
  6. 
     
  7.     level = rt_hw_interrupt_disable();
     
  8.     if (completion->flag != RT_COMPLETED)
     
  9.     {
     
  10.         if (timeout == 0)
      
  11.         {
      
  12.         
      
  13.         }
      
  14.         else
      
  15.         {
      
  16.             /* reset thread error number */
      
  17.             thread->error = RT_EOK;
      
  18. 
      
  19.             /* suspend thread */
      
  20.             rt_thread_suspend(thread);
      
  21.             /* add to suspended list */
      
  22.             rt_list_insert_before(&(completion->suspended_list),
      
  23.                                   &(thread->tlist));
      
  24. 
      
  25.             /* current context checking */
      
  26.             RT_DEBUG_NOT_IN_INTERRUPT;
      
  27. 
      
  28.             /* start timer */
      
  29.             if (timeout > 0)
      
  30.             {
      
  31.                 /* reset the timeout of thread timer and start it */
      
  32.                 rt_timer_control(&(thread->thread_timer),
      
  33.                                  RT_TIMER_CTRL_SET_TIME,
      
  34.                                  &timeout);
      
  35.                 rt_timer_start(&(thread->thread_timer));
      
  36.             }
      
  37.             /* enable interrupt */
      
  38.             rt_hw_interrupt_enable(level);
      
  39. 
      
  40.             /* do schedule */
      
  41.             rt_schedule();
      
  42. 
      
  43.             /* thread is waked up */
      
  44.             result = thread->error;
      
  45. 
      
  46.             level = rt_hw_interrupt_disable();
      
  47.         }
      
  48.     }
      
  49.     /* clean completed flag */
      
  50.     completion->flag = RT_UNCOMPLETED;
      
  51. 
      
  52.     return result;
      
  53. }

  复制代码
  
  主要做了以下工作：
  
  • 关中断：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)
     
  2. {
     
  3.     level = rt_hw_interrupt_disable();
     
  4.     completion->flag = RT_COMPLETED;
     
  5. 
     
  6.     if (!rt_list_isempty(&(completion->suspended_list)))
     
  7.     {
     
  8.         /* there is one thread in suspended list */
     
  9.         struct rt_thread *thread;
     
  10. 
      
  11.         /* get thread entry */
      
  12.      thread = rt_list_entry(completion->suspended_list.next,
      
  13.                                struct rt_thread,
      
  14.                             tlist);
      
  15. 
      
  16.         /* resume it */
      
  17.         rt_thread_resume(thread);
      
  18.         rt_hw_interrupt_enable(level);
      
  19. 
      
  20.         /* perform a schedule */
      
  21.         rt_schedule();
      
  22.     }
      
  23. }

  复制代码
  
  
  
  主要做了以下工作：
  
  • 关中断：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 与信号量的对比

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

5. completion 如何加入工程

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