rthread

#pragma once
 
#include <pthread.h>
 
#include <atomic>
#include <exception>
 
#include <randolf/rex>
 
namespace randolf {
 
  /*======================================================================*//**
  @brief
  This @ref rthread thread library provides an easier and sufficiently-complete
  object-oriented thread interface class for C++ that adds a properly-honoured
  destructor, and without terminating the entire application when the thread
  throws an exception.  This class also provides a virtual method for
  optionally handling all exceptions (that are otherwise ignored by default) in
  a penultimate stage prior to commencing onward to the final destructor stage.
 
  POSIX threads are the foundation of the rthread class, and the resulting C++
  interface will probably seem familiar to those who are familliar with Java.
 
  @par Features
  This is meant to be a safe and easy-to-use thread class for C++, which is
  intended to make thread sub-classing straight-forward in a logical manner for
  developers.  Some of the key features are:
 
     - Customizable constructor that doesn't automatically start the thread
        - Better control with the @ref start() method to start a previously
          constructed rthread
     - Abstract @ref run() method (required)
        - This method contains the code that will be run in its own thread
     - Customizable destructor that occurs only after the thread ends (which
       is particularly useful for daemon threads {a.k.a., detached threads})
     - Customizable exception handler method (just subclass it to use it)
     - Most methods are designed to be thread-safe (e.g., status methods)
 
  Some advanced features are planned that exceed what the basic thread
  functions provide, but are also needed:
 
     - thread groups (separate class), possibly with support for including
       threads in multiple groups
     - thread pool (separate class)
 
  @par Background
  I created this class to make it easier to write internet server daemons.  I
  started out using C-style thread functions (because C++ doesn't come with a
  thread class that can be sub-classed), and even with std::jthreads I ran into
  a serious problem with the thread's destructor executing while the thread was
  still running (the code that started it went out of scope) -- this is not
  what I expected because the running thread should really be an additional
  criteria for thread destruction (this is a serious concern since the
  premature destruction of a running thread usually results in a segmentation
  fault or other unpredictable behaviour that has the potential to cause the
  Operating System to exhibit other strange behaviours or even crash entirely).
 
  After looking for existing solutions (none of which resolved the ineherent
  problems with threads in C++), I embarked on creating this rthread class,
  which was highly educational but also wasn't difficult.  The end result is a
  small class that's easy to maintain, eliminates the reliability concerns, and
  is easy to use primarily because C++ thoroughly supports subclassing.
 
  My background in programming began when I was a young child, teaching myself
  BASIC and then machine language (when I found BASIC to be too limited) before
  moving on to other languages like Perl and Java many years later.  Eventually
  I circled around to C (which I chose to learn the hard way by writing some
  PostgreSQL extensions) and then C++ a few years after that.  I have a lot of
  experience with programming threadded applications on a variety of platforms
  that support pthreads (including Novell's NetWare), running application code
  I created that ran hundreds of thousands of threads successfully serving a
  similar number of users globally without slowdowns or crashes.
  @par History
    - 2022-Oct-22 v1.00 Initial version
    - 2024-Oct-23 v1.00 Various minor improvements to the documentation since
                        the previous update
  @version 1.00
  @author Randolf Richardson
 
  *///=========================================================================
  class rthread {
    private:
             pthread_t  __rthread_pthread_id = 0;
      std::atomic_bool  __rthread_running    = false;
      std::atomic_bool  __rthread_detached   = false;
      std::atomic_bool  __rthread_death      = false; // Destructor changes this to TRUE
      std::atomic_bool  __rthread_reuseable  = false; // Change this to a total-run-count // If set to TRUE, then this thread can be run again without needing to be re-constructed
      std::atomic_ulong __rthread_used       = 0;     // Total number of times this thread was started
 
