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// ---------------------------------------------------------------------------
36namespace android {
37// ---------------------------------------------------------------------------
38
39class Thread : virtual public RefBase
40{
41public:
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
79protected:
80    // exitPending() returns true if requestExit() has been called.
81            bool        exitPending() const;
82
83private:
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
91private:
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