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