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