third_party/ot-br-posix/repo/src/common/task_runner.hpp

   1 /*
   2  *    Copyright (c) 2021, The OpenThread Authors.
   3  *    All rights reserved.
   4  *
   5  *    Redistribution and use in source and binary forms, with or without
   6  *    modification, are permitted provided that the following conditions are met:
   7  *    1. Redistributions of source code must retain the above copyright
   8  *       notice, this list of conditions and the following disclaimer.
   9  *    2. Redistributions in binary form must reproduce the above copyright
  10  *       notice, this list of conditions and the following disclaimer in the
  11  *       documentation and/or other materials provided with the distribution.
  12  *    3. Neither the name of the copyright holder nor the
  13  *       names of its contributors may be used to endorse or promote products
  14  *       derived from this software without specific prior written permission.
  15  *
  16  *    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  17  *    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18  *    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19  *    ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
  20  *    LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  21  *    CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  22  *    SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  23  *    INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  24  *    CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  25  *    ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  26  *    POSSIBILITY OF SUCH DAMAGE.
  27  */
  28
  29 /**
  30  * @file
  31  * This file defines the Task Runner that executes tasks on the mainloop.
  32  */
  33
  34 #ifndef OTBR_COMMON_TASK_RUNNER_HPP_
  35 #define OTBR_COMMON_TASK_RUNNER_HPP_
  36
  37 #include <openthread-br/config.h>
  38
  39 #include <functional>
  40 #include <future>
  41 #include <mutex>
  42 #include <queue>
  43
  44 #include "common/mainloop.h"
  45
  46 namespace otbr {
  47
  48 /**
  49  * This class implements the Task Runner that executes
  50  * tasks on the mainloop.
  51  *
  52  */
  53 class TaskRunner
  54 {
  55 public:
  56     /**
  57      * This type represents the generic executable task.
  58      *
  59      */
  60     template <class T> using Task = std::function<T(void)>;
  61
  62     /**
  63      * This constructor initializes the Task Runner instance.
  64      *
  65      */
  66     TaskRunner(void);
  67
  68     /**
  69      * This destructor destroys the Task Runner instance.
  70      *
  71      */
  72     ~TaskRunner(void);
  73
  74     /**
  75      * This method posts a task to the task runner.
  76      *
  77      * Tasks are executed sequentially and follow the First-Come-First-Serve rule.
  78      * It is safe to call this method in different threads concurrently.
  79      *
  80      * @param[in]  aTask  The task to be executed.
  81      *
  82      */
  83     void Post(const Task<void> &aTask);
  84
  85     /**
  86      * This method posts a task and waits for the completion of the task.
  87      *
  88      * Tasks are executed sequentially and follow the First-Come-First-Serve rule.
  89      * This method must be called in a thread other than the mainloop thread. Otherwise,
  90      * the caller will be blocked forever.
  91      *
  92      * @returns  The result returned by the task @p aTask.
  93      *
  94      */
  95     template <class T> T PostAndWait(const Task<T> &aTask)
  96     {
  97         std::promise<T> pro;
  98
  99         Post([&]() { pro.set_value(aTask()); });
 100
 101         return pro.get_future().get();
 102     }
 103
 104     /**
 105      * This method updates the file descriptor and sets timeout for the mainloop.
 106      *
 107      * This method should only be called on the mainloop thread.
 108      *
 109      * @param[inout]  aMainloop  A reference to OpenThread mainloop context.
 110      *
 111      */
 112     void UpdateFdSet(otSysMainloopContext &aMainloop);
 113
 114     /**
 115      * This method processes events.
 116      *
 117      * This method should only be called on the mainloop thread.
 118      *
 119      * @param[in]  aMainloop  A reference to OpenThread mainloop context.
 120      *
 121      */
 122     void Process(const otSysMainloopContext &aMainloop);
 123
 124 private:
 125     enum
 126     {
 127         kRead  = 0,
 128         kWrite = 1,
 129     };
 130
 131     void PushTask(const Task<void> &aTask);
 132     void PopTasks(void);
 133
 134     // The event fds which are used to wakeup the mainloop
 135     // when there are pending tasks in the task queue.
 136     int mEventFd[2];
 137
 138     std::queue<Task<void>> mTaskQueue;
 139
 140     // The mutex which protects the `mTaskQueue` from being
 141     // simultaneously accessed by multiple threads.
 142     std::mutex mTaskQueueMutex;
 143 };
 144
 145 } // namespace otbr
 146
 147 #endif // OTBR_COMMON_TASK_RUNNER_HPP_