common/message_loop_thread.h

   1 /*
   2  * Copyright 2018 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #pragma once
  18
  19 #include <unistd.h>
  20 #include <future>
  21 #include <memory>
  22 #include <string>
  23 #include <thread>
  24
  25 #include <base/bind.h>
  26 #include <base/location.h>
  27 #include <base/message_loop/message_loop.h>
  28 #include <base/run_loop.h>
  29 #include <base/threading/platform_thread.h>
  30
  31 namespace bluetooth {
  32
  33 namespace common {
  34
  35 /**
  36  * An interface to various thread related functionality
  37  */
  38 class MessageLoopThread final {
  39  public:
  40   /**
  41    * Create a message loop thread with name. Thread won't be running until
  42    * StartUp is called.
  43    *
  44    * @param thread_name name of this worker thread
  45    */
  46   explicit MessageLoopThread(const std::string& thread_name);
  47
  48   /**
  49    * Destroys the message loop thread automatically when it goes out of scope
  50    */
  51   ~MessageLoopThread();
  52
  53   /**
  54    * Start the underlying thread. Blocks until all thread infrastructure is
  55    * setup. IsRunning() and DoInThread() should return true after this call.
  56    * Blocks until the thread is successfully started.
  57    *
  58    * Repeated call to this method will only start this thread once
  59    */
  60   void StartUp();
  61
  62   /**
  63    * Post a task to run on this thread
  64    *
  65    * @param from_here location where this task is originated
  66    * @param task task created through base::Bind()
  67    * @return true if task is successfully scheduled, false if task cannot be
  68    * scheduled
  69    */
  70   bool DoInThread(const base::Location& from_here, base::OnceClosure task);
  71
  72   /**
  73    * Shutdown the current thread as if it is never started. IsRunning() and
  74    * DoInThread() will return false after this call. Blocks until the thread is
  75    * joined and freed. This thread can be re-started again using StartUp()
  76    *
  77    * Repeated call to this method will only stop this thread once
  78    *
  79    * NOTE: Should never be called on the thread itself to avoid deadlock
  80    */
  81   void ShutDown();
  82
  83   /**
  84    * Get the current thread ID returned by PlatformThread::CurrentId()
  85    *
  86    * On Android platform, this value should be the same as the tid logged by
  87    * logcat, which is returned by gettid(). On other platform, this thread id
  88    * may have different meanings. Therefore, this ID is only good for logging
  89    * and thread comparison purpose
  90    *
  91    * @return this thread's ID
  92    */
  93   base::PlatformThreadId GetThreadId() const;
  94
  95   /**
  96    * Get this thread's name set in constructor
  97    *
  98    * @return this thread's name set in constructor
  99    */
 100   std::string GetName() const;
 101
 102   /**
 103    * Get a string representation of this thread
 104    *
 105    * @return a string representation of this thread
 106    */
 107   std::string ToString() const;
 108
 109   /**
 110    * Check if this thread is running
 111    *
 112    * @return true iff this thread is running and is able to do task
 113    */
 114   bool IsRunning() const;
 115
 116   /**
 117    * Attempt to make scheduling for this thread real time
 118    *
 119    * @return true on success, false otherwise
 120    */
 121   bool EnableRealTimeScheduling();
 122
 123   /**
 124    * Return the weak pointer to this object. This can be useful when posting
 125    * delayed tasks to this MessageLoopThread using Timer.
 126    */
 127   base::WeakPtr<MessageLoopThread> GetWeakPtr();
 128
 129   /**
 130    * Return the message loop for this thread. Accessing raw message loop is not
 131    * recommended as message loop can be freed internally.
 132    *
 133    * @return message loop associated with this thread, nullptr if thread is not
 134    * running
 135    */
 136   base::MessageLoop* message_loop() const;
 137
 138  private:
 139   /**
 140    * Static method to run the thread
 141    *
 142    * This is used instead of a C++ lambda because of the use of std::shared_ptr
 143    *
 144    * @param context needs to be a pointer to an instance of MessageLoopThread
 145    * @param start_up_promise a std::promise that is used to notify calling
 146    * thread the completion of message loop start-up
 147    */
 148   static void RunThread(MessageLoopThread* context,
 149                         std::promise<void> start_up_promise);
 150
 151   /**
 152    * Post a task to run on this thread after a specified delay. If the task
 153    * needs to be cancelable before it's run, use base::CancelableClosure type
 154    * for task closure. For example:
 155    * <code>
 156    * base::CancelableClosure cancelable_task;
 157    * cancelable_task.Reset(base::Bind(...)); // bind the task
 158    * same_thread->DoInThreadDelayed(FROM_HERE,
 159    *                                cancelable_task.callback(), delay);
 160    * ...
 161    * // Cancel the task closure
 162    * same_thread->DoInThread(FROM_HERE,
 163    *                         base::Bind(&base::CancelableClosure::Cancel,
 164    *                                    base::Unretained(&cancelable_task)));
 165    * </code>
 166    *
 167    * Warning: base::CancelableClosure objects must be created on, posted to,
 168    * cancelled on, and destroyed on the same thread.
 169    *
 170    * @param from_here location where this task is originated
 171    * @param task task created through base::Bind()
 172    * @param delay delay for the task to be executed
 173    * @return true if task is successfully scheduled, false if task cannot be
 174    * scheduled
 175    */
 176   bool DoInThreadDelayed(const base::Location& from_here,
 177                          base::OnceClosure task, const base::TimeDelta& delay);
 178
 179   friend class RepeatingTimer;  // allow Timer to use DoInThreadDelayed()
 180   friend class OnceTimer;       // allow OnceTimer to use DoInThreadDelayed()
 181
 182   /**
 183    * Actual method to run the thread, blocking until ShutDown() is called
 184    *
 185    * @param start_up_promise a std::promise that is used to notify calling
 186    * thread the completion of message loop start-up
 187    */
 188   void Run(std::promise<void> start_up_promise);
 189
 190   mutable std::recursive_mutex api_mutex_;
 191   const std::string thread_name_;
 192   base::MessageLoop* message_loop_;
 193   base::RunLoop* run_loop_;
 194   std::thread* thread_;
 195   base::PlatformThreadId thread_id_;
 196   // Linux specific abstractions
 197   pid_t linux_tid_;
 198   base::WeakPtrFactory<MessageLoopThread> weak_ptr_factory_;
 199   bool shutting_down_;
 200
 201   DISALLOW_COPY_AND_ASSIGN(MessageLoopThread);
 202 };
 203
 204 inline std::ostream& operator<<(std::ostream& os,
 205                                 const bluetooth::common::MessageLoopThread& a) {
 206   os << a.ToString();
 207   return os;
 208 }
 209
 210 }  // namespace common
 211
 212 }  // namespace bluetooth