      /*======================================================================*//**
      Return Code check, and throws an rthread-specific exception if an error
      occurred, which is indicated by @c -1 (a lot of example code shows @c < @c 1
      comparisons, but we specifically test for @c -1 because the documentation
      clearly states @c -1.  This is important because a system that can support an
      extremely high number of socket handles might, in theory, assign handles with
      values that get interpreted as negative integers, and so less-than-zero tests
      would result in dropped packets or dropped sockets (any such socket code that
      allocates such handles obviously must not ever allocate @c -1 since this
      would definitely be misinterpreted as an error).
 
      If rc is not @c -1, then it is simply returned as is.
 
      If n is nonzero and rc is 0, then n will override errno.  (This option is
      provided to accomodate the few socket library functions that return values
      that are never errors, and expect the developer to rely on other means of
      detecting whether an error occurred.  This is an example of where Object
      Oriented Programming is helpful in making things better.)
      @returns Original value of @c rc (if no exceptions were thrown)
      *///=========================================================================
      const int __rc_check_pthread(
      /// Return code
      const int rc,
      /// Exception handling flags (see @ref rex::REX_FLAGS for details)
      const int flags = rex::rex::REX_FLAGS::REX_DEFAULT) {
        if (rc != 0) {
          randolf::rex::mk_exception("", rc, flags); // This function doesn't return (this code ends here)
        } // -x- if rc -x-
        return rc;
      }; // -x- int __rc_check_pthread -x-
 
    public:
      /*======================================================================*//**
      @brief
      Default constructor.
      You can subclass this constructor and/or create parameterized constructors,
      any of which may throw exceptions (even though this default one doesn't).
 
      This is particularly useful for performing pre-run setup before starting the
      thread (see the @ref run() and @ref start() methods for details), especially
      with threads that start running in response to external events (such as user
      interaction events, incoming internet socket connections, etc.).
      *///=========================================================================
      rthread() noexcept {}; // -x- constructor rthread -x-
 
      /*======================================================================*//**
      @brief
      Default destructor.  Called only after two conditions are met:
         1. this rthread has gone out of scope
         2. termination of the underlying pthread (this is different from the
            standard C++ implementation of threads and jthreads, which don't have
            this criteria)
 
      Exceptions are handled by the @ref _rthread_exceptions() method before this
      destructor is activated.
 
      You can add your own destructor to safely ensure that files and sockets are
      closed, and that resources are freed, deallocated, deleted, etc., which is
      essential to preventing various types of resource leaks if your thread code
      (in the @ref run() method) exited early due to an unexpected exception (it is
      the developer's responsibility to ensure resources are managed properly, and
      this destructor provides a means of handling this reliably).
 
      Logging, re-queuing, semaphore completions, etc., can also be handled in this
      method because it runs after the termination of the underlying pthread.
      @warning
      Do not throw exceptions from this method.  If you're relying on a function or
      a class that might throw exceptions (intended or otherwise), then you need to
      take care to at least utilize a final try/catch block for @c std::exception.
      *///=========================================================================
      virtual ~rthread() noexcept { // Destructor (subclass destructor will run first if it's defined)
        __rthread_death = true;
        if (__rthread_running && !__rthread_detached) {
          pthread_detach(__rthread_pthread_id);
          __rthread_detached = true;
        } // -x- if __rthread_running -x-
//std::cout << "rthread " << __rthread_pthread_id << " destruction completed / __rthread_running=" << __rthread_running << std::endl;
        if (__rthread_running) pthread_cancel(__rthread_pthread_id); // This must be the very last; any commands after this will cause:  terminate called without an active exception
        // TODO:  pthread_setcancelstate, pthread_setcanceltype, and pthread_testcancel
      }; // -x- destructor rthread -x-
 
      /*======================================================================*//**
      @brief
      Final rthread exception handler.
      If an uncaught exception is thrown from the @ref run() method in a running
      rthread, then it will be handled by this method (which is still technically
      running on the underlying pthread).  Override this method to handle known and
      unknown exceptions gracefully, before the destructor (or reinitiator) runs.
      @warning
      If @c e is @c nullptr it means an unknown exception was thrown (e.g.,
      internally we literally caught `(...)` (other exception), in which case
      you'll need to use @c std::current_exception() to access it.
      @note
      For a reuseable rthread, the @ref running status will be set to false during
      @ref _rthread_reinitialize execution, which can be useful for handling those
      exceptions separately within this code (by testing for the @ref running()
      condition).
      *///=========================================================================
      virtual void _rthread_exceptions(
      /// Exceptions (see warning, immediately above)
      std::exception* e) noexcept {}; // -x- void rthread_exceptions -x-
 
