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 26 to 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 48 enum OsclThread_State 49 { 50 Start_on_creation 51 , Suspend_on_creation 52 }; 53 54 // Enumerated Priority Values 55 enum OsclThreadPriority 56 { 57 ThreadPriorityLowest 58 , ThreadPriorityLow 59 , ThreadPriorityBelowNormal 60 , ThreadPriorityNormal 61 , ThreadPriorityAboveNormal 62 , ThreadPriorityHighest 63 , ThreadPriorityTimeCritical 64 }; 65 66 //thread function pointer type. 67 typedef 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 */ 75 class 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