qpcpp/include/qxthread.hpp

//============================================================================
// QP/C++ Real-Time Embedded Framework (RTEF)
// Copyright (C) 2005 Quantum Leaps, LLC. All rights reserved.
//
// SPDX-License-Identifier: GPL-3.0-or-later OR LicenseRef-QL-commercial
//
// This software is dual-licensed under the terms of the open source GNU
// General Public License version 3 (or any later version), or alternatively,
// under the terms of one of the closed source Quantum Leaps commercial
// licenses.
//
// The terms of the open source GNU General Public License version 3
// can be found at: <www.gnu.org/licenses/gpl-3.0>
//
// The terms of the closed source Quantum Leaps commercial licenses
// can be found at: <www.state-machine.com/licensing>
//
// Redistributions in source code must retain this top-level comment block.
// Plagiarizing this software to sidestep the license obligations is illegal.
//
// Contact information:
// <www.state-machine.com>
// <info@state-machine.com>
//============================================================================
//! @date Last updated on: 2021-12-23
//! @version Last updated for: @ref qpcpp_7_0_0
//!
//! @file
//! @brief QXK/C++ extended (blocking) thread

#ifndef QXTHREAD_HPP
#define QXTHREAD_HPP

namespace QP {

//! no-timeout sepcification when blocking on queues or semaphores
static constexpr std::uint_fast16_t QXTHREAD_NO_TIMEOUT = 0U;

//============================================================================
//! Extended (blocking) thread of the QXK preemptive kernel
//! @description
//! QP::QXThread represents the extended (blocking) thread of the QXK kernel.
//! Each blocking thread in the application must be represented by the
//! corresponding QP::QXThread instance
//!
//! @note
//! Typically QP::QXThread is instantiated directly in the application code.
//! The customization of the thread occurs in the constructor, where you
//! provide the thred-handler function as the parameter.
//!
//! @sa QP::QActive
//!
//! @usage
//! The following example illustrates how to instantiate and use an extended
//! thread in your application.
//! @include qxk_thread.cpp
//!
class QXThread : public QActive {
public:

    //! public constructor
    QXThread(QXThreadHandler const handler,
             std::uint_fast8_t const tickRate = 0U) noexcept;

    //! delay (block) the current extended thread for a specified # ticks
    static bool delay(std::uint_fast16_t const nTicks) noexcept;

    //! cancel the delay
    bool delayCancel(void) noexcept;

    //! obtain a message from the private message queue (block if no messages)
    static QEvt const *queueGet(
        std::uint_fast16_t const nTicks = QXTHREAD_NO_TIMEOUT) noexcept;

    // virtual function overrides...
    //! Executes the top-most initial transition in HSM
    void init(void const * const e,
              std::uint_fast8_t const qs_id) noexcept override;
    void init(std::uint_fast8_t const qs_id) noexcept override {
        this->init(nullptr, qs_id);
    }

    //! Dispatches an event to HSM
    void dispatch(QEvt const * const e,
                  std::uint_fast8_t const qs_id) noexcept override;

    //! Starts execution of an extended thread and registers the thread
    //! with the framework.
    void start(std::uint_fast8_t const prio,
               QEvt const * * const qSto, std::uint_fast16_t const qLen,
               void * const stkSto, std::uint_fast16_t const stkSize,
               void const * const par) override;

    //! Overloaded start function (no initialization event)
    void start(std::uint_fast8_t const prio,
               QEvt const * * const qSto, std::uint_fast16_t const qLen,
               void * const stkSto, std::uint_fast16_t const stkSize) override
    {
        this->start(prio, qSto, qLen, stkSto, stkSize, nullptr);
    }

#ifndef Q_SPY
    //! Posts an event @p e directly to the event queue of the extended
    //! thread @p me using the First-In-First-Out (FIFO) policy.
    bool post_(QEvt const * const e,
               std::uint_fast16_t const margin) noexcept override;
#else
    bool post_(QEvt const * const e, std::uint_fast16_t const margin,
               void const * const sender) noexcept override;
#endif

    //! Posts an event directly to the event queue of the active object
    //! using the Last-In-First-Out (LIFO) policy.
    void postLIFO(QEvt const * const e) noexcept override;

private:
    void block_(void) const noexcept;
    void unblock_(void) const noexcept;
    void teArm_(enum_t const sig, std::uint_fast16_t const nTicks) noexcept;
    bool teDisarm_(void) noexcept;

