interprocess/sync/named_mutex.hpp

0001 //////////////////////////////////////////////////////////////////////////////
0002 //
0003 // (C) Copyright Ion Gaztanaga 2005-2012. Distributed under the Boost
0004 // Software License, Version 1.0. (See accompanying file
0005 // LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0006 //
0007 // See http://www.boost.org/libs/interprocess for documentation.
0008 //
0009 //////////////////////////////////////////////////////////////////////////////
0010
0011 #ifndef BOOST_INTERPROCESS_NAMED_MUTEX_HPP
0012 #define BOOST_INTERPROCESS_NAMED_MUTEX_HPP
0013
0014 #ifndef BOOST_CONFIG_HPP
0015 #  include <boost/config.hpp>
0016 #endif
0017 0018 ">#
0019 #if defined(BOOST_HAS_PRAGMA_ONCE)
0020 #  pragma once
0021 #endif
0022
0023 #include <boost/interprocess/detail/config_begin.hpp>
0024 #include <boost/interprocess/detail/workaround.hpp>
0025 #include <boost/interprocess/creation_tags.hpp>
0026 #include <boost/interprocess/exceptions.hpp>
0027 #include <boost/interprocess/timed_utils.hpp>
0028 #include <boost/interprocess/detail/interprocess_tester.hpp>
0029 #include <boost/interprocess/permissions.hpp>
0030
0031 #if defined(BOOST_INTERPROCESS_NAMED_MUTEX_USES_POSIX_SEMAPHORES)
0032    #include <boost/interprocess/sync/posix/named_mutex.hpp>
0033    #define BOOST_INTERPROCESS_NAMED_MUTEX_USE_POSIX
0034 #elif !defined(BOOST_INTERPROCESS_FORCE_GENERIC_EMULATION) && defined (BOOST_INTERPROCESS_WINDOWS)
0035    #include <boost/interprocess/sync/windows/named_mutex.hpp>
0036    #define BOOST_INTERPROCESS_NAMED_MUTEX_USE_WINAPI
0037 #else
0038    #include <boost/interprocess/sync/shm/named_mutex.hpp>
0039 #endif
0040
0041 //!\file
0042 //!Describes a named mutex class for inter-process synchronization
0043
0044 namespace boost {
0045 namespace interprocess {
0046
0047 class named_condition;
0048
0049 //!A mutex with a global name, so it can be found from different
0050 //!processes. This mutex can't be placed in shared memory, and
0051 //!each process should have it's own named_mutex.
0052 class named_mutex
0053 {
0054    #if !defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
0055
0056    //Non-copyable
0057    named_mutex();
0058    named_mutex(const named_mutex &);
0059    named_mutex &operator=(const named_mutex &);
0060    friend class named_condition;
0061    #endif   //#ifndef BOOST_INTERPROCESS_DOXYGEN_INVOKED
0062
0063    public:
0064    //!Creates a global mutex with a name.
0065    //!Throws interprocess_exception on error.
0066    named_mutex(create_only_t, const char *name, const permissions &perm = permissions());
0067
0068    //!Opens or creates a global mutex with a name.
0069    //!If the mutex is created, this call is equivalent to
0070    //!named_mutex(create_only_t, ... )
0071    //!If the mutex is already created, this call is equivalent
0072    //!named_mutex(open_only_t, ... )
0073    //!Does not throw
0074    named_mutex(open_or_create_t, const char *name, const permissions &perm = permissions());
0075
0076    //!Opens a global mutex with a name if that mutex is previously
0077    //!created. If it is not previously created this function throws
0078    //!interprocess_exception.
0079    named_mutex(open_only_t, const char *name);
0080
0081    #if defined(BOOST_INTERPROCESS_WCHAR_NAMED_RESOURCES) || defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
0082
0083    //!Creates a global mutex with a name.
0084    //!Throws interprocess_exception on error.
0085    //!
0086    //!Note: This function is only available on operating systems with
0087    //!      native wchar_t APIs (e.g. Windows).
0088    named_mutex(create_only_t, const wchar_t *name, const permissions &perm = permissions());
0089
0090    //!Opens or creates a global mutex with a name.
0091    //!If the mutex is created, this call is equivalent to
0092    //!named_mutex(create_only_t, ... )
0093    //!If the mutex is already created, this call is equivalent
0094    //!named_mutex(open_only_t, ... )
0095    //!Does not throw
0096    //!
0097    //!Note: This function is only available on operating systems with
0098    //!      native wchar_t APIs (e.g. Windows).
0099    named_mutex(open_or_create_t, const wchar_t *name, const permissions &perm = permissions());
0100
0101    //!Opens a global mutex with a name if that mutex is previously
0102    //!created. If it is not previously created this function throws
0103    //!interprocess_exception.
0104    //!
0105    //!Note: This function is only available on operating systems with
0106    //!      native wchar_t APIs (e.g. Windows).
0107    named_mutex(open_only_t, const wchar_t *name);
0108
0109    #endif   //defined(BOOST_INTERPROCESS_WCHAR_NAMED_RESOURCES) || defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
0110
0111    //!Destroys *this and indicates that the calling process is finished using
0112    //!the resource. The destructor function will deallocate
0113    //!any system resources allocated by the system for use by this process for
0114    //!this resource. The resource can still be opened again calling
0115    //!the open constructor overload. To erase the resource from the system
0116    //!use remove().
0117    ~named_mutex();
0118
0119    //!Unlocks a previously locked
0120    //!mutex.
0121    void unlock();
0122
0123    //!Requires: The calling thread does not own the mutex.
0124    //!
0125    //!Locks the mutex, sleeps when the mutex is already locked.
0126    //!Throws interprocess_exception if a severe error is found
0127    //!
0128    //!Note: A program may deadlock if the thread that has ownership calls
0129    //!   this function. If the implementation can detect the deadlock,
0130    //!   an exception could be thrown.
0131    void lock();
0132
0133    //!Requires: The calling thread does not own the mutex.
0134    //!
0135    //!Tries to lock the mutex, returns false when the mutex
0136    //!is already locked, returns true when success.
0137    //!Throws interprocess_exception if a severe error is found
0138    //!
0139    //!Note: A program may deadlock if the thread that has ownership calls
0140    //!   this function. If the implementation can detect the deadlock,
0141    //!   an exception could be thrown.
0142    bool try_lock();
0143
0144    //!Requires: The calling thread does not own the mutex.
0145    //!
0146    //!Tries to lock the the mutex until time abs_time,
0147    //!Returns false when timeout expires, returns true when locks.
0148    //!Throws interprocess_exception if a severe error is found
0149    //!
0150    //!Note: A program may deadlock if the thread that has ownership calls
0151    //!   this function. If the implementation can detect the deadlock,
0152    //!   an exception could be thrown.
0153    template<class TimePoint>
0154    bool timed_lock(const TimePoint &abs_time);
0155
0156    //!Same as `timed_lock`, but this function is modeled after the
0157    //!standard library interface.
0158    template<class TimePoint> bool try_lock_until(const TimePoint &abs_time)
0159    {  return this->timed_lock(abs_time);  }
0160
0161    //!Same as `timed_lock`, but this function is modeled after the
0162    //!standard library interface.
0163    template<class Duration>  bool try_lock_for(const Duration &dur)
0164    {  return this->timed_lock(ipcdetail::duration_to_ustime(dur)); }
0165
0166    //!Erases a named mutex from the system.
0167    //!Returns false on error. Never throws.
0168    static bool remove(const char *name);
0169
0170    #if defined(BOOST_INTERPROCESS_WCHAR_NAMED_RESOURCES) || defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
0171
0172    //!Erases a named mutex from the system.
0173    //!Returns false on error. Never throws.
0174    //!
0175    //!Note: This function is only available on operating systems with
0176    //!      native wchar_t APIs (e.g. Windows).
0177    static bool remove(const wchar_t *name);
0178
0179    #endif   //defined(BOOST_INTERPROCESS_WCHAR_NAMED_RESOURCES) || defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
0180
0181    #if !defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
0182    private:
0183    friend class ipcdetail::interprocess_tester;
0184    void dont_close_on_destruction();
0185
0186    public:
0187    #if defined(BOOST_INTERPROCESS_NAMED_MUTEX_USE_POSIX)
0188       typedef ipcdetail::posix_named_mutex      internal_mutex_type;
0189    #elif defined(BOOST_INTERPROCESS_NAMED_MUTEX_USE_WINAPI)
0190       typedef ipcdetail::winapi_named_mutex    internal_mutex_type;
0191    #else
0192       typedef ipcdetail::shm_named_mutex        internal_mutex_type;
0193    #endif
0194    internal_mutex_type &internal_mutex()
0195    {  return m_mut; }
0196
0197    internal_mutex_type m_mut;
0198
0199    #endif   //#ifndef BOOST_INTERPROCESS_DOXYGEN_INVOKED
0200 };
0201
0202 #if !defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
0203
0204 inline named_mutex::named_mutex(create_only_t, const char *name, const permissions &perm)
0205    :  m_mut(create_only_t(), name, perm)
0206 {}
0207
0208 inline named_mutex::named_mutex(open_or_create_t, const char *name, const permissions &perm)
0209    :  m_mut(open_or_create_t(), name, perm)
0210 {}
0211
0212 inline named_mutex::named_mutex(open_only_t, const char *name)
0213    :  m_mut(open_only_t(), name)
0214 {}
0215
0216 #if defined(BOOST_INTERPROCESS_WCHAR_NAMED_RESOURCES) || defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
0217
0218 inline named_mutex::named_mutex(create_only_t, const wchar_t *name, const permissions &perm)
0219    :  m_mut(create_only_t(), name, perm)
0220 {}
0221
0222 inline named_mutex::named_mutex(open_or_create_t, const wchar_t *name, const permissions &perm)
0223    :  m_mut(open_or_create_t(), name, perm)
0224 {}
0225
0226 inline named_mutex::named_mutex(open_only_t, const wchar_t *name)
0227    :  m_mut(open_only_t(), name)
0228 {}
0229
0230 #endif   //defined(BOOST_INTERPROCESS_WCHAR_NAMED_RESOURCES) || defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
0231
0232 inline void named_mutex::dont_close_on_destruction()
0233 {  ipcdetail::interprocess_tester::dont_close_on_destruction(m_mut); }
0234
0235 inline named_mutex::~named_mutex()
0236 {}
0237
0238 inline void named_mutex::lock()
0239 {  m_mut.lock();  }
0240
0241 inline void named_mutex::unlock()
0242 {  m_mut.unlock();  }
0243
0244 inline bool named_mutex::try_lock()
0245 {  return m_mut.try_lock();  }
0246
0247 template<class TimePoint>
0248 inline bool named_mutex::timed_lock(const TimePoint &abs_time)
0249 {  return m_mut.timed_lock(abs_time);  }
0250
0251 inline bool named_mutex::remove(const char *name)
0252 {  return internal_mutex_type::remove(name);   }
0253
0254 #if defined(BOOST_INTERPROCESS_WCHAR_NAMED_RESOURCES) || defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
0255
0256 inline bool named_mutex::remove(const wchar_t *name)
0257 {  return internal_mutex_type::remove(name);   }
0258
0259 #endif
0260
0261 #endif   //#ifndef BOOST_INTERPROCESS_DOXYGEN_INVOKED
0262
0263 }  //namespace interprocess {
0264 }  //namespace boost {
0265
0266 #include <boost/interprocess/detail/config_end.hpp>
0267
0268 #endif   //BOOST_INTERPROCESS_NAMED_MUTEX_HPP