feisty meow concerns codebase  2.140
processes::ethread Class Referenceabstract

Provides a platform-independent object for adding threads to a program. More...

#include <ethread.h>

Inheritance diagram for processes::ethread:
Collaboration diagram for processes::ethread:

Public Types

enum  timed_thread_types { TIGHT_INTERVAL , SLACK_INTERVAL }
 

Public Member Functions

 ethread ()
 creates a single-shot thread object. More...
 
 ethread (int sleep_timer, timed_thread_types how=SLACK_INTERVAL)
 creates a managed thread object that runs on a periodic interval. More...
 
virtual ~ethread ()
 
 DEFINE_CLASS_NAME ("ethread")
 
bool start (void *thread_data)
 causes the thread to start, if it has not already been started. More...
 
void stop ()
 tells the thread to shutdown and waits for the shutdown to occur. More...
 
void cancel ()
 stops the thread but does not wait until it has terminated. More...
 
virtual void perform_activity (void *thread_data)=0
 < invoked just after after start(), when the OS thread is created. More...
 
void exempt_stop ()
 this special form of stop() does not wait for the thread to exit. More...
 
void reschedule (int delay=0)
 causes a periodic thread to activate after "delay" milliseconds from now. More...
 
int sleep_time () const
 returns the current periodic thread interval. More...
 
void sleep_time (int new_sleep)
 adjusts the period for the thread to the "new_sleep" interval. More...
 
bool thread_started () const
 returns true if the thread has been started. More...
 
bool thread_finished () const
 returns true if the thread has exited. More...
 
bool thread_active () const
 returns true if the thread is currently performing its activity. More...
 
bool should_stop () const
 reports whether the thread should stop right now. More...
 

Detailed Description

Provides a platform-independent object for adding threads to a program.

This greatly simplifies creating and managing threads by hiding all the operating system details. The user just needs to override one virtual function in their derived object to perform the main activity of their thread. The thread can be a one time invocation or it can run periodically. Control over the thread remains in the hands of the program that started it.

Definition at line 35 of file ethread.h.

Member Enumeration Documentation

◆ timed_thread_types

Enumerator
TIGHT_INTERVAL 
SLACK_INTERVAL 

Definition at line 49 of file ethread.h.

Constructor & Destructor Documentation

◆ ethread() [1/2]

processes::ethread::ethread ( )

creates a single-shot thread object.

the OS-level thread is not started until the start() method is invoked. this constructor creates a thread that will only execute once; when start() is called, the thread starts up and performs its activity. it will then stop. to run it again, start() must be invoked again. however, if the perform_activity() method just keeps running, then the single-shot thread can live as long as needed. it is important for such a thread to periodically check should_exit() to avoid having the program hang-up when it's supposed to be shutting down.

Definition at line 87 of file ethread.cpp.

References FUNCDEF.

◆ ethread() [2/2]

processes::ethread::ethread ( int  sleep_timer,
timed_thread_types  how = SLACK_INTERVAL 
)

creates a managed thread object that runs on a periodic interval.

the thread will activate every "sleep_timer" milliseconds. when start() is invoked, the thread's action (via the perform_activity() method) will be performed at regular intervals (using the specified value for "sleep_timer"). the thread will continue activating until the stop() method is called. a faster interval is used internally during sleep periods such that calling stop() will not consume the whole "sleep_timer" period. if the "how" is TIGHT_INTERVAL, then the thread will activate every "sleep_timer" milliseconds, as accurately as possible. if the "how" is SLACK_INTERVAL, then the thread will activate after a delay of "sleep_timer" milliseconds from its last activation. the latter mode allows the thread to consume its entire intended operation time knowing that there will still be slack time between when it is active. the former mode requires the thread to only run for some amount of time less than its "sleep_timer"; otherwise it will hog a lot of the CPU.

Definition at line 105 of file ethread.cpp.

References FUNCDEF, and processes::MINIMUM_SLEEP_PERIOD.

◆ ~ethread()

processes::ethread::~ethread ( )
virtual

Definition at line 126 of file ethread.cpp.

References stop(), and basis::WHACK().

Member Function Documentation

◆ cancel()

void processes::ethread::cancel ( )
inline

