ncbimtx.hpp

ncbi源码

//    CAutoRW::
//    CReadLockGuard::
//    CWriteLockGuard::
//


// Forward declaration of internal (platform-dependent) RW-lock representation
class CInternalRWLock;
class CReadLockGuard;
class CWriteLockGuard;



/////////////////////////////////////////////////////////////////////////////
///
/// CRWLock --
///
/// Read/Write lock related data and methods.
///
/// Allows multiple readers or single writer with recursive locks.
/// R-after-W is considered to be a recursive Write-lock. W-after-R is not
/// allowed.
///
/// NOTE: When _DEBUG is not defined, does not always detect W-after-R
/// correctly, so that deadlock may happen. Test your application
/// in _DEBUG mode first!

class NCBI_XNCBI_EXPORT CRWLock
{
public:
    /// Constructor.
    CRWLock(void);

    /// Destructor.
    ~CRWLock(void);

    /// Define Read Lock Guard.
    typedef CReadLockGuard TReadLockGuard;

    /// Define Write Lock Guard.
    typedef CWriteLockGuard TWriteLockGuard;

    /// Read lock.
    ///
    /// Acquire the R-lock. If W-lock is already acquired by
    /// another thread, then wait until it is released.
    void ReadLock(void);

    /// Write lock.
    ///
    /// Acquire the W-lock. If R-lock or W-lock is already acquired by
    /// another thread, then wait until it is released.
    void WriteLock(void);

    /// Try read lock.
    ///
    /// Try to acquire R-lock and return immediately.
    /// @return
    ///   TRUE if the R-lock has been successfully acquired;
    ///   FALSE, otherwise.
    bool TryReadLock(void);

    /// Try write lock.
    ///
    /// Try to acquire W-lock and return immediately.
    /// @return
    ///   TRUE if the W-lock has been successfully acquired;
    ///   FALSE, otherwise.
    bool TryWriteLock(void);

    /// Release the RW-lock.
    void Unlock(void);

private:
    
    auto_ptr<CInternalRWLock>  m_RW;    ///< Platform-dependent RW-lock data
    
    volatile CThreadSystemID   m_Owner; ///< Writer ID, one of the readers ID
    
    volatile int               m_Count; ///< Number of readers (if >0) or
                                        ///< writers (if <0)

    
    vector<CThreadSystemID>    m_Readers;   ///< List of all readers or writers
                                            ///< for debugging
    
    /// Private copy constructor to disallow initialization.
    CRWLock(const CRWLock&);
                           
    /// Private assignment operator to disallow assignment.
    CRWLock& operator= (const CRWLock&);
};



/////////////////////////////////////////////////////////////////////////////
///
/// CAutoRW --
///
/// Guarantee RW-lock release.
///
/// Acts in a way like "auto_ptr<>": guarantees RW-Lock release.

class CAutoRW
{
public:
    /// Constructor.
    ///
    /// Register the RW-lock to be released by the guard destructor.
    /// Do NOT acquire the RW-lock though!
    CAutoRW(void) : m_RW(0)
        {
        }

    /// Destructor.
    ///
    /// Release the R-lock, if it was successfully acquired and
    /// not released already by Release().
    ~CAutoRW(void)
        {
            Release();
        }

    /// Release the RW-lock right now - don't release it in the guard
    /// destructor.
    void Release(void)
        {
            if ( m_RW ) {
                m_RW->Unlock();
                m_RW = 0;
            }
        }

protected:
    /// Get the RW-lock being guarded.
    CRWLock* GetRW(void) const { return m_RW; }

    CRWLock* m_RW;  /// The RW-lock -- NULL if not acquired.

    /// Private copy constructor to disallow initialization.
    CAutoRW(const CAutoRW&);

    /// Private assignment operator to disallow assignment.
    CAutoRW& operator= (const CAutoRW&);
};



/////////////////////////////////////////////////////////////////////////////
///
/// CReadLockGuard --
///
/// Acquire the R-lock, then guarantee for its release.

class CReadLockGuard : public CAutoRW
{
public:
    /// Constructor.
    ///
    /// Default constructor - do nothing.
    CReadLockGuard(void)
        {
        }

