git.sesse.net Git - casparcg/blob - dependencies/tbb/include/tbb/queuing_rw_mutex.h

   1 /*
   2     Copyright 2005-2011 Intel Corporation.  All Rights Reserved.
   3
   4     This file is part of Threading Building Blocks.
   5
   6     Threading Building Blocks is free software; you can redistribute it
   7     and/or modify it under the terms of the GNU General Public License
   8     version 2 as published by the Free Software Foundation.
   9
  10     Threading Building Blocks is distributed in the hope that it will be
  11     useful, but WITHOUT ANY WARRANTY; without even the implied warranty
  12     of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13     GNU General Public License for more details.
  14
  15     You should have received a copy of the GNU General Public License
  16     along with Threading Building Blocks; if not, write to the Free Software
  17     Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  18
  19     As a special exception, you may use this file as part of a free software
  20     library without restriction.  Specifically, if other files instantiate
  21     templates or use macros or inline functions from this file, or you compile
  22     this file and link it with other files to produce an executable, this
  23     file does not by itself cause the resulting executable to be covered by
  24     the GNU General Public License.  This exception does not however
  25     invalidate any other reasons why the executable file might be covered by
  26     the GNU General Public License.
  27 */
  28
  29 #ifndef __TBB_queuing_rw_mutex_H
  30 #define __TBB_queuing_rw_mutex_H
  31
  32 #include "tbb_config.h"
  33
  34 #if !TBB_USE_EXCEPTIONS && _MSC_VER
  35     // Suppress "C++ exception handler used, but unwind semantics are not enabled" warning in STL headers
  36     #pragma warning (push)
  37     #pragma warning (disable: 4530)
  38 #endif
  39
  40 #include <cstring>
  41
  42 #if !TBB_USE_EXCEPTIONS && _MSC_VER
  43     #pragma warning (pop)
  44 #endif
  45
  46 #include "atomic.h"
  47 #include "tbb_profiling.h"
  48
  49 namespace tbb {
  50
  51 //! Reader-writer lock with local-only spinning.
  52 /** Adapted from Krieger, Stumm, et al. pseudocode at
  53     http://www.eecg.toronto.edu/parallel/pubs_abs.html#Krieger_etal_ICPP93
  54     @ingroup synchronization */
  55 class queuing_rw_mutex {
  56 public:
  57     //! Construct unacquired mutex.
  58     queuing_rw_mutex() {
  59         q_tail = NULL;
  60 #if TBB_USE_THREADING_TOOLS
  61         internal_construct();
  62 #endif
  63     }
  64
  65     //! Destructor asserts if the mutex is acquired, i.e. q_tail is non-NULL
  66     ~queuing_rw_mutex() {
  67 #if TBB_USE_ASSERT
  68         __TBB_ASSERT( !q_tail, "destruction of an acquired mutex");
  69 #endif
  70     }
  71
  72     class scoped_lock;
  73     friend class scoped_lock;
  74
  75     //! The scoped locking pattern
  76     /** It helps to avoid the common problem of forgetting to release lock.
  77         It also nicely provides the "node" for queuing locks. */
  78     class scoped_lock: internal::no_copy {
  79         //! Initialize fields
  80         void initialize() {
  81             my_mutex = NULL;
  82 #if TBB_USE_ASSERT
  83             my_state = 0xFF; // Set to invalid state
  84             internal::poison_pointer(my_next);
  85             internal::poison_pointer(my_prev);
  86 #endif /* TBB_USE_ASSERT */
  87         }
  88     public:
  89         //! Construct lock that has not acquired a mutex.
  90         /** Equivalent to zero-initialization of *this. */
  91         scoped_lock() {initialize();}
  92
  93         //! Acquire lock on given mutex.
  94         scoped_lock( queuing_rw_mutex& m, bool write=true ) {
  95             initialize();
  96             acquire(m,write);
  97         }
  98
  99         //! Release lock (if lock is held).
 100         ~scoped_lock() {
 101             if( my_mutex ) release();
 102         }
 103
 104         //! Acquire lock on given mutex.
 105         void acquire( queuing_rw_mutex& m, bool write=true );
 106
 107         //! Try acquire lock on given mutex.
 108         bool try_acquire( queuing_rw_mutex& m, bool write=true );
 109
 110         //! Release lock.
 111         void release();
 112
 113         //! Upgrade reader to become a writer.
 114         /** Returns true if the upgrade happened without re-acquiring the lock and false if opposite */
 115         bool upgrade_to_writer();
 116
 117         //! Downgrade writer to become a reader.
 118         bool downgrade_to_reader();
 119
 120     private:
 121         //! The pointer to the current mutex to work
 122         queuing_rw_mutex* my_mutex;
 123
 124         //! The pointer to the previous and next competitors for a mutex
 125         scoped_lock *__TBB_atomic my_prev, *__TBB_atomic my_next;
 126
 127         typedef unsigned char state_t;
 128
 129         //! State of the request: reader, writer, active reader, other service states
 130         atomic<state_t> my_state;
 131
 132         //! The local spin-wait variable
 133         /** Corresponds to "spin" in the pseudocode but inverted for the sake of zero-initialization */
 134         unsigned char __TBB_atomic my_going;
 135
 136         //! A tiny internal lock
 137         unsigned char my_internal_lock;
 138
 139         //! Acquire the internal lock
 140         void acquire_internal_lock();
 141
 142         //! Try to acquire the internal lock
 143         /** Returns true if lock was successfully acquired. */
 144         bool try_acquire_internal_lock();
 145
 146         //! Release the internal lock
 147         void release_internal_lock();
 148
 149         //! Wait for internal lock to be released
 150         void wait_for_release_of_internal_lock();
 151
 152         //! A helper function
 153         void unblock_or_wait_on_internal_lock( uintptr_t );
 154     };
 155
 156     void __TBB_EXPORTED_METHOD internal_construct();
 157
 158     // Mutex traits
 159     static const bool is_rw_mutex = true;
 160     static const bool is_recursive_mutex = false;
 161     static const bool is_fair_mutex = true;
 162
 163 private:
 164     //! The last competitor requesting the lock
 165     atomic<scoped_lock*> q_tail;
 166
 167 };
 168
 169 __TBB_DEFINE_PROFILING_SET_NAME(queuing_rw_mutex)
 170
 171 } // namespace tbb
 172
 173 #endif /* __TBB_queuing_rw_mutex_H */