src/base/runtime/FBaseRt_MutexImpl.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        FBaseRt_MutexImpl.h
  19  * @brief       This is the implementation file for the _MutexImpl class.
  20  *
  21  */
  22
  23 #ifndef _FTHREAD_INTERNAL_MUTEX_IMPL_H_
  24 #define _FTHREAD_INTERNAL_MUTEX_IMPL_H_
  25
  26 #include <pthread.h>
  27 #include <FBaseResult.h>
  28 #include <FBaseString.h>
  29
  30
  31 namespace Tizen { namespace Base { namespace Runtime
  32 {
  33
  34 /**
  35  *  @class  _MutexImpl
  36  *      @brief  This class represents a mutex; one type of synchronization mechanism.
  37  *
  38  *      It is a binary semaphore. Only one thread can acquire the Mutex.
  39  *
  40  *      @code
  41  *      #include <FBase.h>
  42  *
  43  *      using namespace Tizen::Base;
  44  *      using namespace Tizen::Base::Runtime;
  45  *
  46  *  result
  47  *      MyApp::AddRef(void)
  48  *      {
  49  *    __pMutex->Acqure();
  50  *
  51  *    __count++;
  52  *
  53  *    __pMutex->Release();
  54  *      }
  55  *
  56  *      @endcode
  57  *
  58  *
  59  *      @see    Semaphore, Thread
  60  */
  61
  62 class _MutexImpl
  63         : public Tizen::Base::Object
  64 {
  65 public:
  66         /**
  67          *      This is the default constructor for this class.
  68          *
  69          *      @since 2.0
  70          *      @remarks        After creating an instance of this class, you must explicitly call one of
  71          *                              the Create() methods to initialize the instance.
  72          */
  73         _MutexImpl(void);
  74
  75         /**
  76          *      This is the destructor for this class.
  77          *
  78          *      @since 2.0
  79          */
  80         virtual ~_MutexImpl(void);
  81
  82         /**
  83          *      Creates an unnamed Mutex.
  84          *
  85          *      @since 2.0
  86          *      @return                 An error code
  87          *      @exception      E_SUCCESS               The method was successful.
  88          *      @exception      E_SYSTEM                An unknown operating system error occurred.
  89          */
  90         result Create(void);
  91
  92         /**
  93          *      Creates a non-recursive mutex.
  94          *
  95          *      @since 2.0
  96          *      @return                 An error code
  97          *      @exception      E_SUCCESS               The method was successful.
  98          *      @exception      E_SYSTEM                An unknown operating system error occurred.
  99          */
 100         result CreateNonRecursiveMutex(void);
 101
 102         /**
 103          *      Creates a named Mutex. @n
 104          *      If there is already a Mutex with the specified name, this creates a Mutex which references that particular Mutex.
 105          *
 106          *      @since 2.0
 107          *      @return                 An error code
 108          *      @param[in]      name                    The name of the Mutex
 109          *      @exception      E_SUCCESS               The method was successful.
 110          *      @exception      E_SYSTEM                An unknown operating system error occurred.
 111          */
 112         result Create(const Tizen::Base::String& name);
 113
 114         /**
 115          *      Acquires the Mutex if it is not acquired. @n
 116          *      If the Mutex is already acquired by another thread,
 117          *      the current thread is blocked until the Mutex is released.
 118          *
 119          *      @since 2.0
 120          *      @return                 An error code
 121          *      @param[in]      timeout                 The period during which the thread tries to acquire the mutex
 122          *      @exception      E_SUCCESS               The method was successful.
 123          *      @exception      E_TIMEOUT               The operation could not be completed within the specified time period. @n
 124          *      @exception      E_SYSTEM                An unknown operating system error occurred. @n
 125          *                                                              Failed to acquire the Mutex because an OS failure occurred.
 126          */
 127         result Acquire(long timeout);
 128
 129         /**
 130          *      Releases the Mutex.
 131          *
 132          *      @since 2.0
 133          *      @return                 An error code
 134          *      @exception      E_SUCCESS       The method was successful.
 135          *      @exception      E_SYSTEM        An unknown operating system error occurred. @n
 136          *                                                      Failed to acquire the Mutex because an OS failure occurred.
 137          */
 138         result Release(void);
 139
 140         /**
 141          *      Acquires the Mutex if it is not acquired. @n
 142          *      If the Mutex is already acquired by another thread,
 143          *      the current thread is blocked until the Mutex is released.
 144          *
 145          *      @since 2.0
 146          *      @return                 An error code
 147          *      @exception      E_SUCCESS               The method was successful.
 148          *      @exception      E_SYSTEM                An unknown operating system error occurred. @n
 149          *                                                              Failed to acquire the Mutex because an OS failure occurred.
 150          */
 151         result Acquire(void);
 152
 153         /**
 154          *      Acquires the mutex if it is not acquired. @n
 155          *      If the mutex is already acquired by another thread, E_OBJECT_LOCKED is returned.
 156          *
 157          *      @since 2.0
 158          *
 159          *      @return                 An error code
 160          *      @exception      E_SUCCESS               The method is successful.
 161          *      @exception      E_OBJECT_LOCKED         The mutex is already locked.
 162          *      @exception      E_INVALID_STATE         The mutex has not been initialized as yet.
 163          *      @exception      E_SYSTEM                A system error has occurred.
 164          */
 165         result TryToAcquire(void);
 166
 167 private:
 168         pthread_mutex_t* __pMutex;
 169         Tizen::Base::String __name;
 170
 171 };
 172
 173
 174 //}
 175 } } } // Tizen::Runtime
 176
 177
 178 #endif