inc/FBaseRtSemaphore.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                FBaseRtSemaphore.h
  20  * @brief               This is the header file for the %Semaphore class.
  21  *
  22  * This header file contains the declarations of the %Semaphore class.
  23  */
  24
  25 #ifndef _FBASE_RT_SEMAPHORE_H_
  26 #define _FBASE_RT_SEMAPHORE_H_
  27
  28 #include <FBaseResult.h>
  29 #include <FBaseString.h>
  30
  31 namespace Tizen { namespace Base { namespace Runtime
  32 {
  33 /**
  34  *  @class  Semaphore
  35  *  @brief  This class represents semaphore, a type of synchronization mechanisms. It can provide the acquiring semantics. @n
  36  *
  37  *  @since 2.0
  38  *
  39  *  @final This class is not intended for extension.
  40  *
  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.
  43  *
  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>.
  45  *
  46  * The following example demonstrates how to use the %Semaphore class.
  47  *
  48  *      @code
  49  *      #include <FBase.h>
  50  *
  51  *      using namespace Tizen::Base::Runtime;
  52  *
  53  *      class MySemaphoreApp
  54  *      {
  55  *      public:
  56  *              MySemaphoreApp(int count);
  57  *              ~MySemaphoreApp();
  58  *
  59  *              void* AccessCriticalResource();
  60  *
  61  *      private:
  62  *              Semaphore __sem;
  63  *              int __resourceCount;
  64  *      };
  65  *
  66  *      MySemaphoreApp::MySemaphoreApp(int count)
  67  *              : __resourceCount(count)
  68  *      {
  69  *              __sem.Create(count);
  70  *      }
  71  *
  72  *      MySemaphoreApp::~MySemaphoreApp()
  73  *      {
  74  *      }
  75  *
  76  *      void
  77  *      MySemaphoreApp::AccessCriticalResource()
  78  *      {
  79  *              __sem.Acquire();
  80  *              // Code to access critical resource, at max,
  81  *              // The number of '__resourceCount' users can enter this section at same time,
  82  *              __sem.Release();
  83  *      }
  84  *
  85  *      @endcode
  86  *
  87  */
  88 class _OSP_EXPORT_ Semaphore
  89         : Tizen::Base::Object
  90 {
  91 public:
  92         /**
  93          *      This is the default constructor for this class.
  94          *
  95          *      @since 2.0
  96          *
  97          *      @remarks        After creating an instance of this class, one of
  98          *                              the Create() methods must be called explicitly to initialize this instance.
  99          */
 100         Semaphore(void);
 101
 102         /**
 103          *      This is the destructor for this class.
 104          *
 105          *      @since 2.0
 106          */
 107         virtual ~Semaphore(void);
 108
 109
 110         /**
 111          *      Creates an unnamed semaphore.
 112          *
 113          *      @since 2.0
 114          *
 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.
 122          */
 123         result Create(int count = 1);
 124
 125
 126         /**
 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.
 129          *
 130          *      @since 2.0
 131          *
 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.
 139          */
 140         result Create(const Tizen::Base::String& name, int count = 1);
 141
 142         /**
 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.
 145          *
 146          *      @since 2.0
 147          *
 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.
 154          */
 155         result Acquire(long timeout = INFINITE);
 156
 157         /**
 158          *      Tries to acquire the semaphore. @n
 159          *      If the semaphore is already acquired by another thread, E_OBJECT_LOCKED is returned.
 160          *
 161          *      @since 2.0
 162          *
 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.
 167          */
 168         result TryToAcquire(void);
 169
 170         /**
 171          *      Releases the semaphore.
 172          *
 173          *      @since 2.0
 174          *
 175          *      @return                 An error code
 176          *      @exception      E_SUCCESS               The method is successful.
 177          *      @exception      E_SYSTEM                A system error has occurred.
 178          */
 179         result Release(void);
 180
 181 private:
 182         Semaphore(const Semaphore& rhs);
 183         Semaphore& operator =(const Semaphore& rhs);
 184
 185 private:
 186         friend class _SemaphoreImpl;
 187         class _SemaphoreImpl * __pSemaphoreImpl;
 188 }; // Semaphore
 189
 190 } } } // Tizen::Base::Runtime
 191
 192
 193 #endif // _FBASE_RT_SEMAPHORE_H_