trigger.hpp

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of module \alib_threadmodel of the \aliblong.
///
/// Copyright 2013-2026 A-Worx GmbH, Germany.
/// Published under #"mainpage_license".
//==================================================================================================
ALIB_EXPORT namespace alib { namespace threadmodel {
 
// forward declaration
class Trigger;
 
//==================================================================================================
/// This class declares a simple virtual interface for objects that allow to be triggered
/// periodically.
/// The use of this class is recommended to avoid to either creating a dedicated thread for
/// simple, periodic tasks, or to add invocations to perform such tasks to other threads of the
/// application.
///
/// Instead, class #"Trigger" will be the only responsible entity to
/// trigger such actions within its own execution thread.
///
/// @see Chapter #"alib_thrmod_trigger" of this module's Programmer's Manual
///      provides a quick source code sample that demonstrates the use this class.
//==================================================================================================
class Triggered {
  protected:
    #if !DOXYGEN
      // Class Trigger is the only one that will trigger us and hence has access to
      // our protected functions.
      friend class Trigger;
    #endif
 
    #if ALIB_STRINGS
    /// The name of the triggered object. This is mainly used for log output and some
    /// convenience methods.<br>
    /// \par Availability
    ///    This field is available only if the module \alib_strings is included in the
    ///    \alibbuild.
    const   String      Name;
 
    /// Constructor. Stores the name in constant member #".Name". Usually these names are
    /// hard-coded C++ character arrays. If programmatically created, it has to be assured that
    /// the life-cycle of the string supersedes the lifecycle of the instnace of this class.
    /// @param pName The name of this object.
    Triggered(const String& pName)  : Name( pName )                                               {}
 
    #else
    Triggered()                                                               = default;
    #endif
 
    /// Virtual empty destructor. Needed with any virtual class.
    virtual ~Triggered()                                                                          {}
        
    /// Implementations need to return the sleep time, between two trigger events.
    /// Precisely, this method is called after #".trigger" has been executed and defines the
    /// next sleep time.
    /// @return The desired sleep time between two trigger events.
    virtual Ticks::Duration triggerPeriod()                                                      =0;
 
    /// Implementations need to implement this function and perform their trigger actions
    /// here.
    virtual void            trigger()                                                            =0;
 
}; // interface class Triggered
 
//==================================================================================================
/// The #"%Trigger" class provides a mechanism to periodically "trigger" actions on objects
/// that implement the `Triggered` interface without requiring dedicated threads per object
/// or manual additions of actions in existing threads.
///
/// The class manages a collection of #"Triggered" objects and ensures that their virtual
/// #"%Triggered:trigger" methods are called periodically based on the time interval given with
/// their respective method #"Triggered::triggerPeriod".
///
/// Internally, #"%Trigger" operates its own thread to handle the timing and execution of
/// the triggers, adhering to the specified conditions.
///
/// This design helps in simplifying periodic task management within an application,
/// avoiding thread proliferation and minimizing resource overhead.
///
/// \par Key responsibilities of the class:
/// - Maintain and manage a list of #"%Triggered" objects.
/// - Schedule and execute periodic triggers for the registered objects.
/// - Provide the ability to add or remove #"%Triggered" objects dynamically.
///
/// \par Usage:
/// - Users register their implementations of the #"%Triggered" interface with the #"Add()" method
///   to begin periodic triggers.
/// - Objects can be unregistered using the #".Remove" method.
/// - Method #".Stop" method terminates the execution of the internal thread.
///
/// Intended for scenarios where lightweight, periodic task scheduling is needed
/// without creating additional complexity or significant overhead.
//==================================================================================================
class Trigger :   protected   Thread,
                  protected   TCondition<Trigger>
{
    friend struct threads::TCondition<Trigger>;
    friend class  lang::Owner<Trigger&>;
 
  protected:
    /// The entry type used with field #"triggerList".
    struct TriggerEntry {
        /// Constructor.
        /// @param target      Assigned to #".Target".
        /// @param nextWakeup  Assigned to #".NextWakeup".
        TriggerEntry(Triggered* target, const Ticks& nextWakeup )
        : Target(target), NextWakeup(nextWakeup)                                                  {}
 
        /// Deleted copy constructor (to avoid working on copies accidentally).
        TriggerEntry(TriggerEntry& )                                                        =delete;
 
        Triggered*  Target;     ///< The triggered object.
        Ticks       NextWakeup; ///< The next wakeup time.
    };
 
    /// The list of registered triggered objects.
    ListMA<TriggerEntry>   triggerList;
 
    /// The condition requested by parent class #"TCondition" via a call to
    /// #".isConditionMet".
    bool                                wakeUpCondition                                     = false;
 
    /// Denotes whether or not the trigger is currently used in internal thread mode.
    bool                                internalThreadMode                                  = false;
 
    /// Implementation of the interface needed by parent #"TCondition".
    /// @return Member #"wakeUpCondition"
    bool isConditionMet()                                 const noexcept { return wakeUpCondition; }
 
  public:
    /// Constructor.
    ALIB_DLL                Trigger();
 
    /// Destructor.
    ALIB_DLL  virtual      ~Trigger()                                                      override;
 
    using Thread::Start;
    
    /// Implementation of the parent interface (virtual abstract).
    ALIB_DLL  virtual void  Run()                                                          override;
 
    /// Executes the processing of triggers for up to a given maximum time.
    /// If the internal thread is not used, this method may be called manually inside an external
    /// loop to execute triggering operations within the specified timeframe.
    ///
    /// If the internal thread was created and is running, with debug-compilations, an \alib
    /// error will be raised.
    /// @param until  Defines the future point in time until triggering is performed.
    ALIB_DLL void Do( Ticks until );
 
    /// Invokes #"Do(Ticks)" by adding the given \p{duration} to the current point in time.
    /// @param until  Defines the maximum duration for which this method will execute the trigger
    ///               logic.
    void Do( Ticks::Duration until )                                 { Do( Ticks::Now() + until ); }
 
    #if !DOXYGEN
    void Do( Ticks::Duration::TDuration until )                      { Do( Ticks::Now() + until ); }
    #endif
 
    /// Stops the trigger thread and joins it.
    ALIB_DLL  virtual void  Stop();
 
    /// Add an object to be triggered.
    /// @param triggered        The object to be triggered.
    /// @param initialWakeup    If \c true, the first wakeup is scheduled right away.
    ///                         Defaults to \c false.
    ALIB_DLL void           Add( Triggered& triggered, bool initialWakeup= false);
 
    /// Remove a previously added triggered object.
    /// @param triggered  The object to be removed from the list.
    ALIB_DLL void           Remove( Triggered& triggered);
 
}; // Trigger
 
 
} // namespace alib[::threadmodel]
 
/// Type alias in namespace #"%alib".
using      Trigger          = threadmodel::Trigger;
 
/// Type alias in namespace #"%alib".
using      Triggered        = threadmodel::Triggered;
 
}  // namespace [alib]