interprocess/sync/named_condition.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_CONDITION_HPP
0012 #define BOOST_INTERPROCESS_NAMED_CONDITION_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
0025 #include <boost/interprocess/sync/cv_status.hpp>
0026 #include <boost/interprocess/creation_tags.hpp>
0027 #include <boost/interprocess/exceptions.hpp>
0028 #include <boost/interprocess/detail/interprocess_tester.hpp>
0029 #include <boost/interprocess/permissions.hpp>
0030 #include <boost/interprocess/sync/detail/locks.hpp>
0031 #if !defined(BOOST_INTERPROCESS_FORCE_GENERIC_EMULATION) && defined (BOOST_INTERPROCESS_WINDOWS)
0032    #include <boost/interprocess/sync/windows/named_condition.hpp>
0033    #define BOOST_INTERPROCESS_NAMED_CONDITION_USE_WINAPI
0034 #else
0035    #include <boost/interprocess/sync/shm/named_condition.hpp>
0036 #endif
0037
0038 //!\file
0039 //!Describes a named condition class for inter-process synchronization
0040
0041 namespace boost {
0042 namespace interprocess {
0043
0044 #if !defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
0045 namespace ipcdetail{ class interprocess_tester; }
0046 #endif   //#ifndef BOOST_INTERPROCESS_DOXYGEN_INVOKED
0047
0048 //! A global condition variable that can be created by name.
0049 //! This condition variable is designed to work with named_mutex and
0050 //! can't be placed in shared memory or memory mapped files.
0051 class named_condition
0052 {
0053    #if !defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
0054    //Non-copyable
0055    named_condition();
0056    named_condition(const named_condition &);
0057    named_condition &operator=(const named_condition &);
0058    #endif   //#ifndef BOOST_INTERPROCESS_DOXYGEN_INVOKED
0059    public:
0060
0061    //!Creates a global condition with a name.
0062    //!If the condition can't be created throws interprocess_exception
0063    named_condition(create_only_t, const char *name, const permissions &perm = permissions());
0064
0065    //!Opens or creates a global condition with a name.
0066    //!If the condition is created, this call is equivalent to
0067    //!named_condition(create_only_t, ... )
0068    //!If the condition is already created, this call is equivalent
0069    //!named_condition(open_only_t, ... )
0070    //!Does not throw
0071    named_condition(open_or_create_t, const char *name, const permissions &perm = permissions());
0072
0073    //!Opens a global condition with a name if that condition is previously
0074    //!created. If it is not previously created this function throws
0075    //!interprocess_exception.
0076    named_condition(open_only_t, const char *name);
0077
0078    //!Opens a global condition with a name if that condition is previously
0079    //!created. If it is not previously created this function throws
0080    //!interprocess_exception.
0081
0082    #if defined(BOOST_INTERPROCESS_WCHAR_NAMED_RESOURCES) || defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
0083    //!Creates a global condition with a name.
0084    //!If the condition can't be created throws interprocess_exception
0085    //!
0086    //!Note: This function is only available on operating systems with
0087    //!      native wchar_t APIs (e.g. Windows).
0088    named_condition(create_only_t, const wchar_t *name, const permissions &perm = permissions());
0089
0090    //!Opens or creates a global condition with a name.
0091    //!If the condition is created, this call is equivalent to
0092    //!named_condition(create_only_t, ... )
0093    //!If the condition is already created, this call is equivalent
0094    //!named_condition(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_condition(open_or_create_t, const wchar_t *name, const permissions &perm = permissions());
0100
0101    //!Opens a global condition with a name if that condition 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_condition(open_only_t, const wchar_t *name);
0108
0109    #endif //#if 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_condition();
0118
0119    //!If there is a thread waiting on *this, change that
0120    //!thread's state to ready. Otherwise there is no effect.*/
0121    void notify_one();
0122
0123    //!Change the state of all threads waiting on *this to ready.
0124    //!If there are no waiting threads, notify_all() has no effect.
0125    void notify_all();
0126
0127    //!Releases the lock on the named_mutex object associated with lock, blocks
0128    //!the current thread of execution until readied by a call to
0129    //!this->notify_one() or this->notify_all(), and then reacquires the lock.
0130    template <typename L>
0131    void wait(L& lock);
0132
0133    //!The same as:
0134    //!while (!pred()) wait(lock)
0135    template <typename L, typename Pr>
0136    void wait(L& lock, Pr pred);
0137
0138    //!Releases the lock on the named_mutex object associated with lock, blocks
0139    //!the current thread of execution until readied by a call to
0140    //!this->notify_one() or this->notify_all(), or until time abs_time is reached,
0141    //!and then reacquires the lock.
0142    //!Returns: false if time abs_time is reached, otherwise true.
0143    template <typename L, class TimePoint>
0144    bool timed_wait(L& lock, const TimePoint &abs_time);
0145
0146    //!The same as:   while (!pred()) {
0147    //!                  if (!timed_wait(lock, abs_time)) return pred();
0148    //!               } return true;
0149    template <typename L, class TimePoint, typename Pr>
0150    bool timed_wait(L& lock, const TimePoint &abs_time, Pr pred);
0151
0152    //!Same as `timed_wait`, but this function is modeled after the
0153    //!standard library interface.
0154    template <typename L, class TimePoint>
0155    cv_status wait_until(L& lock, const TimePoint &abs_time)
0156    {  return this->timed_wait(lock, abs_time) ? cv_status::no_timeout : cv_status::timeout; }
0157
0158    //!Same as `timed_wait`, but this function is modeled after the
0159    //!standard library interface.
0160    template <typename L, class TimePoint, typename Pr>
0161    bool wait_until(L& lock, const TimePoint &abs_time, Pr pred)
0162    {  return this->timed_wait(lock, abs_time, pred); }
0163
0164    //!Same as `timed_wait`, but this function is modeled after the
0165    //!standard library interface and uses relative timeouts.
0166    template <typename L, class Duration>
0167    cv_status wait_for(L& lock, const Duration &dur)
0168    {  return this->wait_until(lock, ipcdetail::duration_to_ustime(dur)); }
0169
0170    //!Same as `timed_wait`, but this function is modeled after the
0171    //!standard library interface and uses relative timeouts
0172    template <typename L, class Duration, typename Pr>
0173    bool wait_for(L& lock, const Duration &dur, Pr pred)
0174    {  return this->wait_until(lock, ipcdetail::duration_to_ustime(dur), pred); }
0175
0176    //!Erases a named condition from the system.
0177    //!Returns false on error. Never throws.
0178    static bool remove(const char *name);
0179
0180    #if defined(BOOST_INTERPROCESS_WCHAR_NAMED_RESOURCES) || defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
0181
0182    //!Erases a named condition from the system.
0183    //!Returns false on error. Never throws.
0184    //!
0185    //!Note: This function is only available on operating systems with
0186    //!      native wchar_t APIs (e.g. Windows).
0187    static bool remove(const wchar_t *name);
0188
0189    #endif //defined(BOOST_INTERPROCESS_WCHAR_NAMED_RESOURCES) || defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
0190
0191    #if !defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
0192    private:
0193    #if defined(BOOST_INTERPROCESS_NAMED_CONDITION_USE_WINAPI)
0194    typedef ipcdetail::winapi_named_condition   condition_type;
0195    #else
0196    typedef ipcdetail::shm_named_condition       condition_type;
0197    #endif
0198    condition_type m_cond;
0199
0200    friend class ipcdetail::interprocess_tester;
0201    void dont_close_on_destruction()
0202    {  ipcdetail::interprocess_tester::dont_close_on_destruction(m_cond); }
0203    #endif   //#ifndef BOOST_INTERPROCESS_DOXYGEN_INVOKED
0204 };
0205
0206 #if !defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
0207
0208 inline named_condition::~named_condition()
0209 {}
0210
0211 inline named_condition::named_condition(create_only_t, const char *name, const permissions &perm)
0212    :  m_cond(create_only_t(), name, perm)
0213 {}
0214
0215 inline named_condition::named_condition(open_or_create_t, const char *name, const permissions &perm)
0216    :  m_cond(open_or_create_t(), name, perm)
0217 {}
0218
0219 inline named_condition::named_condition(open_only_t, const char *name)
0220    :  m_cond(open_only_t(), name)
0221 {}
0222
0223 #if defined(BOOST_INTERPROCESS_WCHAR_NAMED_RESOURCES) || defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
0224
0225 inline named_condition::named_condition(create_only_t, const wchar_t *name, const permissions &perm)
0226    :  m_cond(create_only_t(), name, perm)
0227 {}
0228
0229 inline named_condition::named_condition(open_or_create_t, const wchar_t *name, const permissions &perm)
0230    :  m_cond(open_or_create_t(), name, perm)
0231 {}
0232
0233 inline named_condition::named_condition(open_only_t, const wchar_t *name)
0234    :  m_cond(open_only_t(), name)
0235 {}
0236
0237 #endif //#if defined(BOOST_INTERPROCESS_WCHAR_NAMED_RESOURCES) || defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
0238
0239
0240 inline void named_condition::notify_one()
0241 {  m_cond.notify_one();  }
0242
0243 inline void named_condition::notify_all()
0244 {  m_cond.notify_all();  }
0245
0246 template <typename L>
0247 inline void named_condition::wait(L& lock)
0248 {
0249    ipcdetail::internal_mutex_lock<L> internal_lock(lock);
0250    m_cond.wait(internal_lock);
0251 }
0252
0253 template <typename L, typename Pr>
0254 inline void named_condition::wait(L& lock, Pr pred)
0255 {
0256    ipcdetail::internal_mutex_lock<L> internal_lock(lock);
0257    m_cond.wait(internal_lock, pred);
0258 }
0259
0260 template <typename L, typename TimePoint>
0261 inline bool named_condition::timed_wait
0262    (L& lock, const TimePoint &abs_time)
0263 {
0264    ipcdetail::internal_mutex_lock<L> internal_lock(lock);
0265    return m_cond.timed_wait(internal_lock, abs_time);
0266 }
0267
0268 template <typename L, typename TimePoint, typename Pr>
0269 inline bool named_condition::timed_wait
0270    (L& lock, const TimePoint &abs_time, Pr pred)
0271 {
0272    ipcdetail::internal_mutex_lock<L> internal_lock(lock);
0273    return m_cond.timed_wait(internal_lock, abs_time, pred);
0274 }
0275
0276 inline bool named_condition::remove(const char *name)
0277 {
0278    return condition_type::remove(name);
0279 }
0280
0281 #if defined(BOOST_INTERPROCESS_WCHAR_NAMED_RESOURCES) || defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
0282
0283 inline bool named_condition::remove(const wchar_t *name)
0284 {
0285    return condition_type::remove(name);
0286 }
0287
0288 #endif
0289
0290
0291 #endif   //#ifndef BOOST_INTERPROCESS_DOXYGEN_INVOKED
0292
0293 }  //namespace interprocess
0294 }  //namespace boost
0295
0296 #include <boost/interprocess/detail/config_end.hpp>
0297
0298 #endif // BOOST_INTERPROCESS_NAMED_CONDITION_HPP