      /*======================================================================*//**
      @brief
      Re-initialize internal variables, refresh resources, etc., before re-running
      a @ref reuseable rthread.
      When utilizing the reuseable feature, this method can be thought of as having
      similar functionality to that of the constructor, except that it is used to
      do the following to bring internal variables and resources back to the same
      state that the constructor originally initialized them to, and thus reducing
      construction overhead (some variables may not need re-initializing, which can
      also help to further-reduce overhead):
         - close any open files, sockets, etc., that need to be closed (or reset
           file pointers instead of re-opening files)
         - reset/clear variables and memory structures to their expected defaults
           (or free-and-allocate resources that can't be reset or cleared reliably)
         - re-add @c this to a thread pool or concurrent queue of ready rthreads
 
      @note
      If there is any clean-up, logging, etc., peformed in the destructor that also
      needs to be performed here, the best approach is to create a private method
      for those particular actions and then call it from this method as well as the
      destructor for better operational consistency.
      @see reuseable
      *///=========================================================================
      virtual void _rthread_reinitialize() noexcept {}; // -x- void rthread_reinitialize -x-
 
      /*======================================================================*//**
      @brief
      Daemonize this rthread.
 
      If this rthread was previously detached, then this method has no effect (but
      won't cause the randolf::rex::xEINVAL exception to be thrown; there may be
      other reasons for this exception to be thrown).
      @par Threads
      This method is thread-safe.
 
      @throws randolf::rex::xEINVAL Not a joinable rthread
      @throws randolf::rex::xESRCH A pthread with the underlying @c pthread_id
              couldn't be found (underlying pthread doesn't exist)
 
      @returns The same rthread object so as to facilitate stacking
      @see detached
      @see start_detached
      *///=========================================================================
      rthread* detach() {
        if (__rthread_running && !__rthread_detached) {
          __rc_check_pthread(pthread_detach(__rthread_pthread_id));
          __rthread_detached = true;
        } // -x- if __rthread_running -x-
        return this;
      }; // -x- rthread* detach -x-
 
      /*======================================================================*//**
      @brief
      Find out whether this rthread is daemonized.
      @par Threads
      This method is thread-safe.
      @returns TRUE = daemonized
      @returns FALSE = not daemonized
      @see detach
      @see start_detached
      *///=========================================================================
      bool detached() noexcept {
        return __rthread_detached;
      }; // -x- bool detached -x-
 
      /*======================================================================*//**
      @brief
      Join this rthread to the current thread that called this method.  (This is
      how non-daemonized threads are normally terminated.)
      @note
      This method blocks until this rthread's underlying pthread is terminated.
      @par Threads
      This method is thread-safe.
 
      @throws randolf::rex::xEDEADLK Deadlock detected because two threads are
              queued to join with each other, or the current rthread is trying to
              join with itself
      @throws randolf::rex::xEINVAL Not a joinable rthread
      @throws randolf::rex::xEINVAL A different thread is already queued to join
              with this rthread
      @throws randolf::rex::xESRCH A pthread with the underlying @c pthread_id
              couldn't be found (underlying pthread doesn't exist)
 
      @returns The same rthread object so as to facilitate stacking
      @see stop
      *///=========================================================================
      rthread* join() {
        if (__rthread_running) {
          __rthread_running = false; // Do this before pthread_join to signal an immediate shutdown
          __rc_check_pthread(pthread_join(__rthread_pthread_id, NULL));
          __rthread_detached = true; // TODO:  Determine if this should actually be set to FALSE
        } // -x- if __rthread_running -x-
        return this;
      }; // -x- rthread* join -x-
 
      /*======================================================================*//**
      @brief
      Find out what the underlying @c pthread_id is.
 
      Advanced developers may want easy access to this ID for a variety of reasons.
 
      @warning
      This method is not thread-safe.
 
      @returns ID number of underlying pthread (0 = not assigned, which is what you
               should expect to find if this rthread didn't @ref start() yet)
      *///=========================================================================
      pthread_t pthread_id() noexcept {
        return __rthread_pthread_id;
      }; // -x- pthread_t pthread_id -x-
 
      /*======================================================================*//**
      @brief
      Find out whether this rthread can be re-used.
      @par Threads
      This method is thread-safe.
      @returns TRUE = re-useable
      @returns FALSE = not re-useable
      *///=========================================================================
      bool reuseable() noexcept {
        return __rthread_reuseable;
      }; // -x- bool reuseable -x-
 