    // attributes...
    QTimeEvt m_timeEvt; //!< time event to handle blocking timeouts

    // friendships...
    friend class QXSemaphore;
    friend class QXMutex;
};

//============================================================================
//! Counting Semaphore of the QXK preemptive kernel
//!
//! @description
//! QP::QXSemaphore is a blocking mechanism intended primarily for signaling
//! @ref QP::QXThread "extended threads". The semaphore is initialized with
//! the maximum count (see QP::QXSemaphore::init()), which allows you to
//! create a binary semaphore (when the maximum count is 1) and
//! counting semaphore when the maximum count is > 1.
//!
//! @usage
//! The following example illustrates how to instantiate and use the semaphore
//! in your application.
//! @include qxk_sema.cpp
//!
class QXSemaphore {
public:
    //! initialize the counting semaphore
    void init(std::uint_fast16_t const count,
              std::uint_fast16_t const max_count = 0xFFFFU) noexcept;

    //! wait (block) on the semaphore
    bool wait(std::uint_fast16_t const nTicks = QXTHREAD_NO_TIMEOUT) noexcept;

    //! try wait on the semaphore (non-blocking)
    bool tryWait(void) noexcept;

    //! signal (unblock) the semaphore
    bool signal(void) noexcept;

private:
    QPSet m_waitSet; //!< set of extended threads waiting on this semaphore
    std::uint16_t volatile m_count;  //!< semaphore up-down counter
    std::uint16_t m_max_count; //!< maximum value of the semaphore counter
};

//============================================================================
//! Priority Ceiling Mutex the QXK preemptive kernel
//!
//! @description
//! QP::QXMutex is a blocking mutual exclusion mechanism that can also apply
//! the **priority ceiling protocol** to avoid unbounded priority inversion
//! (if initialized with a non-zero ceiling priority, see QP::QXMutex::init()).
//! In that case, QP::QXMutex requires its own uinque QP priority level, which
//! cannot be used by any thread or any other QP::QXMutex.
//! If initialzied with zero ceiling priority, QP::QXMutex does **not** use
//! the priority ceiling protocol and does not require a unique QP priority
//! (see QP::QXMutex::init()).
//! QP::QXMutex is **recursive** (reentrant), which means that it can be
//! locked mutiliple times (up to 255 levels) by the *same* thread without
//! causing deadlock.
//! QP::QXMutex is primarily intended for the @ref QP::QXThread
//! "extened (blocking) threads", but can also be used by the @ref QP::QActive
//! "basic threads" through the non-blocking QP::QXMutex::tryLock() API.
//!
//! @note
//! QP::QXMutex should be used in situations when at least one of the extended
//! threads contending for the mutex blocks while holding the mutex (between
//! the QP::QXMutex::lock() and QP::QXMutex::unlock() operations). If no
//! blocking is needed while holding the mutex, the more efficient
//! non-blocking mechanism of @ref QP::QXK::schedLock() "selective QXK
//! scheduler locking" should be used instead. @ref QP::QXK::schedLock()
//! "Selective scheduler locking" is available for both @ref QP::QActive
//! "basic threads" and @ref QP::QXThread "extended threads", so it is
//! applicable to situations where resources are shared among all
//! these threads.
//!
//! @usage
//! The following example illustrates how to instantiate and use the mutex
//! in your application.
//! @include qxk_mutex.cpp
//!
class QXMutex {
public:
    //! initialize the QXK priority-ceiling mutex QP::QXMutex
    void init(std::uint_fast8_t const ceiling) noexcept;

    //! lock the QXK priority-ceiling mutex QP::QXMutex
    bool lock(std::uint_fast16_t const nTicks = QXTHREAD_NO_TIMEOUT) noexcept;

    //! try to lock the QXK priority-ceiling mutex QP::QXMutex
    bool tryLock(void) noexcept;

    //! unlock the QXK priority-ceiling mutex QP::QXMutex
    void unlock(void) noexcept;

private:
    QPSet m_waitSet; //!< set of extended-threads waiting on this mutex
    std::uint8_t volatile m_lockNest; //!< lock-nesting up-down counter
    std::uint8_t volatile m_holderPrio; //!< prio of the lock holder thread
    std::uint8_t m_ceiling; //!< prioirty ceiling of this mutex
};

} // namespace QP

#endif // QXTHREAD_HPP