include/osl/mutex.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef INCLUDED_OSL_MUTEX_HXX
  21 #define INCLUDED_OSL_MUTEX_HXX
  22
  23 #include "osl/mutex.h"
  24
  25 #include <cassert>
  26
  27 namespace osl
  28 {
  29     /** A mutual exclusion synchronization object
  30     */
  31     class SAL_WARN_UNUSED Mutex {
  32
  33     public:
  34         /** Create a mutex.
  35             @return 0 if the mutex could not be created, otherwise a handle to the mutex.
  36             @see ::osl_createMutex()
  37         */
  38         Mutex()
  39         {
  40             mutex = osl_createMutex();
  41         }
  42
  43         /** Release the OS-structures and free mutex data-structure.
  44             @see ::osl_destroyMutex()
  45         */
  46         ~Mutex()
  47         {
  48             osl_destroyMutex(mutex);
  49         }
  50
  51         /** Acquire the mutex, block if already acquired by another thread.
  52             @return false if system-call fails.
  53             @see ::osl_acquireMutex()
  54         */
  55         bool acquire()
  56         {
  57             return osl_acquireMutex(mutex);
  58         }
  59
  60         /** Try to acquire the mutex without blocking.
  61             @return false if it could not be acquired.
  62             @see ::osl_tryToAcquireMutex()
  63         */
  64         bool tryToAcquire()
  65         {
  66             return osl_tryToAcquireMutex(mutex);
  67         }
  68
  69         /** Release the mutex.
  70             @return false if system-call fails.
  71             @see ::osl_releaseMutex()
  72         */
  73         bool release()
  74         {
  75             return osl_releaseMutex(mutex);
  76         }
  77
  78         /** Returns a global static mutex object.
  79             The global and static mutex object can be used to initialize other
  80             static objects in a thread safe manner.
  81             @return the global mutex object
  82             @see ::osl_getGlobalMutex()
  83         */
  84         static Mutex * getGlobalMutex()
  85         {
  86             return reinterpret_cast<Mutex *>(osl_getGlobalMutex());
  87         }
  88
  89     private:
  90         oslMutex mutex;
  91
  92         /** The underlying oslMutex has no reference count.
  93
  94         Since the underlying oslMutex is not a reference counted object, copy
  95         constructed Mutex may work on an already destructed oslMutex object.
  96
  97         */
  98         Mutex(const Mutex&) SAL_DELETED_FUNCTION;
  99
 100         /** This assignment operator is deleted for the same reason as
 101             the copy constructor.
 102         */
 103         Mutex& operator= (const Mutex&) SAL_DELETED_FUNCTION;
 104     };
 105
 106     /** Object lifetime scoped mutex object or interface lock.
 107      *
 108      * Acquires the template object on construction and releases it on
 109      * destruction.
 110      *
 111      * @see MutexGuard
 112      */
 113     template<class T>
 114     class Guard
 115     {
 116         Guard(const Guard&) SAL_DELETED_FUNCTION;
 117         Guard& operator=(const Guard&) SAL_DELETED_FUNCTION;
 118
 119     protected:
 120         T * pT;
 121
 122     public:
 123         /** Acquires the object specified as parameter.
 124         */
 125         Guard(T * pT_) : pT(pT_)
 126         {
 127             assert(pT != NULL);
 128             pT->acquire();
 129         }
 130
 131         /** Acquires the object specified as parameter.
 132         */
 133         Guard(T & t) : pT(&t)
 134         {
 135             pT->acquire();
 136         }
 137
 138         /** Releases the mutex or interface. */
 139         ~Guard()
 140         {
 141             pT->release();
 142         }
 143     };
 144
 145     /** Object lifetime scoped mutex object or interface lock with unlock.
 146      *
 147      * Use this if you can't use scoped code blocks and Guard.
 148      *
 149      * @see ClearableMutexGuard, Guard
 150      */
 151     template<class T>
 152     class ClearableGuard
 153     {
 154         ClearableGuard( const ClearableGuard& ) SAL_DELETED_FUNCTION;
 155         ClearableGuard& operator=(const ClearableGuard&) SAL_DELETED_FUNCTION;
 156
 157     protected:
 158         T * pT;
 159
 160     public:
 161         /** Acquires the object specified as parameter.
 162         */
 163         ClearableGuard(T * pT_) : pT(pT_)
 164         {
 165             assert(pT != NULL);
 166             pT->acquire();
 167         }
 168
 169         /** Acquires the object specified as parameter.
 170         */
 171         ClearableGuard(T & t) : pT(&t)
 172         {
 173             pT->acquire();
 174         }
 175
 176         /** Releases the mutex or interface if not already released by clear().
 177         */
 178         ~ClearableGuard()
 179         {
 180             if (pT)
 181                 pT->release();
 182         }
 183
 184         /** Releases the mutex or interface.
 185         */
 186         void clear()
 187         {
 188 #ifdef LIBO_INTERNAL_ONLY
 189             assert(pT);
 190 #else
 191             if (pT)
 192 #endif
 193             {
 194                 pT->release();
 195                 pT = NULL;
 196             }
 197         }
 198     };
 199
 200     /** Template for temporary releasable mutex objects and interfaces locks.
 201      *
 202      * Use this if you want to acquire a lock but need to temporary release
 203      * it and can't use multiple scoped Guard objects.
 204      *
 205      * @see ResettableMutexGuard
 206      */
 207     template< class T >
 208     class ResettableGuard : public ClearableGuard< T >
 209     {
 210         ResettableGuard(const ResettableGuard&) SAL_DELETED_FUNCTION;
 211         ResettableGuard& operator=(const ResettableGuard&) SAL_DELETED_FUNCTION;
 212
 213     protected:
 214         T* pResetT;
 215
 216     public:
 217         /** Acquires the object specified as parameter.
 218         */
 219         ResettableGuard( T* pT_ ) :
 220                 ClearableGuard<T>( pT_ ),
 221                 pResetT( pT_ )
 222         {}
 223
 224         /** Acquires the object specified as parameter.
 225         */
 226         ResettableGuard( T& rT ) :
 227                 ClearableGuard<T>( rT ),
 228                 pResetT( &rT )
 229         {}
 230
 231         /** Re-acquires the mutex or interface.
 232         */
 233         void reset()
 234         {
 235 #ifdef LIBO_INTERNAL_ONLY
 236             assert(!this->pT);
 237 #endif
 238             if (pResetT)
 239             {
 240                 this->pT = pResetT;
 241                 this->pT->acquire();
 242             }
 243         }
 244     };
 245
 246     typedef Guard<Mutex> MutexGuard;
 247     typedef ClearableGuard<Mutex> ClearableMutexGuard;
 248     typedef ResettableGuard< Mutex > ResettableMutexGuard;
 249 }
 250
 251 #endif // INCLUDED_OSL_MUTEX_HXX
 252
 253 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */