jaulib v1.3.0
Jau Support Library (C++, Java, ..)
Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | List of all members
jau::service_runner Class Reference

Service runner, a reusable dedicated thread performing custom user services. More...

#include <service_runner.hpp>

Collaboration diagram for jau::service_runner:

Public Types

typedef function< void(service_runner_ref)> Callback
 
typedef service_runnerservice_runner_ref
 

Public Member Functions

 service_runner (std::string name, fraction_i64 service_shutdown_timeout, Callback service_work, Callback service_init_locked=Callback(), Callback service_end_locked=Callback()) noexcept
 Service runner constructor. More...
 
 ~service_runner () noexcept
 Service runner destructor. More...
 
std::condition_variable & cv_shall_stop () noexcept
 mtx_shall_stop() and cv_shall_stop() allows caller to be notified when shall_stop() changes, i.e. More...
 
bool is_running () const noexcept
 Returns true if service is running. More...
 
bool join () noexcept
 Blocks the current thread until service is stopped or returns immediately if not running or called from the service thread. More...
 
std::mutex & mtx_shall_stop () noexcept
 mtx_shall_stop() and cv_shall_stop() allows caller to be notified when shall_stop() changes, i.e. More...
 
const std::string & name () const noexcept
 Return the given name of this service. More...
 
fraction_i64 service_shutdown_timeout () const noexcept
 Returns maximum duration in fractions of seconds to wait for service to stop at stop() and join(), where fractions_i64::zero waits infinitely. More...
 
void set_shall_stop () noexcept
 Marks the service thread to stop in due process by flagging shall stop to true. More...
 
bool shall_stop () const noexcept
 Returns true if service shall stop. More...
 
bool shall_stop2 (int dummy) noexcept
 Helper function to easy FunctionDef usage w/o creating a lambda alike capture with same semantics as shall_stop(). More...
 
void start () noexcept
 Starts this service, if not running already. More...
 
bool stop () noexcept
 Stops this service, if running. More...
 
pthread_t thread_id () const noexcept
 Return the thread-id of this service service thread, zero if not running. More...
 
std::string toString () const noexcept
 Returns a string representation of this service. More...
 

Static Public Member Functions

static bool remove_sighandler () noexcept
 Remove the sighandler. More...
 
static bool singleton_sighandler () noexcept
 Install the singleton SIGALRM sighandler instance. More...
 

Static Public Attributes

static const ::pid_t pid_self = ::getpid()
 

Detailed Description

Service runner, a reusable dedicated thread performing custom user services.

Definition at line 59 of file service_runner.hpp.

Member Typedef Documentation

◆ service_runner_ref

Definition at line 61 of file service_runner.hpp.

◆ Callback

Definition at line 62 of file service_runner.hpp.

Constructor & Destructor Documentation

◆ service_runner()

service_runner::service_runner ( std::string  name,
fraction_i64  service_shutdown_timeout,
Callback  service_work,
Callback  service_init_locked = Callback(),
Callback  service_end_locked = Callback() 
)
noexcept

Service runner constructor.

start() shall be issued to kick off this service.

Parameters
nameservice name
service_shutdown_timeoutmaximum duration in fractions of seconds to wait for service to stop at stop() and join(), where fractions_i64::zero waits infinitely
service_workservice working function
service_init_lockedoptional service init function, lifecycle mutex is locked
service_end_lockedoptional service end function, lifecycle mutex is locked

Definition at line 118 of file service_runner.cpp.

◆ ~service_runner()

service_runner::~service_runner ( )
noexcept

Service runner destructor.

Issues stop()

Definition at line 134 of file service_runner.cpp.

Member Function Documentation

◆ remove_sighandler()

bool service_runner::remove_sighandler ( )
staticnoexcept

Remove the sighandler.

Definition at line 104 of file service_runner.cpp.

◆ singleton_sighandler()

static bool jau::service_runner::singleton_sighandler ( )
inlinestaticnoexcept

Install the singleton SIGALRM sighandler instance.

  • First call will install the sighandler
  • Should be called at least once within the application using jau::service_runner

Definition at line 102 of file service_runner.hpp.

◆ name()

const std::string & jau::service_runner::name ( ) const
inlinenoexcept

Return the given name of this service.

Definition at line 144 of file service_runner.hpp.

Here is the caller graph for this function:

◆ service_shutdown_timeout()

fraction_i64 jau::service_runner::service_shutdown_timeout ( ) const
inlinenoexcept

Returns maximum duration in fractions of seconds to wait for service to stop at stop() and join(), where fractions_i64::zero waits infinitely.