    /// Constructor.
    ///
    /// Acquire the R-lock;  register it to be released by the guard
    /// destructor.
    CReadLockGuard(CRWLock& rw)
        {
            rw.ReadLock();
            m_RW = &rw;
        }

    void Guard(CRWLock& rw)
        {
            if ( &rw != m_RW ) {
                Release();
                rw.ReadLock();
                m_RW = &rw;
            }
        }

private:
    /// Private copy constructor to disallow initialization.
    CReadLockGuard(const CReadLockGuard&);

    /// Private assignment operator to disallow assignment.
    CReadLockGuard& operator= (const CReadLockGuard&);
};



/////////////////////////////////////////////////////////////////////////////
///
/// CWriteLockGuard --
///
/// Acquire the W-lock, then guarantee for its release.

class CWriteLockGuard : public CAutoRW
{
public:
    /// Constructor.
    ///
    /// Default constructor - do nothing.
    CWriteLockGuard(void)
        {
        }

    /// Constructor.
    ///
    /// Acquire the W-lock;  register it to be released by the guard
    /// destructor.
    CWriteLockGuard(CRWLock& rw)
        {
            rw.WriteLock();
            m_RW = &rw;
        }

    void Guard(CRWLock& rw)
        {
            if ( &rw != m_RW ) {
                Release();
                rw.WriteLock();
                m_RW = &rw;
            }
        }

private:
    /// Private copy constructor to disallow initialization.
    CWriteLockGuard(const CWriteLockGuard&);

    /// Private assignment operator to disallow assignment.
    CWriteLockGuard& operator= (const CWriteLockGuard&);
};



/////////////////////////////////////////////////////////////////////////////
///
/// CSemaphore --
///
/// Implement the semantics of an application-wide semaphore.

class NCBI_XNCBI_EXPORT CSemaphore
{
public:
    /// Constructor.
    ///
    /// @param
    ///   int_count   The initial value of the semaphore.
    ///   max_count   Maximum value that semaphore value can be incremented to.
    CSemaphore(unsigned int init_count, unsigned int max_count);

    /// Destructor.
    ///
    /// Report error if the semaphore is locked.
    ~CSemaphore(void);

    /// Wait on semaphore.
    ///
    /// Decrement the counter by one. If the semaphore's count is zero then
    /// wait until it's not zero.
    void Wait(void);

    /// Timed wait.
    ///
    /// Wait up to timeout_sec + timeout_nsec/1E9 seconds for the
    /// semaphore's count to exceed zero.  If that happens, decrement
    /// the counter by one and return TRUE; otherwise, return FALSE.
    bool TryWait(unsigned int timeout_sec = 0, unsigned int timeout_nsec = 0);

    /// Increment the semaphore by "count".
    ///
    /// Do nothing and throw an exception if counter would exceed "max_count".
    void Post(unsigned int count = 1);

private:
    struct SSemaphore* m_Sem;  ///< System-specific semaphore data.

    /// Private copy constructor to disallow initialization.
    CSemaphore(const CSemaphore&);

    /// Private assignment operator to disallow assignment.
    CSemaphore& operator= (const CSemaphore&);
};


/* @} */


#include <corelib/ncbimtx.inl>

/////////////////////////////////////////////////////////////////////////////

END_NCBI_SCOPE


