inc/FBaseRtMutex.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                FBaseRtMutex.h
  19  * @brief               This is the header file for the %Mutex class.
  20  *
  21  * This header file contains the declarations of the %Mutex class.
  22  */
  23
  24 #ifndef _FBASE_RT_MUTEX_H_
  25 #define _FBASE_RT_MUTEX_H_
  26
  27 #include <FBaseResult.h>
  28 #include <FBaseString.h>
  29
  30
  31
  32 namespace Tizen { namespace Base { namespace Runtime
  33 {
  34 /**
  35  * @struct      NonRecursiveMutexTag
  36  *
  37  * This struct is used only for providing the non-recursive type of mutex.
  38  * A non-recursive mutex is a mutex that can not be acquired multiple times by the locking thread. It returns an exception if the locking thread tries to lock the same mutex.
  39  *
  40  * @since 2.1
  41  *
  42  * @see         Mutex
  43  */
  44  struct NonRecursiveMutexTag
  45  {
  46  };
  47
  48 /**
  49  * This is a constant instance of NonRecursiveMutexTag.
  50  *
  51  * @code
  52  * Mutex m;
  53  * result r = m.Create(NonRecursiveMutex);
  54  * @endcode
  55  */
  56  static const NonRecursiveMutexTag NonRecursiveMutex = {};
  57
  58 /**
  59  *  @class Mutex
  60  *      @brief  This class represents a mutex; a type of synchronization mechanism.
  61  *
  62  *      @since 2.0
  63  *
  64  * @final This class is not intended for extension.
  65  *  The %Mutex class represents a mutex; a type of synchronization mechanism.
  66  *      It is a binary semaphore. Only one thread can acquire the %Mutex.
  67  *
  68  * 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>.
  69  *
  70  *      @see Semaphore
  71  *      @see Thread
  72  *
  73  * The following example demonstrates how to use the %Mutex class.
  74  *
  75  *      @code
  76  *      #include <FBase.h>
  77  *
  78  *      using namespace Tizen::Base::Runtime;
  79  *
  80  *      class MyMutexApp
  81  *      {
  82  *      public:
  83  *              MyMutexApp();
  84  *              ~MyMutexApp();
  85  *
  86  *              void UpdateCriticalResource();
  87  *
  88  *      private:
  89  *              Mutex __mutex;
  90  *              int __count;
  91  *      };
  92  *
  93  *      MyMutexApp::MyMutexApp()
  94  *              : __count(0)
  95  *      {
  96  *              __mutex.Create();
  97  *      }
  98  *
  99  *      MyMutexApp::~MyMutexApp()
 100  *      {
 101  *      }
 102  *
 103  *      void
 104  *      MyMutexApp::UpdateCriticalResource()
 105  *      {
 106  *              __mutex.Acquire();
 107  *              __count++;
 108  *              __mutex.Release();
 109  *      }
 110  *
 111  *      @endcode
 112  *
 113  */
 114
 115 class _OSP_EXPORT_ Mutex
 116         : public Tizen::Base::Object
 117 {
 118 public:
 119         /**
 120          *      This is the default constructor for this class.
 121          *
 122          *      @since 2.0
 123          *
 124          *      @remarks        After creating an instance of this class, one of
 125          *                              the Create() methods must be called explicitly to initialize this instance.
 126          */
 127         Mutex(void);
 128
 129         /**
 130          *      This is the destructor for this class.
 131          *
 132          *      @since 2.0
 133          */
 134         virtual ~Mutex(void);
 135
 136         /**
 137          *      Creates an unnamed mutex which is a recursive mutex that can be acquired multiple times by the locking thread.
 138          *     It keeps the number of getting locked and you must unlock it the same number of times.
 139          *
 140          *      @since 2.0
 141          *
 142          *      @return                 An error code
 143          *      @exception      E_SUCCESS               The method is successful.
 144          *      @exception      E_OUT_OF_MEMORY         The memory is insufficient.
 145          *      @exception      E_SYSTEM                A system error has occurred.
 146          */
 147         result Create(void);
 148
 149         /**
 150          *      Creates a non-recursive mutex.
 151          *
 152          *      @since 2.1
 153          *
 154          *      @return                 An error code
 155          *      @exception      E_SUCCESS               The method is successful.
 156          *      @exception      E_SYSTEM                A system error has occurred.
 157          */
 158         result Create(NonRecursiveMutexTag);
 159
 160         /**
 161          *      Creates a named mutex which is a recursive mutex that can be acquired multiple times by the locking thread.
 162          *     It keeps the number of getting locked and you must unlock it the same number of times. @n
 163          *      If a mutex with the specified name already exists, this creates a mutex which references that particular mutex.
 164          *
 165          *      @since 2.0
 166          *
 167          *      @return                 An error code
 168          *      @param[in]      name                    The name of the mutex
 169          *      @exception      E_SUCCESS               The method is successful.
 170          *      @exception      E_OUT_OF_MEMORY         The memory is insufficient.
 171          *      @exception      E_SYSTEM                A system error has occurred.
 172          */
 173         result Create(const Tizen::Base::String& name);
 174
 175         /**
 176          *      Releases the mutex.
 177          *
 178          *      @since 2.0
 179          *
 180          *      @return                 An error code
 181          *      @exception      E_SUCCESS               The method is successful.
 182          *      @exception      E_SYSTEM        A system error has occurred.
 183          *      @remarks        This method should be called only after acquiring lock by Acquire()/ TryToAcquire() call
 184          */
 185         result Release(void);
 186
 187         /**
 188          *      Acquires the mutex if it is not acquired. @n
 189          *      If the mutex is already acquired by another thread,
 190          *      the current thread is blocked until the mutex is released.
 191          *
 192          *      @since 2.0
 193          *
 194          *      @return                 An error code
 195          *      @exception      E_SUCCESS               The method is successful.
 196          *      @exception      E_SYSTEM                A system error has occurred.
 197          *      @remarks        This method will block if called on already locked monitor object until mutex becomes available.
 198          */
 199         result Acquire(void);
 200
 201         /**
 202          *      Tries to acquire the mutex if it is not acquired. @n
 203          *      If the mutex is already acquired by another thread, E_OBJECT_LOCKED is returned.
 204          *
 205          *      @since 2.0
 206          *
 207          *      @return                 An error code
 208          *      @exception      E_SUCCESS               The method is successful.
 209          *      @exception      E_OBJECT_LOCKED         The mutex is already locked.
 210          *      @exception      E_SYSTEM                A system error has occurred.
 211          *      @remarks        This method will block if called on already locked monitor object until mutex becomes available.
 212          */
 213         result TryToAcquire(void);
 214
 215 private:
 216         Mutex(const Mutex& value);
 217         Mutex& operator =(const Mutex& value);
 218
 219 private:
 220         friend class _MutexImpl;
 221         class _MutexImpl * __pMutexImpl;
 222 }; // Mutex
 223
 224 } } } // Tizen::Base::Runtime
 225
 226
 227 #endif // _FBASE_RT_MUTEX_H_