thread.hpp

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of module \alib_threads of the \aliblong.
///
/// Copyright 2013-2026 A-Worx GmbH, Germany.
/// Published under #"mainpage_license".
//==================================================================================================
ALIB_EXPORT namespace alib { namespace threads {
// forwards
class     Thread;
 
#if !ALIB_SINGLE_THREADED
namespace detail {
/// Internal method to start a thread.
/// @param thread The \alib thread object to start.
void threadStart( Thread* thread );
}
#endif
}
namespace threads {
 
/// The ALib thread identifier type
using ThreadID=    integer;
 
 
//==================================================================================================
///  This is a value that may be passed as a value indicating an undefined thread
//==================================================================================================
inline constexpr   ThreadID  UNDEFINED = 0;
 
#if ALIB_SINGLE_THREADED
inline void     Bootstrap()                                                                       {}
inline void     Shutdown()                                                                        {}
struct          Runnable {};
#else
 
//==================================================================================================
/// Internally, a hash map used to find the current thread object.
/// The map uses default values for #"HashTable::BaseLoadFactor;*" and
/// #"HashTable::MaxLoadFactor;*".
/// Depending on the use of threads by a using application, these values might be modified
/// \e before starting the first phase of #"alib_mod_bs;bootstrapping ALib".
///
/// This namespace function allows doing this by passing the given parameters to method
/// #"HashTable::Reserve;*" of the internal table.
///
/// \note
///   With the absence of module \alib_monomem in the \alibbuild, the type of the internal object
///   is <c>std::unordered_map</c>, which receives similar parameters.<br>
///
/// @param qty       The expected number of threads.
//==================================================================================================
ALIB_DLL void   BootstrapThreadMap( integer qty );
 
//==================================================================================================
/// Initializes \alib thread logic.
/// Multiple invocations of this method are forbidden.
///
/// The #"alib_mod_bs;standard bootstrap" code of \alib, hence the (overloaded)
/// functions #"alib::Bootstrap(BootstrapPhases);2" will call this function.
///
/// \see
///   For information about using this method, consult chapter
///   #"alib_mod_bs_nocamps" of the #"alib_manual".
//==================================================================================================
ALIB_DLL
void        bootstrap();
 
//==================================================================================================
/// Frees resources and shuts down \alib thread logic.
/// Multiple invocations of this method are forbidden.
/// The #"alib_mod_bs;standard bootstrap" code of \alib, hence the (overloaded)
/// functions #"alib::Shutdown;2" will call this function.
///
/// \see
///   Sibling function #"threads::bootstrap".
//==================================================================================================
ALIB_DLL
void        shutdown();
 
//==================================================================================================
/// This is a virtual abstract (interface) type that provides the executable method
/// for an associated #"Thread".
///
/// Objects of this type may be passed to the constructor of class #"Thread". The
/// default implementation of method #"Thread::Run;*" will then invoke
/// method #".Run" of this class.
//==================================================================================================
class Runnable {
  public:
    /// Virtual destructor.
    virtual                   ~Runnable()                                                         {}
 
    /// The method invoked by the default implementation of #"Thread::Run;*"
    /// of the thread object that this runnable is associated with.
    virtual        void        Run()                                                             =0;
};
 
#endif // !ALIB_SINGLE_THREADED
 
#if !ALIB_SINGLE_THREADED
class Thread;
 
/// A thread-local pointer to the \alib representation of the actual thread.
extern thread_local Thread* THIS_THREAD;
#endif
 
//==================================================================================================
/// This class provides a limited (minimal) abstraction of C++ type <c>std::thread</c>.
/// As elaborated in the module's documentation, this class is not considered full featured
/// but - as of today- is meant for simple use cases only.
///
/// For general information of multi-threading support provided by \alib, please consult
/// the #"alib_mod_threads".
///
/// ## Friends ##
/// function #"threads::bootstrap;*"
/// function #"threads::shutdown;*"
/// @see
///   For this class, a #"alibtools_debug_helpers_gdb;pretty printer" for the
///   GNU debugger is provided.
//==================================================================================================
class Thread : public Runnable {
    #if !DOXYGEN && !ALIB_SINGLE_THREADED
    friend void    ALIB_DLL bootstrap        ();
    friend void    ALIB_DLL shutdown         ();
    friend void    detail::threadStart( Thread* t );
    #endif
 
  public:
  #if !ALIB_SINGLE_THREADED
    /// States that follow the lifecycle of the thread. The states are accessible with method
    /// #"GetState".
    enum class State {
        Unstarted   =  0,  ///< Not started, and no call to #".Start" was performed, yet.
                           ///< This is the state after construction of an instance.
        Started     =  1,  ///< Method #".Start" was invoked but not running, yet.
        Running     =  2,  ///< The thread's #".Run" method is currently processed.
        Done        =  3,  ///< The run method is processed, and the thread is ready to be
                           ///< terminated.
        Terminated  =  4,  ///< The thread is terminated.
    };
 
 
  //################################################################################################
  // Protected fields
  //################################################################################################
  protected:
    /// The internal C++ thread object.
    std::thread*        c11Thread                                                          =nullptr;
 
    /// The internal C++ thread id.
    std::thread::id     nativeID;
 
    /// The runnable to execute.
    Runnable*           runnable                                                           =nullptr;
 
    /// The id of the thread.
    ThreadID            id                                                                       =0;
 
    /// The name of the thread.
    const character*    name                                                               =nullptr;
 
    /// Internal flag to indicate if the thread is alive.
    State               state                                                    = State::Unstarted;
 
 
  //################################################################################################
  // Constructors, destructor
  //################################################################################################
  public:
    /// Constructor without a parameter specifying a Runnable. Such thread will not execute any
    /// code unless a specialized class is derived that overrides virtual method #".Run".
    ///
    /// @param pName  (Optional) The designated name of the thread. If the name provided is,
    ///               empty the name of the thread will be set to match a string representation
    ///               of the thread id.
    Thread( const character* pName= A_CHAR("") )
    : Thread( nullptr, pName )                                                                    {}
 
    /// Constructor with the provision of a Runnable 'target'.
    /// The method #"Runnable::Run;2" of \p{target} will be executed upon thread start (unless a
    /// descendant class overrides method #".Run;2" which changes this behavior.
    /// @param target The target to execute when the thread runs.
    /// @param pName  (Optional) The designated name of the thread.
    ///               If the name provided is empty, the name of the thread will be set to
    ///               match a string representation of the thread id.
    ALIB_DLL            Thread(Runnable* target, const character* pName= A_CHAR("") );
 
    /// Before destruction, #"Join" has to be called.
    /// The destructor blocks if the thread was started and is still running.
    /// Blocking lasts until the thread's end of execution.<br>
    virtual    ~Thread()                                                    override { destruct(); }
 
    /// Deleted copy constructor.
    Thread(const Thread& )                                                                  =delete;
 
  protected:
    /// For reasons currently not understood, MSVC does not allow a direct implementation
    /// of the virtual destructor. Only when moving the implementation to this dedicated helper
    /// method, the linker does not complain about a missing vtable.
    ALIB_DLL void    destruct();
 
  public:
  //################################################################################################
  // Runnable Interface implementation
  //################################################################################################
 
    /// If we have a runnable, its #"%run" method is executed. Otherwise nothing is done.
    ///
    /// Hence, to have the thread execute something, either a #"Runnable"
    /// has to be provided or a derived version of this class replaces this method.
    virtual void            Run()                     override { if (runnable)    runnable->Run(); }
 
  //################################################################################################
  // Interface
  //################################################################################################
 
    /// Returns the id of this Thread. Systems threads have IDs below 0, ALIB generated threads
    /// have positive IDs and start with 1.
    ///
    /// @return    The \alib id of the thread.
    ThreadID            GetID()                                                 const { return id; }
 
    /// Returns the id of this Thread. Systems threads have IDs below 0, ALIB generated threads
    /// have positive IDs and start with 1.
    ///
    /// @return    The \alib id of the thread.
    std::thread::id     GetNativeID()                                     const { return nativeID; }
 
    /// Returns the name of the thread. An \alib thread can have any name that is given to it and
    /// such name can be changed any time. In fact, names are for debugging and logging
    /// purposes only.
    ///
    /// @return Returns the name of the thread.
    virtual
    const character*    GetName()                                             const { return name; }
 
    /// Sets the name of the thread. An \alib thread can have any name that is given to it and
    /// such name can be changed any time.
    /// Thread names are meant for debugging and logging purposes only.
    /// @param newName    The name that the Thread should hold.
    virtual void       SetName( const character* newName )                        { name= newName; }
 
    /// Returns the state of the thread. The states are given in enumeration #".State" and
    /// during the lifecycle of the thread, the state transitions from
    /// #"State::Unstarted" to #"State::Terminated".
    /// \note
    ///   For system threads (the thread that executed function <c>main thread</c> and those
    ///   not created using \alib thread features) #"State::Running" is
    ///   returned.
    ///   For those, it can't be determined if the thread is stared, alive or not.
    /// @return The current state within the thread's lifecycle.
    State              GetState()                                                  { return state; }
 
    /// A shortcut to
    /// <c>GetState().first == State::Started  || GetState().first == State::Running</c>.
    ///
    /// @return \c true if the current state of the thread is running or at least started.
    bool                IsAlive()     { return state == State::Started || state == State::Running; }
 
    /// Starts the execution of the thread. Method #".Run" is invoked by the new system thread,
    /// which - if not overwritten - invokes the method #"Runnable::Run;*".
    /// Of course, this method immediately returns, and after invocation, method #"IsAlive" will
    /// usually return \c true (unless the executed thread is not finished already).
    ALIB_DLL
    virtual void        Start();
 
    /// Terminates a thread using <c>std::join()</c>.
    /// When this method is called, the thread's state should be <b>State::Done</b>, which
    /// is the case after method #"%.Run" has exited.
    /// Otherwise, a #"alib_mod_assert;warning is raised".
    ALIB_DLL
    virtual void        Join();
 
 
  //################################################################################################
  // Static interface
  //################################################################################################
  public:
    #if ( !defined(_MSC_VER)  && !defined( ALIB_API_NO_DLL ) ) || DOXYGEN
    /// Static method that returns an object representing the thread that invoked this call.
    /// If no instance of class #"%Thread" was created for the current thread, yet, then one
    /// with a negative ID is created, indicating that this thread was not created by \alib.
    ///
    /// Once a #"%Thread" was created, a pointer to this instance stored in the <c>thread_local</c>
    /// namespace variable #"THIS_THREAD" is returned.
    /// Thus, this method is very fast from, starting with the second invocation.
    ///
    /// \note For technical reasons, under WindowsOS and DLL compilation, this method is \b not
    ///       inlined, but implemented using the macro #"ALIB_DLL".
    /// @return A pointer to the current thread.
    static inline
    Thread*             GetCurrent() {
        if (THIS_THREAD == nullptr )
            THIS_THREAD= Get( std::this_thread::get_id() );
        return THIS_THREAD;
    }
    #else
      static ALIB_DLL
      Thread*           GetCurrent();
    #endif
 
    /// Static method that returns an object representing the thread identified by the given
    /// system ID \p{nativeID}. \c nullptr is returned only if:
    /// - parameter \p{nativeID} is nulled, or
    /// - during #"alib_mod_bs;bootstrapping of ALib", which multithreaded
    ///   applications have to perform before starting threads, \c nullptr might be returned as
    ///   well.
    ///
    /// In any other situations, either,
    /// - \p{nativeID} is received from a thread that was started using this class #"%Thread", then
    ///   a pointer to that instance is returned, or
    /// - the thread was started without the use of \alib, then an instance of this class is
    ///   created (once) and registered.
    ///
    /// @param nativeID The C++ Standard Libraray identifier.
    /// @return A pointer to the instance associated with the native thread ID.
    ALIB_DLL
    static Thread*      Get(std::thread::id nativeID);
 
    /// Static method that returns the thread that initialized the library.
    /// Such thread is supposedly the "main" thread, as bootstrapping usually is performed
    /// by the process before any other threads are started.
    /// @return A pointer to the main thread.
    ALIB_DLL
    static Thread*      GetMain();
  #endif // !ALIB_SINGLE_THREADED
 
 
    /// Proactively offers the system to suspend the current thread.
    /// Invokes <c>std::this_thread::yield</c>.
    /// \note Must not be named 'Yield', because this is a macro name with MSVC.
    static
    void                YieldToSystem()                               { std::this_thread::yield(); }
 
    /// Suspends the current thread by calling <em>std::this_thread::sleep_for</em>.
    /// \see Variants #".SleepMicros", #".SleepNanos", #".Sleep(const Ticks::Duration&)", and
    ///      #".SleepUntil(const Ticks&)".
    ///  @param milliseconds    Sleep time in milliseconds.
    static void         SleepMillis     ( int milliseconds )
    { std::this_thread::sleep_for( std::chrono::milliseconds( milliseconds ) ); }
 
 
    /// Suspends the current thread by calling <em>std::this_thread::sleep_for</em>.
    /// \see Variants #".SleepMillis", #".SleepNanos", #".Sleep(const Ticks::Duration&)", and
    ///      #".SleepUntil(const Ticks&)".
    /// @param microseconds    Sleep time in microseconds.
    static void         SleepMicros     ( int64_t microseconds )
    { std::this_thread::sleep_for( std::chrono::microseconds( microseconds ) );  }
 
    /// Suspends the current thread by calling <em>std::this_thread::sleep_for</em>.
    /// \see Variants #".SleepMicros", #".SleepMillis", #".Sleep(const Ticks::Duration&)", and
    ///      #".SleepUntil(const Ticks&)".
    /// @param nanoseconds    Sleep time in nanoseconds.
    static void         SleepNanos      ( int64_t nanoseconds )
    { std::this_thread::sleep_for( std::chrono::nanoseconds( nanoseconds ) ); }
 
    /// Suspends the current thread by calling <em>std::this_thread::sleep_for</em>.
    /// \see Variants #".SleepUntil", #".SleepMicros", #".SleepMillis", and #".SleepNanos".
    /// @param duration    Sleep duration.
    static void        Sleep       ( const Ticks::Duration& duration )
    { std::this_thread::sleep_for( duration.Export() ); }
 
    /// Suspends the current thread by calling <em>std::this_thread::sleep_for</em>.
    /// \see Variants #".SleepUntil", #".SleepMicros", #".SleepMillis", and #".SleepNanos".
    /// @param duration    Sleep duration.
    static void        Sleep       ( const Ticks::Duration::TDuration& duration )
    { std::this_thread::sleep_for( duration ); }
 
    /// Suspends the current thread by calling <em>std::this_thread::sleep_for</em>.
    /// \see Variants #".Sleep(const Ticks::Duration&)", #".SleepMicros", #".SleepMillis", and
    ///      #".SleepNanos"
    /// @param time    Sleep duration.
    static void        SleepUntil  ( const Ticks& time )
    { std::this_thread::sleep_until( time.Export() ); }
}; // class Thread
 
} // namespace alib[threads]
 
#if !ALIB_SINGLE_THREADED
/// Type alias in namespace #"%alib".
using     Runnable=     threads::Runnable;
#endif
 
/// Type alias in namespace #"%alib".
using     Thread=       threads::Thread;
 
/// Type to store thread identifiers.
using     ThreadID=     threads::ThreadID;
 
} // namespace [alib]