inc/FBaseRtThread.h

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