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          *                              The value of zero causes the thread to relinquish the remainder of its time
 173          *                              slice to any other thread that is ready to run @n
 174      *                                                          The time cannot be negative.
 175          * @exception   E_SUCCESS       The method is successful.
 176          * @exception   E_INVALID_ARG   A negative time value has been 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 a 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 threads any more. Instead, use the EventDrivenThread class.
 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   A specified input parameter is invalid.
 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 threads any more. Instead, use the EventDrivenThread class.
 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   A specified input parameter is invalid.
 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   A specified input parameter is invalid.
 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   A specified input parameter is invalid.
 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   A specified input parameter is invalid.
 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   A specified input parameter is invalid.
 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          * Joins after 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   Another 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 the 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 the 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             The event or event listener in this method can be initialized 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     The event or event listener in this method can be finalized 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 the 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 the 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