thread_wrapper.hpp

Go to the documentation of this file.

#ifndef LIBJMMCG_CORE_THREAD_WRAPPER_HPP
#define LIBJMMCG_CORE_THREAD_WRAPPER_HPP
 
/******************************************************************************
** Copyright © 2004 by J.M.McGuiness, coder@hussar.me.uk
**
** This library is free software; you can redistribute it and/or
** modify it under the terms of the GNU Lesser General Public
** License as published by the Free Software Foundation; either
** version 2.1 of the License, or (at your option) any later version.
**
** This library 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
** Lesser General Public License for more details.
**
** You should have received a copy of the GNU Lesser General Public
** License along with this library; if not, write to the Free Software
** Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
 
/**
   \file
   Note that this file should be included after any MFC header files, or you'll get an error about WINDOWS.H being included.
*/
 
#include "private_/thread_base.hpp"
 
namespace jmmcg { namespace LIBJMMCG_VER_NAMESPACE { namespace ppd {
 
   /// A handy utility class for the "thread_wrapper" class, that is supposed to do nothing.
   /**
      The idea is that you could have an automatic instance of this object that surrounds the worker_fn() method, is automatically instantiated in the process() method and released upon exit of the process() method.
   */
   struct null_thread_worker_context {
      // Does nothing! No context for the worker thread.
 
      /**
         To assist in allowing compile-time computation of the algorithmic order of the threading model.
      */
      static constexpr ppd::generic_traits::memory_access_modes memory_access_mode=ppd::generic_traits::memory_access_modes::crew_memory_access;
   };
 
   /// This class is used to implement a class that wraps using a thread, it is an alternative to using a thread pool to manage your threads.
   /**
      Note that the most derived classes' dtor must call private_::thread_base::wait_thread_exit() in it's dtor to ensure that the thread goes out of scope before the object upon which it relies.
    */
   template<
      generic_traits::api_type API,
      typename Mdl,
      typename TWC=null_thread_worker_context   ///< This now allows for the worker thread to implement worker-thread specific-context, e.g. COM initialisation for apartment threading! (As the object here is constructed on the stack and within the context of the worker thread in the process() method, but before the worker_fn() method is called. This object must have a default constructor. Thanks to George Velimachitis (he suggested the context template idea)!
   >
   class wrapper : public private_::thread_base<API, Mdl> {
   public:
      using base_t=private_::thread_base<API, Mdl>;
      using thread_context_t=TWC;
      using lock_traits=typename base_t::lock_traits;
      using thread_traits=typename base_t::thread_traits;
      using os_traits=typename base_t::os_traits;
      using exception_type=typename os_traits::exception_type;
 
      /**
         To assist in allowing compile-time computation of the algorithmic order of the threading model.
      */
      static constexpr ppd::generic_traits::memory_access_modes memory_access_mode=(
         base_t::memory_access_mode==ppd::generic_traits::memory_access_modes::crew_memory_access
         && lock_traits::anon_event_type::memory_access_mode==ppd::generic_traits::memory_access_modes::crew_memory_access
         ? ppd::generic_traits::memory_access_modes::crew_memory_access
         : ppd::generic_traits::memory_access_modes::erew_memory_access
      );
 
      /// Create the wrapper object. Note that the underlying kernel thread will not have been created.
      /**
         \see base_t::create_running()
      */
      __stdcall wrapper(const wrapper &) noexcept(true) FORCE_INLINE;
 
      __stdcall ~wrapper() noexcept(false) override FORCE_INLINE;
 
      wrapper(wrapper &&)=delete;
      void operator=(wrapper const &)=delete;
      void operator=(wrapper &&)=delete;
 
   protected:
      /**
         \todo Consider moving this event into the stack of process() as an automatic variable in there. This may be useful in implementing detached threads. Detached threads may be useful in improving performance of horizontal threading, because the work_complete() lock in them won't have to wait for non-dependent work to complete before it returns.
      */
      mutable std::atomic<bool> exit_requested;
 
      explicit __stdcall wrapper(const typename thread_traits::api_params_type::suspend_period_ms ew_=50) noexcept(false) FORCE_INLINE;
 
      explicit __stdcall wrapper(thread_context_t &&thread_context, const typename thread_traits::api_params_type::suspend_period_ms ew_=50) noexcept(false) FORCE_INLINE;
 
      /// The method used to determine if there has been a request for the thread to exit, and therefore finish processing work, called before attempting to process() a work item.
      /**
         \return true if an exit from the thread has been requested, otherwise false to continue processing.
      */
      virtual bool __fastcall pre_exit() noexcept(false) FORCE_INLINE;
 
      /// This is the main "work" function. Implement it to do some work in the thread.
      /**
         \param context The context is non-const, to allow the client to modify the state of the context, if they need to. (Although this generalisation may be really required....)
 
         \return "false" to continue working. Otherwise return "true" to exit. (Or throw an exception - but that's a messy way to exit...)
      */
      virtual bool __fastcall worker_fn(thread_context_t &context) noexcept(false)=0;
      /// Override this function is you want to do some other work to signal the exit of the thread.
      /**
         This is primarily used by the destructor to politely tell the thread function to quit. Note that if you override this function you must still implement the exit functionality, otherwise the destructor will time-out and terminate the worker thread.
      */
      typename thread_traits::api_params_type::states __fastcall process() noexcept(false) override;
 
   private:
      thread_context_t thread_context_;
   };
 
   /// This class is used to implement a class that wraps using a thread, it is an alternative to using a thread pool to manage your threads, in a C++ std::thread-style manner.
   /**
      \see wrapper, std::thread
   */
   template<
      generic_traits::api_type API,
      typename Mdl
   >
   class thread final : public wrapper<API, Mdl, std::function<void()>> {
   public:
      using base_t=wrapper<API, Mdl, std::function<void()>>;
      using thread_context_t=typename base_t::thread_context_t;
      using lock_traits=typename base_t::lock_traits;
      using thread_traits=typename base_t::thread_traits;
      using os_traits=typename base_t::os_traits;
      using exception_type=typename base_t::exception_type;
 
      /**
         To assist in allowing compile-time computation of the algorithmic order of the threading model.
      */
      static constexpr ppd::generic_traits::memory_access_modes memory_access_mode=(
         base_t::memory_access_mode==ppd::generic_traits::memory_access_modes::crew_memory_access
         && lock_traits::anon_event_type::memory_access_mode==ppd::generic_traits::memory_access_modes::crew_memory_access
         ? ppd::generic_traits::memory_access_modes::crew_memory_access
         : ppd::generic_traits::memory_access_modes::erew_memory_access
      );
 
      explicit __stdcall thread(const typename thread_traits::api_params_type::suspend_period_ms ew_=50) noexcept(false) FORCE_INLINE;
      /// Create the wrapper object. Note that the underlying kernel thread will have been created, so the proc_fn will execute in the underlying thread (if any).
      /**
         This ctor requires a memory allocation for the functor.
 
         \param   proc_fn  The functor that will executed by the underlying kernel thread (if any).
         
         \see create_running()
      */
      template<class ProcFn>
      explicit __stdcall thread(ProcFn &&proc_fn, const typename thread_traits::api_params_type::suspend_period_ms ew_=50) noexcept(false) FORCE_INLINE;
 
      __stdcall ~thread() noexcept(false) override FORCE_INLINE;
 
   private:
      bool __fastcall worker_fn(thread_context_t &context) noexcept(false) override;
   };
 
} } }
 
#include "thread_wrapper_impl.hpp"
 
#endif