Home | History | Annotate | Download | only in utils
      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(_WIN32)
     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(),
     75     // 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 // ---------------------------------------------------------------------------
    117