      /*======================================================================*//**
      @brief
      Configure whether this rthread can be re-used.
      @par Threads
      This method is thread-safe.
      @returns The same rthread object so as to facilitate stacking
      @see _rthread_reinitialize
      *///=========================================================================
      rthread* reuseable(
      /// TRUE = Set this rthread to be re-useable@n
      /// FALSE = Set this rthread to not be re-useable
      bool flag) noexcept {
        __rthread_reuseable = flag;
        return this;
      }; // -x- rthread* reuseable -x-
 
      /*======================================================================*//**
      @brief
      Thread functionality (subclassing this method is required).
      @warning
      Do not call this method directly.  To properly begin rthread execution, use
      either of the @ref start() or @ref start_detached() methods.
      When subclassing rthread, you need to override this method with the code that
      is to be executed as a separate thread.  (You don't have to move all of your
      code into this method; in fact, you can simply use this method to call out to
      code elsewhere, or call methods on instantiated classes that were referenced
      during the instantiation of your overriding rthread() constructor, etc.)
      @note
      Minimally, this is the only method that's required when sub-classing rthread.
      @see detach
      @see detached
      @see start
      @see start_detached
      *///=========================================================================
      virtual void run() = 0; // Not requiring this method in the subclass is completely and utterly pointless
 
      /*======================================================================*//**
      @brief
      Find out how many times this rthread was started.
      This method is only really meaningful for @ref reuseable rthreads.
      @par Threads
      This method is thread-safe.
      @returns Run count
      @see _rthread_reinitialize
      @see reuseable
      *///=========================================================================
      ulong run_count() noexcept {
        return __rthread_used;
      }; // -x- ulong run_count -x-
 
      /*======================================================================*//**
      @brief
      Find out whether this rthread is actively running.
      @par Threads
      This method is thread-safe.
      @returns TRUE = running
      @returns FALSE = not running
      @see start
      @see stop
      *///=========================================================================
      bool running() noexcept {
        return __rthread_running;
      }; // -x- bool running -x-
 
      /*======================================================================*//**
      @brief
      Commence execution of the @c run() method as a separate rthread.
      @par Threads
      This method is thread-safe.
 
      @throws randolf::rex::xEWOULDBLOCK (xEAGAIN) Insufficient resources to start
              the underlying pthread
      @throws randolf::rex::xEWOULDBLOCK (xEAGAIN) Maximum number-of-threads limit
              reached
 
      @returns The same rthread object so as to facilitate stacking
      @see detach
      @see detached
      @see start_detached
      @see stop
      *///=========================================================================
      rthread* start() {
        __rc_check_pthread(pthread_create(&__rthread_pthread_id, NULL, __rthread_run, this));
        __rthread_used++; // Increment thread run count
        return this;
      }; // -x- rsocket* start -x-
 
      /*======================================================================*//**
      @brief
      Commence execution of the @c run() method as a separate thread in a
      daemonized state.
      @par Threads
      This method is thread-safe.
 
      @throws randolf::rex::xEDEADLK Deadlock detected because two threads are
              queued to join with each other, or the current rthread is trying to
              join with itself
      @throws randolf::rex::xEINVAL Not a joinable rthread
      @throws randolf::rex::xEINVAL A different thread is already queued to join
              with this rthread
      @throws randolf::rex::xENOMEM Insufficient memory (on Linux this normally
              always succeeds, but there's not guarantee as the community suggests
              that this could change in the future)
      @throws randolf::rex::xESRCH A pthread with the underlying @c pthread_id
              couldn't be found (underlying pthread doesn't exist)
 
      @returns The same rthread object so as to facilitate stacking
      @see detach
      @see detached
      @see start
      @see stop
      *///=========================================================================
      rthread* start_detached() { // Use this instead of calling detach() separately to prevent the highly improbable instance of detaching a thread after it already finished
        pthread_attr_t attr;
        __rc_check_pthread(pthread_attr_init(&attr)); // Overwrite contents of "attr" structure
        __rc_check_pthread(pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED));
        __rc_check_pthread(pthread_create(&__rthread_pthread_id, &attr, __rthread_run, this));
        __rthread_detached = true;
        __rthread_used++; // Increment thread run count
        return this;
      }; // -x- rthread* start_detached -x-
 
