adds % before Tizen
[platform/framework/native/appfw.git] / 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