semaphore

/*
Copyright (C) 2018-2024 Geoffrey Daniels. https://gpdaniels.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, version 3 of the License only.

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, see <https://www.gnu.org/licenses/>.
*/

#pragma once
#ifndef GTL_EXECUTION_SEMAPHORE_HPP
#define GTL_EXECUTION_SEMAPHORE_HPP

// Summary: Semaphore made using a mutex and condition variable.

#ifndef NDEBUG
#   if defined(_MSC_VER)
#       define __builtin_trap() __debugbreak()
#   endif
/// @brief A simple assert macro to break the program if the semaphore is misused.
#   define GTL_SEMAPHORE_ASSERT(ASSERTION, MESSAGE) static_cast<void>((ASSERTION) || (__builtin_trap(), 0))
#else
/// @brief At release time the assert macro is implemented as a nop.
#   define GTL_SEMAPHORE_ASSERT(ASSERTION, MESSAGE) static_cast<void>(0)
#endif

#if defined(_MSC_VER)
#   pragma warning(push, 0)
#endif

#include <mutex>

#if defined(_MSC_VER)
#   pragma warning(pop)
#endif

namespace gtl {
    /// @brief  The semaphore class is a mutex structure that atomically counts notifications.
    template <typename mutex_type, typename condition_variable_type>
    class semaphore final {
    private:
        /// @brief  This is the main variable in the semaphore, it it increased by notifications and decreased after successful waits.
        unsigned long long int count;

        /// @brief  To control access to the semaphore's count a mutex is used, this keeps the structure thread safe.
        mutex_type mutex;

        /// @brief  To wait on the state of the mutex a condition_variable is used, allowing logic in the otherwise blocking mutex locking operations.
        condition_variable_type condition_variable;


    public:
        /// @brief  Destructor asserts that the semaphore's count is empty.
        ~semaphore() {
            GTL_SEMAPHORE_ASSERT(this->count == 0, "Ensure that the semaphore count is empty when it is destructed.");
        }

        /// @brief  Constructor allows the semaphore's count to be initialised, but defaults to zero.
        /// @param  initial_count The initial semaphore count.
        semaphore(unsigned int initial_count = 0)
            : count(initial_count) {
        }

        /// @brief  Default copy constructor.
        semaphore(const semaphore&) = default;

        /// @brief  Default move constructor.
        semaphore(semaphore&&) = default;

        /// @brief  Default copy assignment operator.
        semaphore& operator=(const semaphore&) = default;

        /// @brief  Default move assignment operator.
        semaphore& operator=(semaphore&&) = default;

        /// @brief  Notify the semaphore, increases the semaphore's count by one and notifys one thread of any waiting on it.
        void notify() {
            this->mutex.lock();
            ++this->count;
            this->mutex.unlock();
            this->condition_variable.notify_one();
        }

        /// @brief  Wait on the semaphore, this is a blocking wait on the semaphore's count being non zero before subtracting one.
        void wait() {
            std::unique_lock<mutex_type> lock(this->mutex);
            this->condition_variable.wait(lock, [&]{ return this->count > 0; });
            --this->count;
        }

        /// @brief  Try waiting on the semaphore, this is a non-blocking wait on the semaphore's count being non zero before subtracting one.
        /// @return True if the semaphore's count was non-zero, false otherwise.
        bool try_wait() {
            this->mutex.lock();
            if (this->count > 0) {
                --this->count;
                this->mutex.unlock();
                return true;
            }
            this->mutex.unlock();
            return false;
        }
    };
}

#undef GTL_SEMAPHORE_ASSERT

#endif // GTL_EXECUTION_SEMAPHORE_HPP