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 FBaseRtSemaphore.h
20 * @brief This is the header file for the %Semaphore class.
22 * This header file contains the declarations of the %Semaphore class.
25 #ifndef _FBASE_RT_SEMAPHORE_H_
26 #define _FBASE_RT_SEMAPHORE_H_
28 #include <FBaseResult.h>
29 #include <FBaseString.h>
31 namespace Tizen { namespace Base { namespace Runtime
35 * @brief This class represents semaphore, a type of synchronization mechanisms. It can provide the acquiring semantics. @n
39 * @final This class is not intended for extension.
41 * The %Semaphore class represents a semaphore; a type of synchronization mechanism.
42 * It can provide the acquiring semantics. The semaphore allows the N threads to acquire the semaphore simultaneously.
44 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/mutex_and_semaphore.htm">Mutex and Semaphore</a>.
46 * The following example demonstrates how to use the %Semaphore class.
51 * using namespace Tizen::Base::Runtime;
53 * class MySemaphoreApp
56 * MySemaphoreApp(int count);
59 * void* AccessCriticalResource();
63 * int __resourceCount;
66 * MySemaphoreApp::MySemaphoreApp(int count)
67 * : __resourceCount(count)
69 * __sem.Create(count);
72 * MySemaphoreApp::~MySemaphoreApp()
77 * MySemaphoreApp::AccessCriticalResource()
80 * // Code to access critical resource, at max,
81 * // The number of '__resourceCount' users can enter this section at same time,
88 class _OSP_EXPORT_ Semaphore
93 * This is the default constructor for this class.
97 * @remarks After creating an instance of this class, one of
98 * the Create() methods must be called explicitly to initialize this instance.
103 * This is the destructor for this class.
107 virtual ~Semaphore(void);
111 * Creates an unnamed semaphore.
115 * @return An error code
116 * @param[in] count The number of threads that can acquire the semaphore simultaneously @n
117 * If the count is @c 1, then it is the same as a mutex.
118 * @exception E_SUCCESS The method is successful.
119 * @exception E_INVALID_ARG The specified @c count is less than @c 0.
120 * @exception E_OUT_OF_MEMORY The memory is insufficient.
121 * @exception E_SYSTEM A system error has occurred.
123 result Create(int count = 1);
127 * Creates a named semaphore. @n
128 * If a semaphore with the specified name already exists, this creates a semaphore which references that particular semaphore.
132 * @return An error code
133 * @param[in] name The name of the semaphore
134 * @param[in] count The number of threads that can acquire the semaphore simultaneously
135 * @exception E_SUCCESS The method is successful.
136 * @exception E_INVALID_ARG The specified @c count is less than @c 0.
137 * @exception E_OUT_OF_MEMORY The memory is insufficient.
138 * @exception E_SYSTEM A system error has occurred.
140 result Create(const Tizen::Base::String& name, int count = 1);
143 * Acquires the semaphore if it is not acquired. @n
144 * If the semaphore is already acquired, the current thread is blocked until the semaphore is released.
148 * @return An error code
149 * @param[in] timeout The period during which the thread tries to acquire the semaphore
150 * @exception E_SUCCESS The method is successful.
151 * @exception E_TIMEOUT The operation cannot be completed within the specified time period. @n
152 * The method has failed to acquire the semaphore because the given time has elapsed.
153 * @exception E_SYSTEM A system error has occurred.
155 result Acquire(long timeout = INFINITE);
158 * Tries to acquire the semaphore. @n
159 * If the semaphore is already acquired by another thread, E_OBJECT_LOCKED is returned.
163 * @return An error code
164 * @exception E_SUCCESS The method is successful.
165 * @exception E_OBJECT_LOCKED The semaphore is already locked.
166 * @exception E_SYSTEM A system error has occurred.
168 result TryToAcquire(void);
171 * Releases the semaphore.
175 * @return An error code
176 * @exception E_SUCCESS The method is successful.
177 * @exception E_SYSTEM A system error has occurred.
179 result Release(void);
182 Semaphore(const Semaphore& rhs);
183 Semaphore& operator =(const Semaphore& rhs);
186 friend class _SemaphoreImpl;
187 class _SemaphoreImpl * __pSemaphoreImpl;
190 } } } // Tizen::Base::Runtime
193 #endif // _FBASE_RT_SEMAPHORE_H_