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