See also
stop()
join()

Definition at line 151 of file service_runner.hpp.

◆ thread_id()

pthread_t jau::service_runner::thread_id ( ) const
inlinenoexcept

Return the thread-id of this service service thread, zero if not running.

Definition at line 156 of file service_runner.hpp.

Here is the caller graph for this function:

◆ is_running()

bool jau::service_runner::is_running ( ) const
inlinenoexcept

Returns true if service is running.

See also
start()
stop()
join()

Definition at line 165 of file service_runner.hpp.

Here is the caller graph for this function:

◆ shall_stop()

bool jau::service_runner::shall_stop ( ) const
inlinenoexcept

Returns true if service shall stop.

This flag can be used by the service_work Callback to determine whether to skip lengthly tasks, or even to skip stopping this service (again).

See also
is_running()
set_shall_stop()
mtx_shall_stop()
cv_shall_stop()
start()
stop()
join()

Definition at line 181 of file service_runner.hpp.

Here is the caller graph for this function:

◆ shall_stop2()

bool jau::service_runner::shall_stop2 ( int  dummy)
inlinenoexcept

Helper function to easy FunctionDef usage w/o creating a lambda alike capture with same semantics as shall_stop().

The const qualifier has also been lifted, since free function pointer declarations can't match it.

Parameters
dummya dummy argument to help FunctionDef template parameter pack, not used
See also
shall_stop()

Definition at line 192 of file service_runner.hpp.

◆ set_shall_stop()

void service_runner::set_shall_stop ( )
noexcept

Marks the service thread to stop in due process by flagging shall stop to true.

See also
is_running()
shall_stop()
mtx_shall_stop()
cv_shall_stop()
start()
stop()
join()

Definition at line 140 of file service_runner.cpp.

Here is the caller graph for this function:

◆ mtx_shall_stop()

std::mutex & jau::service_runner::mtx_shall_stop ( )
inlinenoexcept

mtx_shall_stop() and cv_shall_stop() allows caller to be notified when shall_stop() changes, i.e.

start(), set_shall_stop() or stop() is called.

Definition at line 207 of file service_runner.hpp.

◆ cv_shall_stop()

std::condition_variable & jau::service_runner::cv_shall_stop ( )
inlinenoexcept

mtx_shall_stop() and cv_shall_stop() allows caller to be notified when shall_stop() changes, i.e.

start(), set_shall_stop() or stop() is called.

Definition at line 210 of file service_runner.hpp.

◆ start()

void service_runner::start ( )
noexcept

Starts this service, if not running already.

Methods blocks the current thread until service is started.

See also
is_running()
shall_stop()
set_shall_stop()
mtx_shall_stop()
cv_shall_stop()
stop()
join()
service_shutdown_timeout()

Definition at line 148 of file service_runner.cpp.

Here is the caller graph for this function:

◆ stop()

bool service_runner::stop ( )
noexcept

Stops this service, if running.

If called from the service thread, method just issues set_shall_stop() without blocking, otherwise methods blocks the current thread until service is stopped.

Maximum blocked wait period is optionally limited by service_shutdown_timeout().

Method attempts to stop the service thread

  • by flagging shall stop via set_shall_stop()
  • if not called from the service thread itself:
    • sending SIGALRM to the service thread
    • waiting until service thread has stopped or timeout occurred

Implementation requires a SIGALRM handler to be install, e.g. using singleton_sighandler().

Returns
true if thread has been stopped or false if timeout has been hit
See also
is_running()
shall_stop()
set_shall_stop()
mtx_shall_stop()
cv_shall_stop()
start()
join()
service_shutdown_timeout()
singleton_sighandler()

Definition at line 177 of file service_runner.cpp.

Here is the caller graph for this function:

◆ join()

bool service_runner::join ( )
noexcept

Blocks the current thread until service is stopped or returns immediately if not running or called from the service thread.

Maximum blocked wait period is optionally limited by service_shutdown_timeout().

Returns
true if thread has been stopped or false if timeout has been hit
See also
is_running()
shall_stop()
set_shall_stop()
mtx_shall_stop()
cv_shall_stop()
start()
stop()
service_shutdown_timeout()

Definition at line 221 of file service_runner.cpp.

◆ toString()

std::string service_runner::toString ( ) const
noexcept

Returns a string representation of this service.

Definition at line 256 of file service_runner.cpp.

Here is the caller graph for this function:

Member Data Documentation

◆ pid_self

const ::pid_t service_runner::pid_self = ::getpid()
static

Definition at line 64 of file service_runner.hpp.


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