/*
 * ===========================================================================
 * $Log: ncbimtx.hpp,v $
 * Revision 1000.2  2004/04/21 14:34:52  gouriano
 * PRODUCTION: UPGRADED [CATCHUP_003] Dev-tree R1.35
 *
 * Revision 1.35  2004/03/10 20:00:24  gorelenk
 * Added NCBI_XNCBI_EXPORT prefix to SSystemMutex struct members Lock, Unlock,
 * Trylock.
 *
 * Revision 1.34  2004/03/10 18:40:21  gorelenk
 * Added/Removed NCBI_XNCBI_EXPORT prefixes.
 *
 * Revision 1.33  2004/03/10 17:34:05  gorelenk
 * Removed NCBI_XNCBI_EXPORT prefix for classes members-functions
 * that are implemented as a inline functions.
 *
 * Revision 1.32  2003/10/30 14:56:27  siyan
 * Added a test for @sa hyperlink.
 *
 * Revision 1.31  2003/09/30 16:07:39  vasilche
 * Allow release and reacqure rw lock in guard.
 *
 * Revision 1.30  2003/09/29 20:50:30  ivanov
 * Removed CAutoInitializeStaticBase
 *
 * Revision 1.29  2003/09/17 18:09:05  vasilche
 * Removed unnecessary assignment operator - it causes problems on MSVC.
 *
 * Revision 1.28  2003/09/17 17:56:46  vasilche
 * Fixed volatile methods of CThreadSystemID.
 *
 * Revision 1.27  2003/09/17 15:20:45  vasilche
 * Moved atomic counter swap functions to separate file.
 * Added CRef<>::AtomicResetFrom(), CRef<>::AtomicReleaseTo() methods.
 *
 * Revision 1.26  2003/09/02 16:36:50  vasilche
 * Fixed warning on MSVC.
 *
 * Revision 1.25  2003/09/02 16:08:48  vasilche
 * Fixed race condition with optimization on some compilers - added 'volatile'.
 * Moved mutex Lock/Unlock methods out of inline section - they are quite complex.
 *
 * Revision 1.24  2003/09/02 15:06:14  siyan
 * Minor comment changes.
 *
 * Revision 1.23  2003/08/27 12:35:15  siyan
 * Added documentation.
 *
 * Revision 1.22  2003/06/19 18:21:15  vasilche
 * Added default constructors to CFastMutexGuard and CMutexGuard.
 * Added typedefs TReadLockGuard and TWriteLockGuard to mutexes and rwlock.
 *
 * Revision 1.21  2003/03/31 13:30:31  siyan
 * Minor changes to doxygen support
 *
 * Revision 1.20  2003/03/31 13:09:19  siyan
 * Added doxygen support
 *
 * Revision 1.19  2002/12/18 22:53:21  dicuccio
 * Added export specifier for building DLLs in windows.  Added global list of
 * all such specifiers in mswin_exports.hpp, included through ncbistl.hpp
 *
 * Revision 1.18  2002/09/23 13:58:29  vasilche
 * MS VC 6 doesn't accept empty initialization block
 *
 * Revision 1.17  2002/09/23 13:47:23  vasilche
 * Made static mutex structures POD-types on Win32
 *
 * Revision 1.16  2002/09/20 20:02:07  vasilche
 * Added public Lock/Unlock/TryLock
 *
 * Revision 1.15  2002/09/20 19:28:21  vasilche
 * Fixed missing initialization with NCBI_NO_THREADS
 *
 * Revision 1.14  2002/09/20 19:13:58  vasilche
 * Fixed single-threaded mode on Win32
 *
 * Revision 1.13  2002/09/20 13:51:56  vasilche
 * Added #include <memory> for auto_ptr<>
 *
 * Revision 1.12  2002/09/19 20:05:41  vasilche
 * Safe initialization of static mutexes
 *
 * Revision 1.11  2002/08/19 19:37:17  vakatov
 * Use <corelib/ncbi_os_mswin.hpp> in the place of <windows.h>
 *
 * Revision 1.10  2002/08/19 18:15:58  ivanov
 * +include <corelib/winundef.hpp>
 *
 * Revision 1.9  2002/07/15 18:17:51  gouriano
 * renamed CNcbiException and its descendents
 *
 * Revision 1.8  2002/07/11 14:17:54  gouriano
 * exceptions replaced by CNcbiException-type ones
 *
 * Revision 1.7  2002/04/11 20:39:18  ivanov
 * CVS log moved to end of the file
 *
 * Revision 1.6  2002/01/23 23:31:17  vakatov
 * Added CFastMutexGuard::Guard()
 *
 * Revision 1.5  2001/05/17 14:53:50  lavr
 * Typos corrected
 *
 * Revision 1.4  2001/04/16 18:45:28  vakatov
 * Do not include system MT-related headers if in single-thread mode
 *
 * Revision 1.3  2001/03/26 22:50:24  grichenk
 * Fixed CFastMutex::Unlock() bug
 *
 * Revision 1.2  2001/03/26 21:11:37  vakatov
 * Allow use of not yet initialized mutexes (with A.Grichenko)
 *
 * Revision 1.1  2001/03/13 22:34:24  vakatov
 * Initial revision
 *
 * ===========================================================================
 */

#endif  /* NCBIMTX__HPP */