      /*======================================================================*//**
      @brief
      Request the graceful termination of this rthread.
      @warning
      One side-effect of this method is to daemonize this rthread because stop() 
      serves as an alternative to the @ref join() method.
      @note
      It is the responsibility of developers to include periodic checks throughout
      their code (assumedly at convenient points, which is common) by utilizing the
      @ref running() method to determine whether to start winding things down.
      @par Threads
      This method is thread-safe.
 
      @throws randolf::rex::xEINVAL Not a joinable rthread
      @throws randolf::rex::xESRCH A pthread with the underlying @c pthread_id
              couldn't be found (underlying pthread doesn't exist)
 
      @returns The same rthread object so as to facilitate stacking
      @see join
      @see start
      @see start_detached
      *///=========================================================================
      rthread* stop() noexcept { // This doesn't cancel the thread; it just indicates that it needs to stop running -- it's up to the code in the subclassed run() method to check periodically if it should stop by using the running() method
        if (__rthread_running) {
          detach();
          __rthread_running = false;
        }// -x- if __rthread_running -x-
        return this;
      }; // -x- rthread* stop -x-
 
    private:
      /*======================================================================*//**
      @brief
      This internal method starts the underlying pthread, and does the following:
 
         1. catches any exceptions that the thread might have thrown (and, if any
            were caught, in turn calls the @ref exceptions() method)
 
         2. if this rthread is reuseable, makes preparations for re-use, including
            calling the re-constructor method (if it was subclassed)
 
         3. if this rthreads is not reuseable, affect its destruction
 
      @par Threads
      This method is thread-safe.
      *///=========================================================================
      static void* __rthread_run(
      // Pointer to subclassed rthread object, which @c pthread_create() passes as type @c void*
      void* arg) noexcept {
 
        // --------------------------------------------------------------------------
        // Alias (void*)arg to (rthread*)r so we can just write r-> instead of having
        // write ((rthread*)arg)-> repeatedly (the compiler will effectively do this
        // for us).
        // --------------------------------------------------------------------------
        rthread* r = (rthread*)arg;
 
        // --------------------------------------------------------------------------
        // Indicate that this rthread is running.
        //
        // We must set this before starting the underlying thread to avoid a
        // potential race condition if there's a loop within the thread that first
        // checks whether the thread is in a running state.
        // --------------------------------------------------------------------------
        r->__rthread_running = true; // This will be set to false in the destructor (or the reinitiator)
 
        // --------------------------------------------------------------------------
        // Call the subclassed run() method.
        // --------------------------------------------------------------------------
        try {
          r->run();
        } catch (std::exception* e) { // Handle a known exception
          r->_rthread_exceptions(e);
        } catch (...) { // Handle an unknown exception
          r->_rthread_exceptions(nullptr);
        }
 
        // --------------------------------------------------------------------------
        // This is where it becomes possible to reuse an rthread.  The amount of work
        // required to just terminate a non-reusable (default) rthread is very little
        // compared to preparing an rthread to be reuseable at this point, but the
        // trade-off is worthwhile when performing a minimal (and probably partial)
        // re-initialization whilst also avoiding re-instantiating an rthread object.
        // --------------------------------------------------------------------------
        if (r->__rthread_reuseable) { // This rthread is reuseable
          r->__rthread_detached = false; // Reset internal flags because each thread will begin as not-detached
          r->__rthread_running  = false; // Clear the "running" status
          try {
            r->_rthread_reinitialize();
          } catch (std::exception* e) { // Handle a known exception
            r->_rthread_exceptions(e);
          } catch (...) { // Handle an unknown exception
            r->_rthread_exceptions(nullptr);
          }
 
        // --------------------------------------------------------------------------
        // If an rthread is not flagged as re-useable, then it needs to be deleted.
        // --------------------------------------------------------------------------
        } else { // This rthread is not reuseable
          delete r; // Initiate destructor(s) since rthread is not reuseable
        } // -x- if __rthread_reuseable -x-
 
        return r; // Same as "return arg;" but in this case we're expressing intent by returning "r"
      }; // -x- void* __rthread_run -x-
 
  }; // -x- class rthread -x-
  
} // -x- namespace randolf -x-