inc/FBaseRtSemaphore.h

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