ceph/src/boost/boost/interprocess/sync/file_lock.hpp

   1 //////////////////////////////////////////////////////////////////////////////
   2 //
   3 // (C) Copyright Ion Gaztanaga 2005-2012. Distributed under the Boost
   4 // Software License, Version 1.0. (See accompanying file
   5 // LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   6 //
   7 // See http://www.boost.org/libs/interprocess for documentation.
   8 //
   9 //////////////////////////////////////////////////////////////////////////////
  10
  11 #ifndef BOOST_INTERPROCESS_FILE_LOCK_HPP
  12 #define BOOST_INTERPROCESS_FILE_LOCK_HPP
  13
  14 #ifndef BOOST_CONFIG_HPP
  15 #  include <boost/config.hpp>
  16 #endif
  17 #
  18 #if defined(BOOST_HAS_PRAGMA_ONCE)
  19 #  pragma once
  20 #endif
  21
  22 #include <boost/interprocess/detail/config_begin.hpp>
  23 #include <boost/interprocess/detail/workaround.hpp>
  24 #include <boost/interprocess/exceptions.hpp>
  25 #include <boost/interprocess/detail/os_file_functions.hpp>
  26 #include <boost/interprocess/detail/os_thread_functions.hpp>
  27 #include <boost/interprocess/sync/detail/common_algorithms.hpp>
  28 #include <boost/interprocess/sync/detail/locks.hpp>
  29 #include <boost/move/utility_core.hpp>
  30
  31 //!\file
  32 //!Describes a class that wraps file locking capabilities.
  33
  34 namespace boost {
  35 namespace interprocess {
  36
  37
  38 //!A file lock, is a mutual exclusion utility similar to a mutex using a
  39 //!file. A file lock has sharable and exclusive locking capabilities and
  40 //!can be used with scoped_lock and sharable_lock classes.
  41 //!A file lock can't guarantee synchronization between threads of the same
  42 //!process so just use file locks to synchronize threads from different processes.
  43 class file_lock
  44 {
  45    #if !defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
  46    //Non-copyable
  47    BOOST_MOVABLE_BUT_NOT_COPYABLE(file_lock)
  48    #endif   //#ifndef BOOST_INTERPROCESS_DOXYGEN_INVOKED
  49
  50    public:
  51    //!Constructs an empty file mapping.
  52    //!Does not throw
  53    file_lock() BOOST_NOEXCEPT
  54       :  m_file_hnd(file_handle_t(ipcdetail::invalid_file()))
  55    {}
  56
  57    //!Opens a file lock. Throws interprocess_exception if the file does not
  58    //!exist or there are no operating system resources.
  59    file_lock(const char *name);
  60
  61    #if defined(BOOST_INTERPROCESS_WCHAR_NAMED_RESOURCES) || defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
  62    //!Opens a file lock. Throws interprocess_exception if the file does not
  63    //!exist or there are no operating system resources.
  64    //!
  65    //!Note: This function is only available on operating systems with
  66    //!      native wchar_t APIs (e.g. Windows).
  67    file_lock(const wchar_t *name);
  68    #endif
  69
  70    //!Moves the ownership of "moved"'s file mapping object to *this.
  71    //!After the call, "moved" does not represent any file mapping object.
  72    //!Does not throw
  73    file_lock(BOOST_RV_REF(file_lock) moved) BOOST_NOEXCEPT
  74       :  m_file_hnd(file_handle_t(ipcdetail::invalid_file()))
  75    {  this->swap(moved);   }
  76
  77    //!Moves the ownership of "moved"'s file mapping to *this.
  78    //!After the call, "moved" does not represent any file mapping.
  79    //!Does not throw
  80    file_lock &operator=(BOOST_RV_REF(file_lock) moved) BOOST_NOEXCEPT
  81    {
  82       file_lock tmp(boost::move(moved));
  83       this->swap(tmp);
  84       return *this;
  85    }
  86
  87    //!Closes a file lock. Does not throw.
  88    ~file_lock();
  89
  90    //!Swaps two file_locks.
  91    //!Does not throw.
  92    void swap(file_lock &other) BOOST_NOEXCEPT
  93    {
  94       file_handle_t tmp = m_file_hnd;
  95       m_file_hnd = other.m_file_hnd;
  96       other.m_file_hnd = tmp;
  97    }
  98
  99    //Exclusive locking
 100
 101    //!Requires: The calling thread does not own the mutex.
 102    //!
 103    //!Effects: The calling thread tries to obtain exclusive ownership of the mutex,
 104    //!   and if another thread has exclusive, or sharable ownership of
 105    //!   the mutex, it waits until it can obtain the ownership.
 106    //!Throws: interprocess_exception on error.
 107    //!
 108    //!Note: A program may deadlock if the thread that has ownership calls
 109    //!   this function. If the implementation can detect the deadlock,
 110    //!   an exception could be thrown.
 111    void lock();
 112
 113    //!Requires: The calling thread does not own the mutex.
 114    //!
 115    //!Effects: The calling thread tries to acquire exclusive ownership of the mutex
 116    //!   without waiting. If no other thread has exclusive, or sharable
 117    //!   ownership of the mutex this succeeds.
 118    //!Returns: If it can acquire exclusive ownership immediately returns true.
 119    //!   If it has to wait, returns false.
 120    //!Throws: interprocess_exception on error.
 121    //!
 122    //!Note: A program may deadlock if the thread that has ownership calls
 123    //!   this function. If the implementation can detect the deadlock,
 124    //!   an exception could be thrown.
 125    bool try_lock();
 126
 127    //!Requires: The calling thread does not own the mutex.
 128    //!
 129    //!Effects: The calling thread tries to acquire exclusive ownership of the mutex
 130    //!   waiting if necessary until no other thread has exclusive, or sharable
 131    //!   ownership of the mutex or abs_time is reached.
 132    //!Returns: If acquires exclusive ownership, returns true. Otherwise returns false.
 133    //!Throws: interprocess_exception on error.
 134    //!
 135    //!Note: A program may deadlock if the thread that has ownership calls
 136    //!   this function. If the implementation can detect the deadlock,
 137    //!   an exception could be thrown.
 138    template<class TimePoint>
 139    bool timed_lock(const TimePoint &abs_time);
 140
 141    //!Same as `timed_lock`, but this function is modeled after the
 142    //!standard library interface.
 143    template<class TimePoint> bool try_lock_until(const TimePoint &abs_time)
 144    {  return this->timed_lock(abs_time);  }
 145
 146    //!Same as `timed_lock`, but this function is modeled after the
 147    //!standard library interface.
 148    template<class Duration>  bool try_lock_for(const Duration &dur)
 149    {  return this->timed_lock(ipcdetail::duration_to_ustime(dur)); }
 150
 151    //!Precondition: The thread must have exclusive ownership of the mutex.
 152    //!Effects: The calling thread releases the exclusive ownership of the mutex.
 153    //!Throws: An exception derived from interprocess_exception on error.
 154    void unlock();
 155
 156    //Sharable locking
 157
 158    //!Requires: The calling thread does not own the mutex.
 159    //!
 160    //!Effects: The calling thread tries to obtain sharable ownership of the mutex,
 161    //!   and if another thread has exclusive ownership of the mutex, waits until
 162    //!   it can obtain the ownership.
 163    //!Throws: interprocess_exception on error.
 164    //!
 165    //!Note: A program may deadlock if the thread that owns a mutex object calls
 166    //!   this function. If the implementation can detect the deadlock,
 167    //!   an exception could be thrown.
 168    void lock_sharable();
 169
 170    //!Same as `lock_sharable` but with a std-compatible interface
 171    //!
 172    void lock_shared()
 173    {  this->lock_sharable();  }
 174
 175    //!Effects: The calling thread tries to acquire sharable ownership of the mutex
 176    //!   without waiting. If no other thread has exclusive ownership of the
 177    //!   mutex this succeeds.
 178    //!Returns: If it can acquire sharable ownership immediately returns true. If it
 179    //!   has to wait, returns false.
 180    //!Throws: interprocess_exception on error.
 181    bool try_lock_sharable();
 182
 183    //!Same as `try_lock_sharable` but with a std-compatible interface
 184    //!
 185    bool try_lock_shared()
 186    {  return this->try_lock_sharable();  }
 187
 188    //!Effects: The calling thread tries to acquire sharable ownership of the mutex
 189    //!   waiting if necessary until no other thread has exclusive ownership of
 190    //!   the mutex or abs_time is reached.
 191    //!Returns: If acquires sharable ownership, returns true. Otherwise returns false.
 192    //!Throws: interprocess_exception on error.
 193    template<class TimePoint>
 194    bool timed_lock_sharable(const TimePoint &abs_time);
 195
 196    //!Same as `timed_lock_sharable`, but this function is modeled after the
 197    //!standard library interface.
 198    template<class TimePoint> bool try_lock_shared_until(const TimePoint &abs_time)
 199    {  return this->timed_lock_sharable(abs_time);  }
 200
 201    //!Same as `timed_lock_sharable`, but this function is modeled after the
 202    //!standard library interface.
 203    template<class Duration>  bool try_lock_shared_for(const Duration &dur)
 204    {  return this->timed_lock_sharable(ipcdetail::duration_to_ustime(dur)); }
 205
 206    //!Precondition: The thread must have sharable ownership of the mutex.
 207    //!Effects: The calling thread releases the sharable ownership of the mutex.
 208    //!Throws: An exception derived from interprocess_exception on error.
 209    void unlock_sharable();
 210
 211    //!Same as `unlock_sharable` but with a std-compatible interface
 212    //!
 213    void unlock_shared()
 214    {  this->unlock_sharable();  }
 215
 216    #if !defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
 217    private:
 218    file_handle_t m_file_hnd;
 219
 220    #endif   //#ifndef BOOST_INTERPROCESS_DOXYGEN_INVOKED
 221 };
 222
 223 inline file_lock::file_lock(const char *name)
 224 {
 225    m_file_hnd = ipcdetail::open_existing_file(name, read_write);
 226
 227    if(m_file_hnd == ipcdetail::invalid_file()){
 228       error_info err(system_error_code());
 229       throw interprocess_exception(err);
 230    }
 231 }
 232
 233 #if defined(BOOST_INTERPROCESS_WCHAR_NAMED_RESOURCES) || defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
 234
 235 inline file_lock::file_lock(const wchar_t *name)
 236 {
 237    m_file_hnd = ipcdetail::open_existing_file(name, read_write);
 238
 239    if(m_file_hnd == ipcdetail::invalid_file()){
 240       error_info err(system_error_code());
 241       throw interprocess_exception(err);
 242    }
 243 }
 244
 245 #endif //defined(BOOST_INTERPROCESS_WCHAR_NAMED_RESOURCES) || defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
 246
 247 inline file_lock::~file_lock()
 248 {
 249    if(m_file_hnd != ipcdetail::invalid_file()){
 250       ipcdetail::close_file(m_file_hnd);
 251       m_file_hnd = ipcdetail::invalid_file();
 252    }
 253 }
 254
 255 inline void file_lock::lock()
 256 {
 257    if(!ipcdetail::acquire_file_lock(m_file_hnd)){
 258       error_info err(system_error_code());
 259       throw interprocess_exception(err);
 260    }
 261 }
 262
 263 inline bool file_lock::try_lock()
 264 {
 265    bool result;
 266    if(!ipcdetail::try_acquire_file_lock(m_file_hnd, result)){
 267       error_info err(system_error_code());
 268       throw interprocess_exception(err);
 269    }
 270    return result;
 271 }
 272
 273 template<class TimePoint>
 274 inline bool file_lock::timed_lock(const TimePoint &abs_time)
 275 {  return ipcdetail::try_based_timed_lock(*this, abs_time);   }
 276
 277 inline void file_lock::unlock()
 278 {
 279    if(!ipcdetail::release_file_lock(m_file_hnd)){
 280       error_info err(system_error_code());
 281       throw interprocess_exception(err);
 282    }
 283 }
 284
 285 inline void file_lock::lock_sharable()
 286 {
 287    if(!ipcdetail::acquire_file_lock_sharable(m_file_hnd)){
 288       error_info err(system_error_code());
 289       throw interprocess_exception(err);
 290    }
 291 }
 292
 293 inline bool file_lock::try_lock_sharable()
 294 {
 295    bool result;
 296    if(!ipcdetail::try_acquire_file_lock_sharable(m_file_hnd, result)){
 297       error_info err(system_error_code());
 298       throw interprocess_exception(err);
 299    }
 300    return result;
 301 }
 302
 303 template<class TimePoint>
 304 inline bool file_lock::timed_lock_sharable(const TimePoint &abs_time)
 305 {
 306    ipcdetail::lock_to_sharable<file_lock> lsh(*this);
 307    return ipcdetail::try_based_timed_lock(lsh, abs_time);
 308 }
 309
 310 inline void file_lock::unlock_sharable()
 311 {
 312    if(!ipcdetail::release_file_lock_sharable(m_file_hnd)){
 313       error_info err(system_error_code());
 314       throw interprocess_exception(err);
 315    }
 316 }
 317
 318 }  //namespace interprocess {
 319 }  //namespace boost {
 320
 321 #include <boost/interprocess/detail/config_end.hpp>
 322
 323 #endif   //BOOST_INTERPROCESS_FILE_LOCK_HPP