bslmt_recursivemuteximpl_pthread.h

Go to the documentation of this file.

/// @file bslmt_recursivemuteximpl_pthread.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// bslmt_recursivemuteximpl_pthread.h                                 -*-C++-*-
#ifndef INCLUDED_BSLMT_RECURSIVEMUTEXIMPL_PTHREAD
#define INCLUDED_BSLMT_RECURSIVEMUTEXIMPL_PTHREAD
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup bslmt_recursivemuteximpl_pthread bslmt_recursivemuteximpl_pthread
/// @brief  Provide a POSIX implementation of `bslmt::RecursiveMutex`.
/// @addtogroup bsl
/// @{
/// @addtogroup bslmt
/// @{
/// @addtogroup bslmt_recursivemuteximpl_pthread
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#bslmt_recursivemuteximpl_pthread-purpose"> Purpose</a>
/// * <a href="#bslmt_recursivemuteximpl_pthread-classes"> Classes </a>
/// * <a href="#bslmt_recursivemuteximpl_pthread-description"> Description </a>
///   * <a href="#bslmt_recursivemuteximpl_pthread-usage"> Usage </a>
///
/// # Purpose {#bslmt_recursivemuteximpl_pthread-purpose}
/// Provide a POSIX implementation of `bslmt::RecursiveMutex`.
///
/// # Classes {#bslmt_recursivemuteximpl_pthread-classes}
///
/// -  bslmt::RecursiveMutexImpl<PosixThreads>: POSIX specialization
///
/// @see  bslmt_recursivemutex
///
/// # Description {#bslmt_recursivemuteximpl_pthread-description}
/// This component provides an implementation of
/// `bslmt::RecursiveMutex` for POSIX threads ("pthreads"),
/// `bslmt::RecursiveMutexImpl<PosixThreads>`, via the template specialization:
/// @code
/// bslmt::RecursiveMutexImpl<Platform::PosixThreads>
/// @endcode
/// This template class should not be used (directly) by client code.  Clients
/// should instead use `bslmt::RecursiveMutex`.
///
/// ## Usage {#bslmt_recursivemuteximpl_pthread-usage}
///
///
/// This component is an implementation detail of `bslmt` and is *not* intended
/// for direct client use.  It is subject to change without notice.  As such, a
/// usage example is not provided.
/// @}
/** @} */
/** @} */
 
/** @addtogroup bsl
 * @{
 */
/** @addtogroup bslmt
 * @{
 */
/** @addtogroup bslmt_recursivemuteximpl_pthread
 * @{
 */
 
#include <bslscm_version.h>
 
#include <bslmt_platform.h>
 
#ifdef BSLMT_PLATFORM_POSIX_THREADS
 
// Platform-specific implementation starts here.
 
#include <pthread.h>
 
#ifndef PTHREAD_MUTEX_RECURSIVE
#include <bsls_spinlock.h>
#endif
 
 
namespace bslmt {
 
template <class THREAD_POLICY>
class RecursiveMutexImpl;
 
             // ================================================
             // class RecursiveMutexImpl<Platform::PosixThreads>
             // ================================================
 
/// This class provides a full specialization of `RecursiveMutexImpl` for
/// pthreads.  If the pthreads implementation supports the "recursive"
/// attribute, then the native implementation is used, otherwise, a
/// portable, efficient implementation is provided.
template <>
class RecursiveMutexImpl<Platform::PosixThreads> {
 
    // DATA
    pthread_mutex_t d_lock;       // TBD doc
 
#ifndef PTHREAD_MUTEX_RECURSIVE
    bsls::SpinLock  d_spin;       // spin lock controlling access to this
                                  // object
 
    pthread_t       d_owner;      // thread id of thread currently owning this
                                  // lock object
 
    int             d_lockCount;  // current lock recursion level
#endif
 
  private:
    // NOT IMPLEMENTED
    RecursiveMutexImpl(const RecursiveMutexImpl&);
    RecursiveMutexImpl& operator=(const RecursiveMutexImpl&);
 
  public:
    // CREATORS
 
    /// Create a recursive mutex initialized to an unlocked state.  This
    /// method does not return normally unless there are sufficient system
    /// resources to construct the object.
    RecursiveMutexImpl();
 
    /// Destroy this recursive mutex object.
    ~RecursiveMutexImpl();
 
    // MANIPULATORS
 
    /// Acquire a lock on this mutex object.  If this object is currently
    /// locked by a different thread, then suspend execution of the current
    /// thread until a lock can be acquired.  Otherwise, if it unlocked, or
    /// locked by the calling thread, then grant ownership of the lock immediately and return.  
    /// 
    /// \note Note that   when this object is recursively
    /// locked by a thread, `unlock` must be called an equal number of times
    /// before the lock is actually released.
    void lock();
 
    /// Attempt to acquire a lock on this mutex object.  If this object is
    /// unlocked, or locked by the calling thread, then grant ownership of
    /// the lock immediately and return 0.  Otherwise If this object is
    /// currently locked by a different thread or if an error occurs, then return a non-zero value.  
    /// 
    /// \note Note that   when this object is recursively
    /// locked by a thread, `unlock` must be called an equal number of times
    ///  before the lock is actually released.
    int tryLock();
 
    /// Release a lock on this mutex that was previously acquired through a
    /// successful call to `lock`, or `tryLock`.  The behavior is undefined,
    /// unless the calling thread currently owns the lock on this mutex. 
    /// 
    /// \note Note that   when this object is recursively locked by a thread,
    /// `unlock` must be called an equal number of times before the lock is
    /// actually released.
    void unlock();
};
 
// ============================================================================
//                             INLINE DEFINITIONS
// ============================================================================
 
             // ------------------------------------------------
             // class RecursiveMutexImpl<Platform::PosixThreads>
             // ------------------------------------------------
 
// CREATORS
inline
RecursiveMutexImpl<bslmt::Platform::PosixThreads>::~RecursiveMutexImpl()
{
    pthread_mutex_destroy(&d_lock);
}
 
}  // close package namespace
 
 
#endif // BSLMT_PLATFORM_POSIX_THREADS
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2023 Bloomberg Finance L.P.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------------------- END-OF-FILE ----------------------------------
 
/** @} */
/** @} */
/** @} */