mirror of
https://github.com/QuantumLeaps/qpcpp.git
synced 2025-01-14 05:42:57 +08:00
241 lines
8.7 KiB
C++
241 lines
8.7 KiB
C++
/// @file
|
|
/// @brief QXK/C++ extended (blocking) thread
|
|
/// @ingroup qxk
|
|
/// @cond
|
|
///***************************************************************************
|
|
/// Last updated for version 6.2.0
|
|
/// Last updated on 2018-03-16
|
|
///
|
|
/// Q u a n t u m L e a P s
|
|
/// ---------------------------
|
|
/// innovating embedded systems
|
|
///
|
|
/// Copyright (C) 2002-2018 Quantum Leaps. All rights reserved.
|
|
///
|
|
/// This program is open source 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 3 of the License, or
|
|
/// (at your option) any later version.
|
|
///
|
|
/// Alternatively, this program may be distributed and modified under the
|
|
/// terms of Quantum Leaps commercial licenses, which expressly supersede
|
|
/// the GNU General Public License and are specifically designed for
|
|
/// licensees interested in retaining the proprietary status of their code.
|
|
///
|
|
/// 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 <http://www.gnu.org/licenses/>.
|
|
///
|
|
/// Contact information:
|
|
/// https://www.state-machine.com
|
|
/// mailto:info@state-machine.com
|
|
///***************************************************************************
|
|
/// @endcond
|
|
|
|
#ifndef qxthread_h
|
|
#define qxthread_h
|
|
|
|
//! no-timeout sepcification when blocking on queues or semaphores
|
|
#define QXTHREAD_NO_TIMEOUT (static_cast<uint_fast16_t>(0))
|
|
|
|
namespace QP {
|
|
|
|
class QXThread; // forward declaration
|
|
|
|
//! Thread handler pointer-to-function
|
|
typedef void (*QXThreadHandler)(QXThread * const me);
|
|
|
|
//****************************************************************************
|
|
//! 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 a "naked" thread
|
|
/// in your application.
|
|
/// @include qf_qxthread.cpp
|
|
///
|
|
class QXThread : public QActive {
|
|
public:
|
|
|
|
//! public constructor
|
|
QXThread(QXThreadHandler const handler,
|
|
uint_fast8_t const tickRate = static_cast<uint_fast8_t>(0));
|
|
|
|
//! delay (block) the current extended thread for a specified # ticks
|
|
static bool delay(uint_fast16_t const nTicks);
|
|
|
|
//! cancel the delay
|
|
bool delayCancel(void);
|
|
|
|
//! obtain a message from the private message queue (block if no messages)
|
|
static QEvt const *queueGet(
|
|
uint_fast16_t const nTicks = QXTHREAD_NO_TIMEOUT);
|
|
|
|
// virtual function overrides...
|
|
//! Executes the top-most initial transition in QP::QMsm.
|
|
virtual void init(QEvt const * const e);
|
|
virtual void init(void) { this->init(static_cast<QEvt const *>(0)); }
|
|
|
|
//! Dispatches an event to QMsm
|
|
virtual void dispatch(QEvt const * const e);
|
|
|
|
//! Starts execution of an extended thread and registers the thread
|
|
//! with the framework.
|
|
virtual void start(uint_fast8_t const prio,
|
|
QEvt const *qSto[], uint_fast16_t const qLen,
|
|
void * const stkSto, uint_fast16_t const stkSize,
|
|
QEvt const * const ie);
|
|
|
|
//! Overloaded start function (no initialization event)
|
|
virtual void start(uint_fast8_t const prio,
|
|
QEvt const *qSto[], uint_fast16_t const qLen,
|
|
void * const stkSto, uint_fast16_t const stkSize)
|
|
{
|
|
this->start(prio, qSto, qLen, stkSto, stkSize,
|
|
static_cast<QEvt const *>(0));
|
|
}
|
|
|
|
#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.
|
|
virtual bool post_(QEvt const * const e, uint_fast16_t const margin);
|
|
#else
|
|
virtual bool post_(QEvt const * const e, uint_fast16_t const margin,
|
|
void const * const sender);
|
|
#endif
|
|
|
|
//! Posts an event directly to the event queue of the active object
|
|
//! using the Last-In-First-Out (LIFO) policy.
|
|
virtual void postLIFO(QEvt const * const e);
|
|
|
|
//! get the blocking object for this thread (NULL if not blocked)
|
|
void const *getBlockingObj(void) const {
|
|
return m_temp.obj;
|
|
}
|
|
|
|
private:
|
|
void block_(void) const;
|
|
void unblock_(void) const;
|
|
void teArm_(enum_t const sig, uint_fast16_t const nTicks);
|
|
bool teDisarm_(void);
|
|
|
|
// attributes...
|
|
QTimeEvt m_timeEvt;
|
|
|
|
// friendships...
|
|
friend class QXSemaphore;
|
|
friend class QXMutex;
|
|
};
|
|
|
|
//****************************************************************************
|
|
//! Counting Semaphore of the QXK preemptive kernel
|
|
///
|
|
/// @description
|
|
/// ::QXSemaphore is a blocking mechanism intended primarily for signaling
|
|
/// @ref ::QXThread "extended threads". The semaphore is initialized with
|
|
/// the maximum count (see 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 the semaphore
|
|
/// in your application.
|
|
/// @include qf_qxsema.cpp
|
|
///
|
|
class QXSemaphore {
|
|
public:
|
|
//! initialize the counting semaphore
|
|
void init(uint_fast16_t const count,
|
|
uint_fast16_t const max_count
|
|
= static_cast<uint_fast16_t>(0xFFFF));
|
|
|
|
//! wait (block) on the semaphore
|
|
bool wait(uint_fast16_t const nTicks = QXTHREAD_NO_TIMEOUT);
|
|
|
|
//! try wait on the semaphore (non-blocking)
|
|
bool tryWait(void);
|
|
|
|
//! signal (unblock) the semaphore
|
|
bool signal(void);
|
|
|
|
private:
|
|
QPSet m_waitSet; //!< set of extended threads waiting on this semaphore
|
|
uint16_t volatile m_count;
|
|
uint16_t m_max_count;
|
|
};
|
|
|
|
//****************************************************************************
|
|
//! Priority Ceiling Mutex the QXK preemptive kernel
|
|
///
|
|
/// @description
|
|
/// ::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 QXMutex::init()).
|
|
/// In that case, ::QXMutex requires its own uinque QP priority level, which
|
|
/// cannot be used by any thread or any other ::QXMutex.
|
|
/// If initialzied with zero ceiling priority, ::QXMutex does **not** use the
|
|
/// priority ceiling protocol and does not require a unique QP priority
|
|
/// (see QXMutex::init()).
|
|
/// ::QXMutex is **recursive** (reentrant), which means that it can be locked
|
|
/// mutiliple times (up to 255 levels) by the *same* thread without causing
|
|
/// deadlock.
|
|
/// ::QXMutex is primarily intended for the @ref ::QXThread
|
|
/// "extened (blocking) threads", but can also be used by the @ref ::QActive
|
|
/// "basic threads" through the non-blocking QXMutex::tryLock() API.
|
|
///
|
|
/// @note
|
|
/// ::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 QXMutex::lock() and QXMutex::unlock() operations). If no blocking is
|
|
/// needed while holding the mutex, the more efficient non-blocking mechanism
|
|
/// of @ref QXK_schedLock() "selective QXK scheduler locking" should be used
|
|
/// instead. @ref QXK_schedLock() "Selective scheduler locking" is available
|
|
/// for both @ref ::QActive "basic threads" and @ref ::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 the mutex
|
|
/// in your application.
|
|
/// @include qf_mutex.cpp
|
|
///
|
|
class QXMutex {
|
|
public:
|
|
//! initialize the QXK priority-ceiling mutex QP::QXMutex
|
|
void init(uint_fast8_t const ceiling);
|
|
|
|
//! lock the QXK priority-ceiling mutex QP::QXMutex
|
|
bool lock(uint_fast16_t const nTicks = QXTHREAD_NO_TIMEOUT);
|
|
|
|
//! try to lock the QXK priority-ceiling mutex QP::QXMutex
|
|
bool tryLock(void);
|
|
|
|
//! unlock the QXK priority-ceiling mutex QP::QXMutex
|
|
void unlock(void);
|
|
|
|
private:
|
|
QPSet m_waitSet; //!< set of extended-threads waiting on this mutex
|
|
uint8_t volatile m_lockNest;
|
|
uint8_t volatile m_holderPrio;
|
|
uint8_t m_ceiling;
|
|
};
|
|
|
|
} // namespace QP
|
|
|
|
#endif // qxthread_h
|
|
|