stops the thread but does not wait until it has terminated.

this is appropriate for use within the perform_activity() method.

Definition at line 84 of file ethread.h.

Referenced by stop(), and application::stdio_redirecter::zap_program().

◆ DEFINE_CLASS_NAME()

processes::ethread::DEFINE_CLASS_NAME ( "ethread"  )

◆ exempt_stop()

void processes::ethread::exempt_stop ( )

this special form of stop() does not wait for the thread to exit.

it is required in certain weird OS situations where the thread does not exit properly and stop() would cause an infinite wait. don't use it unless you are SURE that this is the case.

Definition at line 216 of file ethread.cpp.

Referenced by start().

◆ perform_activity()

virtual void processes::ethread::perform_activity ( void *  thread_data)
pure virtual

< invoked just after after start(), when the OS thread is created.

< the call comes in from the thread itself, so the derived method must be thread-safe. < this is invoked just before the thread is to be terminated.

< the call also comes in from the thread itself, so the implementation must be thread-safe. carries out the main activity of the thread. this is called repeatedly by the main thread management function and so should return as soon as possible. if it does not return fairly regularly, then the thread shutdown process will not occur until the function exits on its own.

◆ reschedule()

void processes::ethread::reschedule ( int  delay = 0)

causes a periodic thread to activate after "delay" milliseconds from now.

void ethread::pre_thread() {}

this resets the normal activation period, but after the next activation occurs, the normal activation interval takes over again.

void ethread::post_thread() {}

Definition at line 141 of file ethread.cpp.

◆ should_stop()

bool processes::ethread::should_stop ( ) const
inline

reports whether the thread should stop right now.

this returns true due to an invocation of stop() or cancel().

Definition at line 136 of file ethread.h.

Referenced by processes::post_office::deliver_mail_on_route(), and cromp::cromp_server::look_for_clients().

◆ sleep_time() [1/2]

int processes::ethread::sleep_time ( ) const
inline

returns the current periodic thread interval.

this is only meaningful for periodic threads.

Definition at line 114 of file ethread.h.

◆ sleep_time() [2/2]

void processes::ethread::sleep_time ( int  new_sleep)
inline

adjusts the period for the thread to the "new_sleep" interval.

this is only meaningful for periodic threads.

Definition at line 117 of file ethread.h.

◆ start()

bool processes::ethread::start ( void *  thread_data)

causes the thread to start, if it has not already been started.

if the thread has terminated previously, then this will restart the thread. true is returned if the thread could be started. false is returned if the thread could not be started or if it is already running.

Definition at line 146 of file ethread.cpp.

References exempt_stop(), FUNCDEF, LOG, processes::MAXIMUM_CREATE_ATTEMPTS, timely::time_stamp::reset(), processes::SNOOZE_FOR_RETRY, and thread_finished().

Referenced by processes::thread_cabinet::add_thread().

◆ stop()

void processes::ethread::stop ( )

tells the thread to shutdown and waits for the shutdown to occur.

this will cause the OS thread to terminate once the current (if any) perform_activity() invocation completes. the thread may be restarted with start().

Definition at line 197 of file ethread.cpp.

References cancel(), thread_finished(), and thread_started().

Referenced by application::stdio_redirecter::zap_program(), and ~ethread().

◆ thread_active()

bool processes::ethread::thread_active ( ) const
inline

returns true if the thread is currently performing its activity.

this information is not necessarily relevant even at the point it is returned (because of the nature of multethreading), so don't believe this information for anything important.

Definition at line 131 of file ethread.h.

◆ thread_finished()

bool processes::ethread::thread_finished ( ) const
inline

returns true if the thread has exited.

This can happen either by the thread responding to the stop() or cancel() methods or when the thread stops of its own accord. if this returns true, it means that the thread will not start up again unless the user invokes start().

Definition at line 125 of file ethread.h.

Referenced by processes::thread_cabinet::add_thread(), start(), and stop().

◆ thread_started()

bool processes::ethread::thread_started ( ) const
inline

returns true if the thread has been started.

this does not mean it is necessarily active.

Definition at line 122 of file ethread.h.

Referenced by stop().


The documentation for this class was generated from the following files: