triggered.hpp

Go to the documentation of this file.

/** ************************************************************************************************
 * \file
 * This header file is part of module \alib_threads of the \aliblong.
 *
 * \emoji :copyright: 2013-2019 A-Worx GmbH, Germany.
 * Published under \ref mainpage_license "Boost Software License".
 **************************************************************************************************/
#ifndef HPP_AWORX_ALIB_THREADS_MODEL_TRIGGERED
#define HPP_AWORX_ALIB_THREADS_MODEL_TRIGGERED
 
#if !defined(ALIB_DOX)  // todo remove
 
#if !defined(HPP_ALIB_LANG_INTEGERS)
#   include "alib/lang/integers.hpp"
#endif
 
 
namespace alib { namespace threads::model {
 
// forward declaration
class ThreadManager;
 
 
/** ************************************************************************************************
 * This class is declares a simple interface for objects that allow to be triggerd periodically.
 * The use of this class is recommended to avoid to either creating a dedicated thread for
 * simple, periodic tasks, or to add invoctions to perform such tasks to other threadds of the
 * application.
 *
 * Instead, class \alib{threads::model;ThreadManager} will be the only responsible entity to
 * trigger such actions within its own execution thread.
 **************************************************************************************************/
class Triggered
{
    protected:
        /** Class ThreadManager is the only one that will trigger us and hence has access to
         *  our protected functions. */
        friend class ThreadManager;
 
        /** The name of the triggered object. This is mainly used for log output and some
         *  convenience methods.   */
        const   String      Name;
 
        /**
         * Constructor. Stores the name in constant member #Name. Usually these names are
         * hard-coded C++ character arrays. If progarmmatically 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 )                                  {}
 
       /** Virtual empty destructor. Needed with any virtual class.   */
        virtual ~Triggered()                                                                      {}
        
        /** Implementations need to implement this function to return the trigger period.
         *  The period is allowed to change with each request. A request is made
         *  when the type is added to the thread manager for triggering and after each
         *  call to #trigger(), when the next trigger time is scheduled.
         *
         * @return The desired sleep time between two trigger events in milliseconds.
         */
        virtual integer     triggerPeriodInMilliseconds()                                       = 0;
 
        /**
         *  Implementations need to implement this function and perform their trigger actions
         *  here.
         */
        virtual void        trigger()                                                           = 0;
 
}; // interface class Triggered
 
} // namespace alib[::threads::model]
 
/// Type alias in namespace #alib.
using      Triggered        = alib::threads::model::Triggered;
 
}  // namespace [alib]
 
#endif // #if !defined(ALIB_DOX)  // todo remove
 
#endif // HPP_AWORX_ALIB_THREADS_MODEL_TRIGGERED