inc/FBaseRtThread.h

   1 //
   2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   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 /**
  18  * @file                FBaseRtThread.h
  19  * @brief               This is the header file for the %Thread class.
  20  *
  21  * This header file contains the declarations of the %Thread class.
  22  */
  23 #ifndef _FBASE_RT_THREAD_H_
  24 #define _FBASE_RT_THREAD_H_
  25
  26
  27 #include <FBaseResult.h>
  28 #include <FBaseObject.h>
  29 #include <FBaseColIList.h>
  30 #include <FBaseColMultiHashMap.h>
  31 #include <FBaseColArrayList.h>
  32
  33 #include <FBaseRtMutex.h>
  34 #include <FBaseRtSemaphore.h>
  35 #include <FBaseRtMonitor.h>
  36 #include <FBaseRtIRunnable.h>
  37
  38
  39 #if defined(Yield)  // For preventing compile errors
  40 #undef Yield
  41 #endif
  42
  43 namespace Tizen { namespace Base { class String; }}
  44
  45 namespace Tizen { namespace Base { namespace Runtime
  46 {
  47
  48
  49 /**
  50  * @if OSPDEPREC
  51  * @enum ThreadType
  52  *
  53  * Defines the type of thread.
  54  *
  55  * @brief       <i> [Deprecated] </i>
  56  * @deprecated This enum is deprecated.
  57  *
  58  * @since 2.0
  59  *
  60  * @endif
  61  */
  62 enum ThreadType
  63 {
  64         THREAD_TYPE_WORKER = 0, /**< @if OSPDEPREC The worker thread mode @endif */
  65         THREAD_TYPE_EVENT_DRIVEN, /**< @if OSPDEPREC The event-driven thread mode @endif */
  66         THREAD_TYPE_MAIN                        // This enum value is for internal use only. Using this enum value can cause behavioral,
  67                                                                 // security-related, and consistency-related issues in the application.
  68                                                                 // The main thread mode
  69 };
  70
  71 /**
  72  * @enum ThreadPriority
  73  *
  74  * Defines the priority of the thread.
  75  *
  76  * @since 2.0
  77  *
  78  */
  79 enum ThreadPriority
  80 {
  81         THREAD_PRIORITY_HIGH, /**< The high priority*/
  82         THREAD_PRIORITY_MID, /**< The mid priority*/
  83         THREAD_PRIORITY_LOW, /**< The low priority*/
  84 };
  85
  86 /**
  87  * @class   Thread
  88  * @brief       This class is the fundamental class for the asynchronous execution of a thread.
  89  *
  90  * @since 2.0
  91  *
  92  * @remarks This class supports only worker threads. For event-driven threads, use the EventDrivenThread class.
  93  *
  94  * The %Thread class is the fundamental class for the asynchronous execution of a thread.
  95  * A Tizen native application can execute several threads during its operation from the multi-threading view.
  96  *
  97  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/thread.htm">Thread</a>.
  98  *
  99  * @see Tizen::Base::Runtime::EventDrivenThread
 100  *
 101  * The following example demonstrates how to use the %Thread class.
 102  *
 103  * @code
 104  *
 105  * using namespace Tizen::Base;
 106  * using namespace Tizen::Base::Runtime;
 107  *
 108  * class MyThread
 109  *  : public Thread
 110  * {
 111  *   public:
 112  *              MyThread(void)
 113  *              {
 114  *              }
 115  *
 116  *              virtual ~MyThread(void)
 117  *              {
 118  *              }
 119  *
 120  *              result Construct(void)
 121  *              {
 122  *                              return Thread::Construct();
 123  *              }
 124  *
 125  *              Object* Run(void)
 126  *              {
 127  *                              // Do some task...
 128  *                              return null;
 129  *              }
 130  * };
 131  *
 132  * void
 133  * MyApplication::ThreadSample(void)
 134  * {
 135  *              MyThread* pMyThread = new MyThread;
 136  *
 137  *              pMyThread->Construct();
 138  *
 139  *              pMyThread->Start();
 140  *
 141  *              pMyThread->Join(); // Waits until the thread finished the task
 142  *
 143  *              delete pMyThread;
 144  * }
 145  *
 146  * @endcode
 147  *
 148  */
 149
 150 class _OSP_EXPORT_ Thread
 151         : public Object
 152         , public Tizen::Base::Runtime::IRunnable
 153
 154 {
 155 public:
 156         /**
 157         * Default stack size of the thread.
 158         *
 159         * @since 2.0
 160         *
 161         */
 162         const static unsigned long DEFAULT_STACK_SIZE = 64 * 1024;
 163
 164 public:
 165         /**
 166          * Suspends the execution of the current thread for the specified interval.
 167          *
 168          * @since 2.0
 169          *
 170          * @return      An error code
 171          * @param[in]   milliSeconds    The time, in milliseconds, for which to suspend the execution @n
 172          *                              A value of zero causes the thread to relinquish the remainder of its time
 173          *                              slice to any other thread that is ready to run. The time cannot be negative.
 174          * @exception   E_SUCCESS       The method is successful.
 175          * @exception   E_INVALID_ARG   A negative time value is passed.
 176          */
 177         static result Sleep(long milliSeconds);
 178
 179         /**
 180          * Causes the current thread context to be temporarily paused and allows other threads to execute.
 181          *
 182          * @since 2.0
 183          *
 184          * @return      An error code
 185          * @exception   E_SUCCESS      The method is successful.
 186          * @exception   E_SYSTEM       A system error has occurred.
 187          */
 188         static result Yield(void);
 189
 190         /**
 191          * Ends a thread.
 192          * After this method is called, the thread's execution is stopped.
 193          *
 194          * @since 2.0
 195          *
 196          * @return      An error code
 197          * @param[in]   exitCode        The exit code for the thread @n
 198          * @exception   E_SUCCESS       The method is successful.
 199          * @remarks      Use GetExitCode() for getting the exit code set by this method.
 200          */
 201         static result Exit(int exitCode = 0x00);
 202
 203         /**
 204          * Gets the pointer of the currently running %Thread instance.
 205          *
 206          * @since 2.0
 207          *
 208          * @return      A pointer to the currently running thread
 209          */
 210         static Thread* GetCurrentThread(void);
 211
 212         /**
 213          * This is the default constructor for this class.
 214          *
 215          * @since 2.0
 216          *
 217          * @remarks             After creating an instance of this class, one of the
 218          *              Construct() methods must be called explicitly to initialize this instance.
 219          */
 220         Thread(void);
 221
 222         /**
 223          * @if OSPDEPREC
 224          * Initializes this instance of %Thread with the specified thread type, stack size, and priority.
 225          *
 226          * @brief       <i> [Deprecated] </i>
 227          * @deprecated This method is deprecated because the %Thread class does not support event-driven thread any more. Instead, use the EventDrivenThread class instead.
 228          *
 229          * @since 2.0
 230          *
 231          * @return      An error code
 232          * @param[in]   threadType      The thread type
 233          * @param[in]   stackSize       The thread stack size
 234          * @param[in]   priority        The thread priority
 235          * @exception   E_SUCCESS       The method is successful.
 236          * @exception   E_INVALID_ARG   An invalid argument is passed.
 237          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 238          * @endif
 239          */
 240         result Construct(ThreadType threadType, long stackSize = DEFAULT_STACK_SIZE, ThreadPriority priority = THREAD_PRIORITY_MID);
 241
 242         /**
 243          * @if OSPDEPREC
 244          * Initializes this instance of %Thread with the specified name, thread type, stack size, and priority.
 245          *
 246          * @brief       <i> [Deprecated] </i>
 247          * @deprecated This method is deprecated because the %Thread class does not support event-driven thread any more. Instead, use the EventDrivenThread class instead.
 248          *
 249          * @since 2.0
 250          *
 251          * @return      An error code
 252          * @param[in]   name            The name of the thread
 253          * @param[in]   threadType      The thread type
 254          * @param[in]   stackSize       The thread stack size
 255          * @param[in]   priority        The thread priority
 256          * @exception   E_SUCCESS       The method is successful.
 257          * @exception   E_INVALID_ARG   An invalid argument is passed.
 258          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 259          * @endif
 260          */
 261         result Construct(const Tizen::Base::String& name, ThreadType threadType,
 262                         long stackSize = DEFAULT_STACK_SIZE, ThreadPriority priority = THREAD_PRIORITY_MID);
 263
 264         /**
 265          * Initializes this instance of %Thread with the specified stack size, and priority.
 266          *
 267          * @since 2.0
 268          *
 269          * @return      An error code
 270          * @param[in]   stackSize       The thread stack size
 271          * @param[in]   priority        The thread priority
 272          * @exception   E_SUCCESS       The method is successful.
 273          * @exception   E_INVALID_ARG   An invalid argument is passed.
 274          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 275          */
 276         result Construct(long stackSize = DEFAULT_STACK_SIZE, ThreadPriority priority = THREAD_PRIORITY_MID);
 277
 278         /**
 279          * Initializes this instance of %Thread with the specified name, stack size, and priority.
 280          *
 281          * @since 2.0
 282          *
 283          * @return      An error code
 284          * @param[in]   name            The name of the thread
 285          * @param[in]   stackSize       The thread stack size
 286          * @param[in]   priority        The thread priority
 287          * @exception   E_SUCCESS       The method is successful.
 288          * @exception   E_INVALID_ARG   An invalid argument is passed.
 289          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 290          */
 291         result Construct(const Tizen::Base::String& name,
 292                 long stackSize = DEFAULT_STACK_SIZE, ThreadPriority priority = THREAD_PRIORITY_MID);
 293
 294         /**
 295          * Initializes this instance of %Thread with the specified IRunnable instance, stack size, and priority.
 296          *
 297          * @since 2.0
 298          *
 299          * @return      An error code
 300          * @param[in]   target          An instance of %IRunnable
 301          * @param[in]   stackSize       The thread stack size
 302          * @param[in]   priority        The thread priority
 303          * @exception   E_SUCCESS       The method is successful.
 304          * @exception   E_INVALID_ARG   An invalid argument is passed.
 305          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 306          */
 307         result Construct(IRunnable& target, long stackSize = DEFAULT_STACK_SIZE, ThreadPriority priority = THREAD_PRIORITY_MID);
 308
 309         /**
 310          * Initializes this instance of %Thread with the specified name, IRunnable instance, stack size, and priority.
 311          *
 312          * @since 2.0
 313          *
 314          * @return              An error code
 315          * @param[in]   name                    The name of the thread
 316          * @param[in]   target          An instance of IRunnable
 317          * @param[in]   stackSize       The thread stack size
 318          * @param[in]   priority        The thread priority
 319          * @exception   E_SUCCESS       The method is successful.
 320          * @exception   E_INVALID_ARG   An invalid argument is passed.
 321          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 322          */
 323         result Construct(const Tizen::Base::String& name, IRunnable& target,
 324                                          long stackSize = DEFAULT_STACK_SIZE, ThreadPriority priority = THREAD_PRIORITY_MID);
 325
 326
 327         /**
 328          * This is the destructor for this class.
 329          *
 330          * @since 2.0
 331          *
 332          */
 333         virtual ~Thread(void);
 334
 335         /**
 336          * Waits until the thread execution is terminated.
 337          *
 338          * @since 2.0
 339          *
 340          * @return      An error code
 341          * @exception   E_SUCCESS             The method is successful.
 342          * @exception   E_INVALID_OPERATION   An other thread is calling this method.
 343          * @exception   E_SYSTEM              A system error has occurred.
 344          */
 345         result Join(void);
 346
 347         /**
 348          * Starts the thread. @n
 349          * The Run() method is called when the thread starts.
 350          *
 351          * @since 2.0
 352          *
 353          * @return      An error code
 354          * @exception   E_SUCCESS              The method is successful.
 355          * @exception   E_SYSTEM               A system error has occurred.
 356          */
 357         result Start(void);
 358
 359         /**
 360          * @if OSPDEPREC
 361          * Forces the thread to stop executing.
 362          *
 363          * @brief       <i> [Deprecated] </i>
 364          * @deprecated This method is deprecated.
 365          *
 366          * @since 2.0
 367          *
 368          * @return      An error code
 369          * @exception   E_SUCCESS                       The method is successful.
 370          * @exception   E_SYSTEM                        A system error has occurred.
 371          * @remarks     This is only available for event-driven threads.
 372          * @endif
 373          */
 374         result Stop(void);
 375
 376         /**
 377          * Called when the thread is started without the IRunnable instance. @n
 378          * The body for thread execution is specified by inheriting the %Thread class and implementing this method.
 379          *
 380          * @since 2.0
 381          *
 382          * @return      It is just ignored because there is nowhere to take the returned object
 383          * @remarks     The default action of this method returns @c null.
 384          */
 385         virtual Tizen::Base::Object* Run(void);
 386
 387         /**
 388          * Gets an exit code of the thread which is given by calling the Exit() method.
 389          *
 390          * @since 2.0
 391          *
 392          * @return      An error code
 393          * @param[out]  exitCode               The exit code for the thread
 394          * @exception   E_SUCCESS              The method is successful.
 395          * @exception   E_INVALID_STATE        The thread is in an invalid state.
 396          * @exception   E_SYSTEM               A system error has occurred.
 397          */
 398         result GetExitCode(int& exitCode) const;
 399
 400         /**
 401          * Gets the name of the thread.
 402          *
 403          * @since 2.0
 404          *
 405          * @return      The name of the thread
 406          * @exception   E_SUCCESS                       The method is successful.
 407          */
 408         const Tizen::Base::String& GetName(void) const;
 409
 410
 411         /**
 412          * @if OSPDEPREC
 413          * Called before the Run() method is executed. @n
 414          * The Run() method is executed if this method returns @c true, and @n
 415          * if this method returns @c false, the thread is terminated immediately.
 416          *
 417          * @brief       <i> [Deprecated] </i>
 418          * @deprecated This method is deprecated because the %Thread class does not support event-driven threads.
 419          *
 420          * @since 2.0
 421          *
 422          * @return              @c true if this thread can be run, @n
 423          *                              else @c false
 424          * @remarks             You can initialize the event or event listener in this method for running this
 425          *                      thread in an event-driven mode.
 426          * @endif
 427          */
 428         virtual bool OnStart(void);
 429
 430         /**
 431          * @if OSPDEPREC
 432          * Called after the Run() method is executed.
 433          *
 434          * @brief       <i> [Deprecated] </i>
 435          * @deprecated This method is deprecated because the %Thread class does not support event-driven threads.
 436          * @since 2.0
 437          *
 438          * @remarks     You can finalize the event or event listener in this method for running this
 439          *              thread in an event-driven mode.
 440          *
 441          * @endif
 442          */
 443         virtual void OnStop(void);
 444
 445         /**
 446          * @if OSPDEPREC
 447          * Sends a user event to the event-driven thread.
 448          *
 449          * @brief       <i> [Deprecated] </i>
 450          * @deprecated This method is deprecated because the %Thread class does not support event-driven threads.
 451          *
 452          * @since 2.0
 453          *
 454          * @return       An error code
 455          * @param[in]    requestId            The user-defined event Id
 456          * @param[in]    pArgs                A pointer to a list of arguments
 457          * @exception    E_SUCCESS            The method is successful.
 458          * @exception    E_INVALID_OPERATION  The thread is not an event-driven thread.
 459          *
 460          * @remarks     This is only available for event-driven threads.
 461          * @see         OnUserEventReceivedN()
 462          * @endif
 463          */
 464         virtual result SendUserEvent(RequestId requestId, const Tizen::Base::Collection::IList* pArgs);
 465
 466         /**
 467          * @if OSPDEPREC
 468          * Called when the user event is received.
 469          *
 470          * @brief       <i> [Deprecated] </i>
 471          * @deprecated This method is deprecated because the %Thread class does not support event-driven threads.
 472          *
 473          * @since 2.0
 474          *
 475          * @param[in]    requestId       The user-defined event Id
 476          * @param[in]    pArgs           A pointer to a list of arguments
 477          * @see          SendUserEvent()
 478          * @endif
 479          */
 480         virtual void OnUserEventReceivedN(RequestId requestId, Tizen::Base::Collection::IList* pArgs);
 481
 482 private:
 483         Thread(const Thread& rhs);
 484         Thread& operator =(const Thread& rhs);
 485
 486 private:
 487         friend class _ThreadImpl;
 488         class _ThreadImpl* __pThreadImpl;
 489 }; // Thread
 490
 491 } } } // Tizen::Base::Runtime
 492
 493 #endif // _FBASE_RT_THREAD_H_
 494