include/utils/Thread.h

   1 /*
   2  * Copyright (C) 2007 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 #ifndef _LIBS_UTILS_THREAD_H
  18 #define _LIBS_UTILS_THREAD_H
  19
  20 #include <stdint.h>
  21 #include <sys/types.h>
  22 #include <time.h>
  23
  24 #if defined(HAVE_PTHREADS)
  25 # include <pthread.h>
  26 #endif
  27
  28 #include <utils/Condition.h>
  29 #include <utils/Errors.h>
  30 #include <utils/Mutex.h>
  31 #include <utils/RefBase.h>
  32 #include <utils/Timers.h>
  33 #include <utils/ThreadDefs.h>
  34
  35 // ---------------------------------------------------------------------------
  36 namespace android {
  37 // ---------------------------------------------------------------------------
  38
  39 class Thread : virtual public RefBase
  40 {
  41 public:
  42     // Create a Thread object, but doesn't create or start the associated
  43     // thread. See the run() method.
  44                         Thread(bool canCallJava = true);
  45     virtual             ~Thread();
  46
  47     // Start the thread in threadLoop() which needs to be implemented.
  48     virtual status_t    run(    const char* name = 0,
  49                                 int32_t priority = PRIORITY_DEFAULT,
  50                                 size_t stack = 0);
  51
  52     // Ask this object's thread to exit. This function is asynchronous, when the
  53     // function returns the thread might still be running. Of course, this
  54     // function can be called from a different thread.
  55     virtual void        requestExit();
  56
  57     // Good place to do one-time initializations
  58     virtual status_t    readyToRun();
  59
  60     // Call requestExit() and wait until this object's thread exits.
  61     // BE VERY CAREFUL of deadlocks. In particular, it would be silly to call
  62     // this function from this object's thread. Will return WOULD_BLOCK in
  63     // that case.
  64             status_t    requestExitAndWait();
  65
  66     // Wait until this object's thread exits. Returns immediately if not yet running.
  67     // Do not call from this object's thread; will return WOULD_BLOCK in that case.
  68             status_t    join();
  69
  70     // Indicates whether this thread is running or not.
  71             bool        isRunning() const;
  72
  73 #ifdef HAVE_ANDROID_OS
  74     // Return the thread's kernel ID, same as the thread itself calling gettid() or
  75     // androidGetTid(), or -1 if the thread is not running.
  76             pid_t       getTid() const;
  77 #endif
  78
  79 protected:
  80     // exitPending() returns true if requestExit() has been called.
  81             bool        exitPending() const;
  82
  83 private:
  84     // Derived class must implement threadLoop(). The thread starts its life
  85     // here. There are two ways of using the Thread object:
  86     // 1) loop: if threadLoop() returns true, it will be called again if
  87     //          requestExit() wasn't called.
  88     // 2) once: if threadLoop() returns false, the thread will exit upon return.
  89     virtual bool        threadLoop() = 0;
  90
  91 private:
  92     Thread& operator=(const Thread&);
  93     static  int             _threadLoop(void* user);
  94     const   bool            mCanCallJava;
  95     // always hold mLock when reading or writing
  96             thread_id_t     mThread;
  97     mutable Mutex           mLock;
  98             Condition       mThreadExitedCondition;
  99             status_t        mStatus;
 100     // note that all accesses of mExitPending and mRunning need to hold mLock
 101     volatile bool           mExitPending;
 102     volatile bool           mRunning;
 103             sp<Thread>      mHoldSelf;
 104 #ifdef HAVE_ANDROID_OS
 105     // legacy for debugging, not used by getTid() as it is set by the child thread
 106     // and so is not initialized until the child reaches that point
 107             pid_t           mTid;
 108 #endif
 109 };
 110
 111
 112 }; // namespace android
 113
 114 // ---------------------------------------------------------------------------
 115 #endif // _LIBS_UTILS_THREAD_H
 116 // ---------------------------------------------------------------------------