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 /*! \addtogroup osclproc OSCL Proc 19 * 20 * @{ 21 */ 22 23 24 /** \file oscl_scheduler_ao.h 25 \brief Oscl Scheduler user execution object classes. 26 */ 27 28 29 #ifndef OSCL_SCHEDULER_AO_H_INCLUDED 30 #define OSCL_SCHEDULER_AO_H_INCLUDED 31 32 #ifndef OSCL_SCHEDULER_TYPES_H_INCLUDED 33 #include "oscl_scheduler_types.h" 34 #endif 35 36 #ifndef OSCL_SCHEDULER_AOBASE_H_INCLUDED 37 #include "oscl_scheduler_aobase.h" 38 #endif 39 40 #ifndef OSCL_MEM_H_INCLUDED 41 #include "oscl_mem.h" 42 #endif 43 44 /** 45 * User base class for execution objects. 46 * OsclActiveObject defines an execution object without any timer. 47 * This AO can be used across threads, i.e. the request 48 * can be activated in one thread and completed in another. 49 */ 50 class OsclActiveObject: 51 public HeapBase, 52 public PVActiveBase 53 { 54 public: 55 /** 56 * Scheduling priorities. 57 */ 58 enum OsclActivePriority 59 { 60 /** 61 A low priority, useful for execution objects representing 62 background processing. 63 */ 64 EPriorityIdle = -100, 65 /** 66 A priority higher than EPriorityIdle but lower than EPriorityNominal. 67 */ 68 EPriorityLow = -20, 69 /** 70 Most exec objects will have this priority. 71 */ 72 EPriorityNominal = 0, 73 /** 74 A priority higher than EPriorityNominal; useful for execution objects 75 handling user input. 76 */ 77 EPriorityHigh = 10, 78 /** 79 A priority higher than EPriorityHighest. 80 */ 81 EPriorityHighest = 20, 82 }; 83 84 /** 85 * Constructor. 86 * @param aPriority (input param): scheduling priority 87 * @param name (inpup param): optional name for this AO. 88 */ 89 OSCL_IMPORT_REF OsclActiveObject(int32 aPriority, const char name[]); 90 91 /** 92 * Destructor. 93 */ 94 OSCL_IMPORT_REF virtual ~OsclActiveObject(); 95 96 97 /** 98 * Set object ready for this AO, 99 * additionally sets the request status to OSCL_REQUEST_PENDING. 100 * Will leave if the request is already readied, 101 * or the execution object is not added to any scheduler, 102 * or the calling thread context does not match 103 * the scheduler thread. 104 */ 105 OSCL_IMPORT_REF void SetBusy(); 106 107 /** 108 * Return true if this AO is pending, 109 * false otherwise. 110 */ 111 OSCL_IMPORT_REF bool IsBusy() const; 112 113 /** 114 * Set request active for this AO and set the status to pending. 115 * PendForExec is identical to SetActive, but it 116 * additionally sets the request status to OSCL_REQUEST_PENDING. 117 */ 118 OSCL_IMPORT_REF void PendForExec(); 119 120 /** 121 * Complete the active request for the AO. 122 * This API is thread-safe. 123 * If the request is not pending, this call will leave. 124 * @param aStatus: request completion status. 125 */ 126 OSCL_IMPORT_REF void PendComplete(int32 aStatus); 127 128 /** 129 * Add this exec object to the current thread's scheduler. 130 */ 131 OSCL_IMPORT_REF void AddToScheduler(); 132 133 /** 134 * Remove this AO from its scheduler. 135 * Will leave if the calling thread context does 136 * not match the scheduling thread. 137 * Cancels any readied request before removing. 138 */ 139 OSCL_IMPORT_REF void RemoveFromScheduler(); 140 141 142 /** 143 * Complete this AO's request immediately. 144 * If the AO is already active, this will do nothing. 145 * Will leave if the AO is not added to any scheduler, 146 * or if the calling thread context does not match the 147 * scheduling thread. 148 */ 149 OSCL_IMPORT_REF void RunIfNotReady(); 150 151 /** 152 * Cancel any pending request. 153 * If the request is readied, this will call the DoCancel 154 * routine, wait for the request to cancel, then set the 155 * request idle. The AO will not run. 156 * If the request is not readied, it does nothing. 157 * Request must be canceled from the same thread 158 * in which it is scheduled. 159 */ 160 OSCL_IMPORT_REF void Cancel(); 161 162 163 /** 164 * Return scheduling priority of this exec object. 165 */ 166 OSCL_IMPORT_REF int32 Priority() const; 167 168 /** 169 * Request status access 170 */ 171 OSCL_IMPORT_REF int32 Status()const; 172 OSCL_IMPORT_REF void SetStatus(int32); 173 OSCL_IMPORT_REF OsclAOStatus& StatusRef(); 174 175 protected: 176 /** 177 * Cancel request handler. 178 * This gets called by scheduler when the request 179 * is cancelled. The default routine will complete 180 * the request. If any additional action is needed, 181 * the derived class may override this. If the derived class 182 * does override DoCancel, it must complete the request. 183 */ 184 OSCL_IMPORT_REF virtual void DoCancel(); 185 186 /** 187 * Run Error handler. 188 * This gets called by scheduler when the Run routine leaves. 189 * The default implementation simply returns the leave code. 190 * If the derived class wants to handle errors from Run, 191 * it may override this. The RunError should return OsclErrNone 192 * if it handles the error, otherwise it should return the 193 * input error code. 194 * @param aError: the leave code generated by the Run. 195 */ 196 OSCL_IMPORT_REF virtual int32 RunError(int32 aError); 197 198 }; 199 200 /** 201 * User base class for execution objects. 202 * OsclTimerObject defines an exec object with a timer. 203 204 */ 205 class OsclTimerObject: public HeapBase 206 , public PVActiveBase 207 { 208 public: 209 /** 210 * Constructor. 211 * @param aPriority (input param): scheduling priority 212 * @param name (input param): optional name for this AO. 213 */ 214 OSCL_IMPORT_REF OsclTimerObject(int32 aPriority, const char name[]); 215 216 /** 217 * Destructor. 218 */ 219 OSCL_IMPORT_REF virtual ~OsclTimerObject(); 220 221 /** 222 * Add this AO to the current thread's scheduler. 223 */ 224 OSCL_IMPORT_REF void AddToScheduler(); 225 226 227 /** 228 * Remove this AO from its scheduler. 229 * Will leave if the calling thread context does 230 * not match the scheduling thread. 231 * Cancels any pending request before removing. 232 */ 233 OSCL_IMPORT_REF void RemoveFromScheduler(); 234 235 236 /** 237 * 'After' sets the request ready, with request status 238 * OSCL_REQUEST_STATUS_PENDING, and starts a timer. 239 * When the timer expires, the request will complete with 240 * status OSCL_REQUEST_ERR_NONE. 241 * Must be called from the same thread in which the 242 * active object is scheduled. 243 * Will leave if the request is already readied, the object 244 * is not added to any scheduler, or the calling thread 245 * does not match the scheduling thread. 246 * @param anInterval: timeout interval in microseconds. 247 */ 248 OSCL_IMPORT_REF void After(int32 aDelayMicrosec); 249 250 /** 251 * Complete the request after a time interval. 252 * RunIfNotReady is identical to After() except that it 253 * first checks the request status, and if it is already 254 * readied, it does nothing. 255 * 256 * @param aDelayMicrosec (input param): delay in microseconds. 257 */ 258 OSCL_IMPORT_REF void RunIfNotReady(uint32 aDelayMicrosec = 0); 259 260 /** 261 * Set request ready for this AO. 262 * Will leave if the request is already readied, 263 * or the exec object is not added to any scheduler, 264 * or the calling thread context does not match 265 * the scheduler thread. 266 */ 267 OSCL_IMPORT_REF void SetBusy(); 268 269 /** 270 * Return true if this AO is active, 271 * false otherwise. 272 */ 273 OSCL_IMPORT_REF bool IsBusy() const; 274 275 /** 276 * Cancel any active request. 277 * If the request is pending, this will call the DoCancel 278 * routine, wait for the request to cancel, then set the 279 * request idle. The AO will not run. 280 * If the request is not active, it does nothing. 281 * Request must be canceled from the same thread 282 * in which it is scheduled. 283 */ 284 OSCL_IMPORT_REF void Cancel(); 285 286 /** 287 * Return scheduling priority of this exec object. 288 */ 289 OSCL_IMPORT_REF int32 Priority() const; 290 /** 291 * Request status access 292 */ 293 OSCL_IMPORT_REF int32 Status()const; 294 OSCL_IMPORT_REF void SetStatus(int32); 295 OSCL_IMPORT_REF OsclAOStatus& StatusRef(); 296 297 protected: 298 /** 299 * Cancel request handler. 300 * This gets called by scheduler when the request 301 * is cancelled. The default routine will cancel 302 * the timer. If any additional action is needed, 303 * the derived class may override this. If the 304 * derived class does override this, it should explicitly 305 * call OsclTimerObject::DoCancel in its own DoCancel 306 * routine. 307 */ 308 OSCL_IMPORT_REF virtual void DoCancel(); 309 310 /** 311 * Run Leave handler. 312 * This gets called by scheduler when the Run routine leaves. 313 * The default implementation simply returns the leave code. 314 * If the derived class wants to handle errors from Run, 315 * it may override this. The ExecError should return OsclErrNone 316 * if it handles the error, otherwise it should return the 317 * input error code. 318 * @param aError: the leave code generated by the Run. 319 */ 320 OSCL_IMPORT_REF virtual int32 RunError(int32 aError); 321 }; 322 323 324 #endif 325 326 /*! @} */ 327
