mutex.cpp

Go to the documentation of this file.

// Copyright (c) 2013-2025  Made to Order Software Corp.  All Rights Reserved
//
// https://snapwebsites.org/project/cppthread
// contact@m2osw.com
//
// This program is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation; either version 2 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License along
// with this program; if not, write to the Free Software Foundation, Inc.,
// 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
// self
//
#include    "cppthread/mutex.h"
 
#include    "cppthread/exception.h"
#include    "cppthread/guard.h"
#include    "cppthread/log.h"
 
 
// snapdev
//
#include    <snapdev/timespec_ex.h>
 
 
// C
//
#include    <string.h>
#include    <sys/time.h>
 
 
// last include
//
#include    <snapdev/poison.h>
 
 
 
 
namespace cppthread
{
 
 
 
namespace detail
{
 
 
 
class mutex_impl
{
public:
    pthread_mutex_t     f_mutex = pthread_mutex_t();
    pthread_cond_t      f_condition = pthread_cond_t();
};
 
 
}
 
 
 
mutex::mutex()
    : f_impl(std::make_shared<detail::mutex_impl>())
{
    // initialize the mutex
    pthread_mutexattr_t mattr;
    int err(pthread_mutexattr_init(&mattr));
    if(err != 0)
    {
        log << log_level_t::fatal
            << "a mutex attribute structure could not be initialized, error #"
            << err
            << end;
        throw invalid_error("pthread_muteattr_init() failed");
    }
    err = pthread_mutexattr_settype(&mattr, PTHREAD_MUTEX_RECURSIVE);
    if(err != 0)
    {
        log << log_level_t::fatal
            << "a mutex attribute structure type could not be setup, error #"
            << err
            << end;
        pthread_mutexattr_destroy(&mattr);
        throw invalid_error("pthread_muteattr_settype() failed");
    }
    err = pthread_mutex_init(&f_impl->f_mutex, &mattr);
    if(err != 0)
    {
        log << log_level_t::fatal
            << "a mutex structure could not be initialized, error #"
            << err
            << end;
        pthread_mutexattr_destroy(&mattr);
        throw invalid_error("pthread_mutex_init() failed");
    }
    err = pthread_mutexattr_destroy(&mattr);
    if(err != 0)
    {
        log << log_level_t::fatal
            << "a mutex attribute structure could not be destroyed, error #"
            << err
            << end;
        pthread_mutex_destroy(&f_impl->f_mutex);
        throw invalid_error("pthread_mutexattr_destroy() failed");
    }
 
    // initialize the condition
    pthread_condattr_t cattr;
    err = pthread_condattr_init(&cattr);
    if(err != 0)
    {
        log << log_level_t::fatal
            << "a mutex condition attribute structure could not be initialized, error #"
            << err
            << end;
        pthread_mutex_destroy(&f_impl->f_mutex);
        throw invalid_error("pthread_condattr_init() failed");
    }
    err = pthread_cond_init(&f_impl->f_condition, &cattr);
    if(err != 0)
    {
        log << log_level_t::fatal
            << "a mutex condition structure could not be initialized, error #"
            << err
            << end;
        pthread_condattr_destroy(&cattr);
        pthread_mutex_destroy(&f_impl->f_mutex);
        throw invalid_error("pthread_cond_init() failed");
    }
    err = pthread_condattr_destroy(&cattr);
    if(err != 0)
    {
        log << log_level_t::fatal
            << "a mutex condition attribute structure could not be destroyed, error #"
            << err
            << end;
        pthread_mutex_destroy(&f_impl->f_mutex);
        throw invalid_error("pthread_condattr_destroy() failed");
    }
}
 
 
mutex::~mutex()
{
    // Note that the following reference count test only ensure that
    // you don't delete a mutex which is still locked; however, if
    // you still have multiple threads running, we can't really know
    // if another thread is not just about to use this thread...
    //
    if(f_reference_count != 0UL)
    {
        // we cannot legally throw in a destructor so we instead generate a fatal error
        //
        log << log_level_t::fatal
            << "a mutex is being destroyed when its reference count is "
            << f_reference_count
            << " instead of zero."
            << end;
        std::terminate();
    }
    int err(pthread_cond_destroy(&f_impl->f_condition));
    if(err != 0)
    {
        log << log_level_t::error
            << "a mutex condition destruction generated error #"
            << err
            << end;
    }
    err = pthread_mutex_destroy(&f_impl->f_mutex);
    if(err != 0)
    {
        log << log_level_t::fatal
            << "a mutex destruction generated error #"
            << err
            << end;
    }
}
 
 
void mutex::lock()
{
    int const err(pthread_mutex_lock(&f_impl->f_mutex));
    if(err != 0)
    {
        log << log_level_t::error
            << "a mutex lock generated error #"
            << err
            << " -- "
            << strerror(err)
            << end;
        throw invalid_error("pthread_mutex_lock() failed");
    }
 
    // note: we do not need an atomic call since we
    //       already know we are running alone here...
    ++f_reference_count;
}
 
 
bool mutex::try_lock()
{
    int const err(pthread_mutex_trylock(&f_impl->f_mutex));
    if(err == 0)
    {
        // note: we do not need an atomic call since we
        //       already know we are running alone here...
        ++f_reference_count;
        return true;
    }
 
    // failed because another thread has the lock?
    if(err == EBUSY)
    {
        return false;
    }
 
    // another type of failure
    log << log_level_t::error
        << "a mutex try lock generated error #"
        << err
        << " -- "
        << strerror(err)
        << end;
    throw invalid_error("pthread_mutex_trylock() failed");
}
 
 
void mutex::unlock()
{
    // We can't unlock if it wasn't locked before!
    if(f_reference_count <= 0UL)
    {
        log << log_level_t::fatal
            << "attempting to unlock a mutex when it is still locked "
            << f_reference_count
            << " times"
            << end;
        throw not_locked_error("unlock was called too many times");
    }
 
    // NOTE: we do not need an atomic call since we
    //       already know we are running alone here...
    --f_reference_count;
 
    int const err(pthread_mutex_unlock(&f_impl->f_mutex));
    if(err != 0)
    {
        log << log_level_t::fatal
            << "a mutex unlock generated error #"
            << err
            << " -- "
            << strerror(err)
            << end;
        throw invalid_error("pthread_mutex_unlock() failed");
    }
}
 
 
void mutex::wait()
{
    // For any mutex wait to work, we MUST have the
    // mutex locked already and just one time.
    //
    // note: the 1 time is just for assurance that it will
    //       work in most cases; it should work even when locked
    //       multiple times, but it is less likely. For sure, it
    //       has to be at least once.
    //if(f_reference_count != 1UL)
    //{
    //    log << log_level_t::fatal
    //        << "attempting to wait on a mutex when it is not locked exactly once, current count is "
    //        << f_reference_count
    //        << end;
    //    throw exception_not_locked_once_error();
    //}
    int const err(pthread_cond_wait(&f_impl->f_condition, &f_impl->f_mutex));
    if(err != 0)
    {
        // an error occurred!
        log << log_level_t::fatal
            << "a mutex conditional wait generated error #"
            << err
            << " -- "
            << strerror(err)
            << end;
        throw mutex_failed_error("pthread_cond_wait() failed");
    }
}
 
 
bool mutex::timed_wait(std::uint64_t const usecs)
{
    return timed_wait(timespec{
              static_cast<time_t>(usecs / 1'000'000ULL)
            , static_cast<long>((usecs % 1'000'000ULL) * 1'000ULL)
        });
}
 
 
bool mutex::timed_wait(timespec const & nsecs)
{
    int err(0);
 
    // get clock time (a.k.a. now)
    //
    snapdev::timespec_ex abstime(snapdev::timespec_ex::gettime());
 
    // now + user specified nsecs
    //
    abstime += nsecs;
 
    err = pthread_cond_timedwait(
              &f_impl->f_condition
            , &f_impl->f_mutex
            , &abstime);
    if(err != 0)
    {
        if(err == ETIMEDOUT)
        {
            return false;
        }
 
        // an error occurred!
        log << log_level_t::fatal
            << "a mutex conditional timed wait generated error #"
            << err
            << " -- "
            << strerror(err)
            << " (time out sec = "
            << abstime.tv_sec
            << ", nsec = "
            << abstime.tv_nsec
            << ")"
            << end;
        throw mutex_failed_error("pthread_cond_timedwait() failed");
    }
 
    return true;
}
 
 
bool mutex::dated_wait(std::uint64_t const usec)
{
    return dated_wait(timespec{
              static_cast<long>(usec / 1'000'000ULL)
            , static_cast<long>((usec % 1'000'000ULL) * 1'000ULL)
        });
}
 
 
bool mutex::dated_wait(timespec const & date)
{
    // For any mutex wait to work, we MUST have the
    // mutex locked already and just one time.
    //
    // note: the 1 time is just for assurance that it will
    //       work in most cases; it should work even when locked
    //       multiple times, but it is less likely. For sure, it
    //       has to be at least once.
    //if(f_reference_count != 1UL)
    //{
    //    log << log_level_t::fatal
    //        << "attempting to dated wait until "
    //        << usec
    //        << " msec on a mutex when it is not locked exactly once, current count is "
    //        << f_reference_count
    //        << end;
    //    throw exception_not_locked_once_error();
    //}
 
    int const err(pthread_cond_timedwait(
              &f_impl->f_condition
            , &f_impl->f_mutex
            , &date));
    if(err != 0)
    {
        if(err == ETIMEDOUT)
        {
            return false;
        }
 
        // an error occurred!
        log << log_level_t::error
            << "a mutex conditional wait generated error #"
            << err
            << " -- "
            << strerror(err)
            << " (time out sec = "
            << date.tv_sec
            << ", nsec = "
            << date.tv_nsec
            << ")"
            << end;
        throw mutex_failed_error("pthread_cond_timedwait() failed");
    }
 
    return true;
}
 
 
void mutex::signal()
{
    int const err(pthread_cond_signal(&f_impl->f_condition));
    if(err != 0)
    {
        log << log_level_t::fatal
            << "a mutex condition signal generated error #"
            << err
            << end;
        throw invalid_error("pthread_cond_signal() failed");
    }
}
 
 
void mutex::safe_signal()
{
    guard lock(*this);
 
    int const err(pthread_cond_signal(&f_impl->f_condition));
    if(err != 0)
    {
        log << log_level_t::fatal
            << "a mutex condition signal generated error #"
            << err
            << end;
        throw invalid_error("pthread_cond_signal() failed");
    }
}
 
 
void mutex::safe_broadcast()
{
    guard lock(*this);
 
    int const err(pthread_cond_broadcast(&f_impl->f_condition));
    if(err != 0)
    {
        log << log_level_t::fatal
            << "a mutex signal broadcast generated error #"
            << err
            << end;
        throw invalid_error("pthread_cond_broadcast() failed");
    }
}
 
 
void mutex::broadcast()
{
    guard lock(*this);
 
    int const err(pthread_cond_broadcast(&f_impl->f_condition));
    if(err != 0)
    {
        log << log_level_t::fatal
            << "a mutex signal broadcast generated error #"
            << err
            << end;
        throw invalid_error("pthread_cond_broadcast() failed");
    }
}
 
 
mutex *         g_system_mutex = nullptr;
 
 
void create_system_mutex()
{
    if(g_system_mutex != nullptr)
    {
        std::cerr << "fatal: create_system_mutex() called twice." << std::endl;
        std::terminate();
    }
 
    g_system_mutex = new mutex;
}
 
 
 
 
} // namespace cppthread
// vim: ts=4 sw=4 et