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