inc/FBaseRtEventDrivenThread.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                FBaseRtEventDrivenThread.h
  19  * @brief               This is the header file for the %EventDrivenThread class.
  20  *
  21  * This header file contains the declarations of the %EventDrivenThread class.
  22  */
  23 #ifndef _FBASE_RT_EVENT_DRIVEN_THREAD_H_
  24 #define _FBASE_RT_EVENT_DRIVEN_THREAD_H_
  25
  26
  27 #include <FBaseResult.h>
  28 #include <FBaseObject.h>
  29 #include <FBaseRtThread.h>
  30
  31 namespace Tizen { namespace Base { class String; }}
  32
  33 namespace Tizen { namespace Base { namespace Runtime
  34 {
  35
  36 /**
  37  * @class   EventDrivenThread
  38  * @brief               This class is the fundamental class for the asynchronous execution of a thread.
  39  *
  40  * @since 2.0
  41  *
  42  * The %EventDrivenThread class is the fundamental class for the asynchronous execution of a thread.
  43  * A %Tizen native application can execute several threads during its operation from the multi-threading view.
  44  *
  45  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/thread.htm">Thread</a>.
  46  *
  47  * @see Tizen::Base::Runtime::EventDrivenThread
  48  *
  49  * The following example demonstrates how to use the %EventDrivenThread class.
  50  *
  51  * @code
  52  *
  53  *   #include <FBase.h>
  54  *
  55  *   using namespace Tizen::Base;
  56  *   using namespace Tizen::Base::Runtime;
  57  *
  58  *   class MyTimerThread
  59  *      : public EventDrivenThread
  60  *      , public ITimerEventListener
  61  *   {
  62  *   public:
  63  *      MyTimerThread(void)
  64  *              : __pTimer(null)
  65  *              , __count(0)
  66  *      {
  67  *      }
  68  *
  69  *      virtual ~MyTimerThread(void)
  70  *      {
  71  *              delete __pTimer;
  72  *      }
  73  *
  74  *      result Construct(void)
  75  *      {
  76  *              return EventDrivenThread::Construct();
  77  *      }
  78  *
  79  *      bool OnStart(void)
  80  *      {
  81  *              __pTimer = new Timer;
  82  *
  83  *              __pTimer->Construct(*this);
  84  *
  85  *              __pTimer->StartAsRepeatable(1000);
  86  *
  87  *              return true;
  88  *      }
  89  *
  90  *      void OnStop(void)
  91  *      {
  92  *              __pTimer->Cancel();
  93  *      }
  94  *
  95  *      void OnTimerExpired(Timer& timer)
  96  *      {
  97  *              // Do repetitive tasks
  98  *              AppLog("MyTimerThread: OnTimerExpired: %d", __count++);
  99  *      }
 100  *
 101  *   private:
 102  *      Timer* __pTimer;
 103  *      int __count;
 104  *   };
 105  *
 106  *   void
 107  *   MyApplication::StartEventDrivenThreadSample(void)
 108  *   {
 109  *              __pMyTimerThread = new MyThread;
 110  *
 111  *              __pMyTimerThread->Construct();
 112  *
 113  *              __pMyTimerThread->Start();
 114  *
 115  *   }
 116  *
 117  *   void
 118  *   MyApplication::StopEventDrivenThreadSample(void)
 119  *   {
 120  *
 121  *              __pMyTimerThread->Quit();
 122  *
 123  *              __pMyTimerThread->Join();
 124  *
 125  *              delete __pMyTimerThread;
 126  *   }
 127  *
 128  * @endcode
 129  */
 130
 131 class _OSP_EXPORT_ EventDrivenThread
 132         : public Thread
 133 {
 134 public:
 135         /**
 136          * This is the default constructor for this class.
 137          *
 138          * @since 2.0
 139          *
 140          * @remarks     After creating an instance of this class, one of the
 141          *              Construct() methods must be called explicitly to initialize this instance.
 142          */
 143         EventDrivenThread(void);
 144
 145         /**
 146          * Initializes this instance of %EventDrivenThread with the specified thread type, stack size, and priority.
 147          *
 148          * @since 2.0
 149          *
 150          * @return      An error code
 151          * @param[in]   stackSize       The thread stack size
 152          * @param[in]   priority        The thread priority
 153          * @exception   E_SUCCESS       The method is successful.
 154          * @exception   E_INVALID_ARG   An invalid argument is passed.
 155          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 156          */
 157         result Construct(long stackSize = DEFAULT_STACK_SIZE, ThreadPriority priority = THREAD_PRIORITY_MID);
 158
 159         /**
 160          * Initializes this instance of %EventDrivenThread with the specified name, thread type, stack size, and priority.
 161          *
 162          * @since 2.0
 163          *
 164          * @return      An error code
 165          * @param[in]   name                    The name of the thread
 166          * @param[in]   stackSize       The thread stack size
 167          * @param[in]   priority        The thread priority
 168          * @exception   E_SUCCESS       The method is successful.
 169          * @exception   E_INVALID_ARG   An invalid argument is passed.
 170          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 171          */
 172         result Construct(const Tizen::Base::String& name, long stackSize = DEFAULT_STACK_SIZE, ThreadPriority priority = THREAD_PRIORITY_MID);
 173
 174         /**
 175          * This is the destructor for this class.
 176          *
 177          * @since 2.0
 178          *
 179          */
 180         virtual ~EventDrivenThread(void);
 181
 182         /**
 183          * Sends a termination request to the thread.
 184          *
 185          * @since 2.0
 186          *
 187          * @return      An error code
 188          * @exception   E_SUCCESS                       The method is successful.
 189          * @exception   E_INVALID_STATE                 The thread is in an invalid state.
 190          * @exception   E_SYSTEM                        A system error has occurred.
 191          */
 192         virtual result Quit(void);
 193
 194         /**
 195          * Called when the thread is started and runs a message loop.
 196          *
 197          * @since 2.0
 198          *
 199          * @final       Although this method is virtual, it must not be overridden.
 200          *              If overridden, it may not work as expected.
 201          *
 202          * @return      It is just ignored because there is nowhere to take the returned object
 203          * @remarks     The default action of this method returns @c null.
 204          */
 205         virtual Tizen::Base::Object* Run(void);
 206
 207         /**
 208          * Called before the message loop is started. @n
 209          * If this method returns @c false, the thread is terminated immediately.
 210          *
 211          * @since 2.0
 212          *
 213          * @return              @c true if this thread can be run, @n
 214          *                              else @c false
 215          * @remarks             You can initialize the event or event listener in this method for running this thread.
 216          *
 217          */
 218         virtual bool OnStart(void);
 219
 220         /**
 221          * Called after the message loop is stopped.
 222          *
 223          * @since 2.0
 224          *
 225          * @remarks     You can finalize the event or event listener in this method for running this thread.
 226          *
 227          */
 228         virtual void OnStop(void);
 229
 230         /**
 231          * Sends a user event to the event-driven thread.
 232          *
 233          * @since 2.0
 234          *
 235          * @final        Although this method is virtual, it must not be overridden.
 236          *               If overridden, it may not work as expected.
 237          *
 238          * @return       An error code
 239          * @param[in]    requestId       The user-defined event ID
 240          * @param[in]    pArgs           A pointer to a list of arguments
 241          * @exception    E_SUCCESS         The method is successful.
 242          * @exception    E_INVALID_STATE   The thread is in an invalid state.
 243          * @exception    E_OUT_OF_MEMORY The memory is insufficient.
 244          * @exception    E_SYSTEM          A system error has occurred.
 245          *
 246          * @see          OnUserEventReceivedN()
 247          */
 248         virtual result SendUserEvent(RequestId requestId, const Tizen::Base::Collection::IList* pArgs);
 249
 250         /**
 251          * Called when the user event is received.
 252          *
 253          * @since 2.0
 254          *
 255          * @param[in]    requestId       The user-defined event ID
 256          * @param[in]    pArgs           A pointer to a list of arguments
 257          *
 258          * @see          SendUserEvent()
 259          */
 260         virtual void OnUserEventReceivedN(RequestId requestId, Tizen::Base::Collection::IList* pArgs);
 261
 262 private:
 263         EventDrivenThread(const EventDrivenThread& rhs);
 264         EventDrivenThread& operator = (const EventDrivenThread& rhs);
 265
 266 private:
 267         class _EventDrivenThreadImpl* __pEventDrivenThreadImpl;
 268         friend class _EventDrivenThreadImpl;
 269
 270 }; // EventDrivenThread
 271
 272 } } } // Tizen::Base::Runtime
 273
 274 #endif // _FBASE_RT_EVENT_DRIVEN_THREAD_H_
 275