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