2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
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
8 // http://www.apache.org/licenses/LICENSE-2.0
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.
18 * @file FBaseRtSemaphore.h
19 * @brief This is the header file for the %Semaphore class.
21 * This header file contains the declarations of the %Semaphore class.
24 #ifndef _FBASE_RT_SEMAPHORE_H_
25 #define _FBASE_RT_SEMAPHORE_H_
27 #include <FBaseResult.h>
28 #include <FBaseString.h>
30 namespace Tizen { namespace Base { namespace Runtime
34 * @brief This class represents semaphore, a type of synchronization mechanisms. It can provide the acquiring semantics. @n
38 * @final This class is not intended for extension.
40 * The %Semaphore class represents a semaphore; a type of synchronization mechanism.
41 * It can provide the acquiring semantics. The semaphore allows the N threads to acquire the semaphore simultaneously.
43 * 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>.
45 * The following example demonstrates how to use the %Semaphore class.
50 * using namespace Tizen::Base::Runtime;
52 * class MySemaphoreApp
55 * MySemaphoreApp(int count);
58 * void* AccessCriticalResource();
62 * int __resourceCount;
65 * MySemaphoreApp::MySemaphoreApp(int count)
66 * : __resourceCount(count)
68 * __sem.Create(count);
71 * MySemaphoreApp::~MySemaphoreApp()
76 * MySemaphoreApp::AccessCriticalResource()
79 * // Code to access critical resource, at max,
80 * // The number of '__resourceCount' users can enter this section at same time,
87 class _OSP_EXPORT_ Semaphore
92 * This is the default constructor for this class.
96 * @remarks After creating an instance of this class, one of
97 * the Create() methods must be called explicitly to initialize this instance.
102 * This is the destructor for this class.
106 virtual ~Semaphore(void);
110 * Creates an unnamed semaphore.
114 * @return An error code
115 * @param[in] count The number of threads that can acquire the semaphore simultaneously @n
116 * If the count is @c 1, then it is the same as a mutex.
117 * @exception E_SUCCESS The method is successful.
118 * @exception E_INVALID_ARG The specified @c count is less than @c 0.
119 * @exception E_OUT_OF_MEMORY The memory is insufficient.
120 * @exception E_SYSTEM A system error has occurred.
122 result Create(int count = 1);
126 * Creates a named semaphore. @n
127 * If a semaphore with the specified name already exists, this creates a semaphore which references that particular semaphore.
131 * @return An error code
132 * @param[in] name The name of the semaphore
133 * @param[in] count The number of threads that can acquire the semaphore simultaneously
134 * @exception E_SUCCESS The method is successful.
135 * @exception E_INVALID_ARG The specified @c count is less than @c 0.
136 * @exception E_OUT_OF_MEMORY The memory is insufficient.
137 * @exception E_SYSTEM A system error has occurred.
139 result Create(const Tizen::Base::String& name, int count = 1);
142 * Acquires the semaphore if it is not acquired. @n
143 * If the semaphore is already acquired, the current thread is blocked until the semaphore is released.
147 * @return An error code
148 * @param[in] timeout The period during which the thread tries to acquire the semaphore
149 * @exception E_SUCCESS The method is successful.
150 * @exception E_TIMEOUT The operation cannot be completed within the specified time period. @n
151 * The method has failed to acquire the semaphore because the given time has elapsed.
152 * @exception E_SYSTEM A system error has occurred.
154 result Acquire(long timeout = INFINITE);
157 * Tries to acquire the semaphore. @n
158 * If the semaphore is already acquired by another thread, E_OBJECT_LOCKED is returned.
162 * @return An error code
163 * @exception E_SUCCESS The method is successful.
164 * @exception E_OBJECT_LOCKED The semaphore is already locked.
165 * @exception E_SYSTEM A system error has occurred.
167 result TryToAcquire(void);
170 * Releases the semaphore.
174 * @return An error code
175 * @exception E_SUCCESS The method is successful.
176 * @exception E_SYSTEM A system error has occurred.
178 result Release(void);
181 Semaphore(const Semaphore& rhs);
182 Semaphore& operator =(const Semaphore& rhs);
185 friend class _SemaphoreImpl;
186 class _SemaphoreImpl * __pSemaphoreImpl;
189 } } } // Tizen::Base::Runtime
192 #endif // _FBASE_RT_SEMAPHORE_H_