2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
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
9 // http://www.apache.org/licenses/LICENSE-2.0
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.
19 * @file FBaseRtMonitor.h
20 * @brief This is the header file for the %Monitor class.
22 * This header file contains the declarations of the %Monitor class.
25 #ifndef _FBASE_RT_MONITOR_H_
26 #define _FBASE_RT_MONITOR_H_
28 #include <FBaseResult.h>
29 #include <FBaseObject.h>
32 namespace Tizen { namespace Base { namespace Runtime
39 * @brief This represents a monitor; a type of synchronization mechanism that provides acquire/release semantics by Enter() / Exit() as well as wait/notify semantics by Wait() / Notify() / NotifyAll().
43 * @final This class is not intended for extension.
45 * The %Monitor class represents a monitor. %Monitor is a synchronization mechanism that provides acquire/release semantics by Enter() / Exit() as well as wait/notify semantics by Wait() / Notify() / NotifyAll().
47 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/monitor.htm">Monitor</a>.
49 * The following examples demonstrates how to use the %Monitor class. In the examples, 2 classes, Consumer and Producer, share a space.
50 * Producer writes some data to this space, and Consumer reads it. Consumer and Producer run simultaneously.
51 * Consumer must not miss the data which Producer writes. In this case, Consumer and Producer share the monitor.
52 * Producer notifies Consumer that its writing action is done. Consumer waits for this notification, and reads the data after receiving it.
58 * using namespace Tizen::Base;
59 * using namespace Tizen::Base::Runtime;
66 * // This methods creates a new instance of the Producer thread
67 * Producer(int* pShared, Monitor* pMonitor);
68 * virtual ~Producer(void);
70 * // This methods waits for a starting Consumer and sets a value to the shared position
71 * // Finally it notifies the Consumer thread
72 * virtual Object* Run(void);
76 * Monitor* __pMonitor;
79 * Producer::Producer(int* pShared, Monitor* pMonitor)
80 * : __pShared(pShared)
81 * , __pMonitor(pMonitor)
85 * Producer::~Producer(void)
92 * if (__pShared && __pMonitor)
94 * // Begins a critical region
95 * result r = __pMonitor->Enter();
101 * // Waits for a starting Consumer
102 * r = __pMonitor->Wait();
108 * // Produces a number value 6 times
109 * for (int i = 0; i < 6; i++)
113 * // Notifies the consumer thread
114 * r = __pMonitor->Notify();
120 * AppLog("Producer::Run [%d]: Value at shared resource: %d\n", i, *__pShared);
121 * if (*__pShared == 5)
126 * // Waits until the consumer thread reads the value
127 * r = __pMonitor->Wait();
131 * __pMonitor->Exit();
143 * // This methods creates a new instance of the Consumer thread
144 * Consumer(int* pShared, Monitor* pMonitor);
145 * virtual ~Consumer(void);
147 * // This methods waits for a notification from the Producer thread and reads a value From the shared position
148 * virtual Tizen::Base::Object* Run(void);
152 * Monitor* __pMonitor;
156 * Consumer::Consumer(int* pShared, Monitor* pMonitor)
157 * : __pShared(pShared)
158 * , __pMonitor(pMonitor)
162 * Consumer::~Consumer(void)
167 * Consumer::Run(void)
169 * if (__pShared &&__pMonitor)
171 * // Begins a critical region
172 * result r = __pMonitor->Enter();
178 * // Notifies the producer thread
179 * r = __pMonitor->Notify();
185 * // Waits for a notification
186 * r = __pMonitor->Wait();
187 * while (!IsFailed(r))
189 * // Notifies the producer thread
190 * r = __pMonitor->Notify();
196 * AppLog("Consumer::Run: Value at shared resource: %d\n", *__pShared);
197 * if (*__pShared == 5)
202 * // Waits for a notification
203 * r = __pMonitor->Wait();
211 * // Exits the monitor
212 * r = __pMonitor->Exit();
220 * MyApp::TestProducerConsumer(void)
222 * result r = E_SUCCESS;
223 * Monitor* pMonitor = null;
224 * int* pShared = null;
226 * pMonitor = new Monitor;
229 * r = pMonitor->Construct();
232 * AppLog("Failed at Monitor Construct\n");
239 * Producer producer(pShared, pMonitor);
240 * Consumer consumer(pShared, pMonitor);
242 * producer.Construct();
243 * consumer.Construct();
262 class _OSP_EXPORT_ Monitor
263 : public Tizen::Base::Object
267 * This is the default constructor for this class.
271 * @remarks After creating an instance of this class, one of the
272 * Construct() methods must be called explicitly to initialize this instance.
278 * This is the destructor for this class.
282 virtual ~Monitor(void);
286 * Initializes this instance of %Monitor.
290 * @return An error code
291 * @exception E_SUCCESS The method is successful.
292 * @exception E_OUT_OF_MEMORY The memory is insufficient.
293 * @exception E_SYSTEM A system error has occurred.
295 result Construct(void);
298 * Acquires a lock for a monitor. @n
299 * Semantically, this method declares the beginning of the critical region for the monitor. This region
300 * ends with the Exit() method.
304 * @return An error code
305 * @exception E_SUCCESS The method is successful in acquiring the lock.
306 * @exception E_SYSTEM A system error has occurred.
307 * @remarks This method will block if called on already locked monitor object until monitor becomes availalbe.
314 * Releases a lock for a monitor. @n
315 * Semantically, it declares the ending of the critical region for the monitor that begins with
316 * the Enter() method.
320 * @return An error code
321 * @exception E_SUCCESS The method is successful in releasing the lock.
322 * @exception E_SYSTEM A system error has occurred.
323 * @remarks This method should be called only after acquiring lock by Enter() call
329 * Releases the lock for the monitor and waits for the notification from the other thread. @n
330 * After receiving the notification, it tries to acquire the lock.
331 * Semantically, it waits until the other thread notifies it.
335 * @return An error code
336 * @exception E_SUCCESS The method is successful.
337 * @exception E_SYSTEM A system error has occurred.
338 * @remarks This method should be called only after acquiring lock by Enter() call
345 * Notifies one of the waiting threads. @n
346 * The selection of the notified thread is determined by the Linux scheduling policy.
350 * @return An error code
351 * @exception E_SUCCESS The method is successful.
352 * @exception E_SYSTEM A system error has occurred.
360 * Notifies all waiting threads.
364 * @return An error code
365 * @exception E_SUCCESS The method is successful.
366 * @exception E_SYSTEM A system error has occurred.
370 result NotifyAll(void);
373 Monitor(const Monitor& rhs);
374 Monitor& operator =(const Monitor& rhs);
377 friend class _MonitorImpl;
378 class _MonitorImpl * __pMonitorImpl;
381 } } } // Tizen::Base::Runtime
383 #endif // _FBASE_RT_MONITOR_H_