1/* ------------------------------------------------------------------
2 * Copyright (C) 1998-2009 PacketVideo
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
13 * express or implied.
14 * See the License for the specific language governing permissions
15 * and limitations under the License.
16 * -------------------------------------------------------------------
17 */
18// -*- c++ -*-
19// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
20
21//                  OSCL_T H R E A D (T H R E A D  I M P L E M E N T A T I O N)
22
23// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
24
25/*! \file oscl_thread.h .This file provides THREAD implementation that can be ported
26to three OS LINUX, SYMBIAN, WIN32
27*/
28
29
30// Definition file for OSCL Threads
31#ifndef OSCL_THREAD_H_INCLUDED
32#define OSCL_THREAD_H_INCLUDED
33
34#ifndef OSCLCONFIG_PROC_H_INCLUDED
35#include "osclconfig_proc.h"
36#endif
37
38#ifndef OSCL_PROCSTATUS_H_INCLUDED
39#include "oscl_procstatus.h"
40#endif
41
42#ifndef OSCL_BASE_H_INCLUDED
43#include "oscl_base.h"
44#endif
45
46
47// Thread state on creation
48enum OsclThread_State
49{
50    Start_on_creation
51    , Suspend_on_creation
52};
53
54// Enumerated Priority Values
55enum OsclThreadPriority
56{
57    ThreadPriorityLowest
58    , ThreadPriorityLow
59    , ThreadPriorityBelowNormal
60    , ThreadPriorityNormal
61    , ThreadPriorityAboveNormal
62    , ThreadPriorityHighest
63    , ThreadPriorityTimeCritical
64};
65
66//thread function pointer type.
67typedef TOsclThreadFuncRet(OSCL_THREAD_DECL *TOsclThreadFuncPtr)(TOsclThreadFuncArg);
68
69/**
70 * Thread Class.  A subset of Thread APIs.
71 * It implements platform independendent APIs for thread creation, exiting, suspend, resume, priority
72 * and termination. With the use of proper defines it implements the basic thread festures.
73 * It provides an opaque layer through which user doesn't need to worry about OS specific data.
74 */
75class OsclThread
76{
77
78    public:
79
80        /**
81         * Class constructor
82         */
83        OSCL_IMPORT_REF OsclThread();
84
85        /**
86         * Class destructor
87         */
88        OSCL_IMPORT_REF ~OsclThread();
89
90        /**
91         *  This routine will create a thread.  The thread may be
92         *   launched immediately or may be created in a suspended
93         *   state and launched with a Resume call.
94         *
95         * @param
96         * func  =  Name of the thread Function
97         * stack_size  =  Size of the thread stack.  If zero, then the
98         *    platform-specific default stack size will be used.
99         * argument = Argument to be passed to thread function
100         * state = Enumeration which specifies the state of the thread on creation
101         *        with values Running and Suspend.  Note: the Suspend option
102         *        may not be available on all platforms.  If it is not supported,
103         *        the Create call will return INVALID_PARAM_ERROR.
104         * @return eOsclProcError
105         */
106        OSCL_IMPORT_REF OsclProcStatus::eOsclProcError Create(TOsclThreadFuncPtr func,
107                int32 stack_size,
108                TOsclThreadFuncArg argument,
109                OsclThread_State state = Start_on_creation,
110                bool isJoinable = false);
111
112        /**
113         * Exit is a static function which is used to end the current thread. When called it
114         * just ends the execution of the current thread.
115         * @param
116         * exitcode  =  Exitcode of the thread. This can be used by other threads to know the
117         *              exit status of this thread.
118         * @return None
119         */
120        OSCL_IMPORT_REF static void Exit(OsclAny* exitcode);
121
122        /**
123         * EnableKill is a static function which can
124         *  be called by the thread routine in order to enable
125         *  thread termination without waiting for cancellation
126         *  points.
127         *  EnableKill only applies to pthread implementations.
128         *  For other implementations this function will do nothing.
129         *
130         * @return None
131         */
132        OSCL_IMPORT_REF static void EnableKill();
133
134        /**
135         * GetThreadPriority gets the priority of the thread. It takes reference of the input argument
136         * and assigns priority to it from one of the already defined priorities.
137         * @param
138         * int16& refThreadPriority : Output Priority value
139         * @return Error code
140         */
141        OSCL_IMPORT_REF OsclProcStatus::eOsclProcError GetPriority(OsclThreadPriority& refThreadPriority);
142
143        /**
144         * SetThreadPriority sets the priority of the thread. It takes priority as the input argument
145         * and assigns it to the thread referred.
146         * @param
147         * ePriorityLevel : Input Priority value
148         * @return Error code
149         * Note: this function may not be supported on all platforms, and
150         * may return NOT_IMPLEMENTED.
151         */
152        OSCL_IMPORT_REF OsclProcStatus::eOsclProcError SetPriority(OsclThreadPriority ePriority);
153
154        /**
155         * This API suspends the thread being referred. The thread can later be brought into execution
156         * by calling OSCL_ResumeThread() on it.
157         * @param None
158         * @return Error code
159         * Note: this function may not be supported on all platforms, and
160         * may return NOT_IMPLEMENTED.
161         */
162        OSCL_IMPORT_REF OsclProcStatus::eOsclProcError Suspend();
163
164        /**
165         * ResumeThread resumes the suspended thread and brings it into execution.
166         * @param None
167         * @return Error code
168         * Note: this function may not be supported on all platforms, and
169         * may return NOT_IMPLEMENTED.
170         */
171        OSCL_IMPORT_REF OsclProcStatus::eOsclProcError Resume();
172
173        /**
174         * Terminate a thread other than the calling thread.
175         *
176         * Note: for pthread implementations, the Terminate call will
177         *   block until the thread has terminated.  By default,
178         *   threads will not terminate until a cancellation point
179         *   is reached.  The EnableKill method may be used to override
180         *   this default behavior and allow immediate termination.
181         *
182         * @param
183         * exitcode  =  Exitcode of the thread.
184         * @return Error code
185         */
186        OSCL_IMPORT_REF OsclProcStatus::eOsclProcError Terminate(OsclAny* exitcode);
187
188
189        /**
190         * Static routine to retrieve ID of calling thread.
191         * @param Thread ID passed by the application
192         * @return Error code
193         */
194        OSCL_IMPORT_REF static OsclProcStatus::eOsclProcError GetId(TOsclThreadId& refThreadId);
195
196        /**
197         * Static routine to compare whether two thread ID's are equal.
198         * @param t1, t2: thread ID passed by the application
199         * @return true if equal.
200         */
201        OSCL_IMPORT_REF static bool CompareId(TOsclThreadId &t1, TOsclThreadId &t2);
202
203        /**
204         * Suspend current thread execution for specified time.
205         * @param msec, t2: sleep time in milliseconds.
206         */
207        OSCL_IMPORT_REF static void SleepMillisec(const int32 msec);
208
209    private:
210
211        /**
212         * Helper Function
213         * Map the Operating system errors to OSCL defined erros
214         * @param
215         * error : Input error as one of the OS errors
216         * @return Error code ( User defined )
217         */
218        OsclProcStatus::eOsclProcError MapOsclError(int16 error);
219
220
221        TOsclMutexObject mutex;
222        TOsclConditionObject  condition;
223        uint8 suspend;
224
225
226
227        TOsclThreadObject ObjThread;
228        bool bCreated;
229        bool iJoined;
230};
231
232#endif
233
234