#include <Main.h>

Classes
struct	CommandArgs

class	IApplicationRep

class	IServiceIntegrationRep

class	LoggerServiceWrapper

class	RunNoFrillsService

Public Types
enum class	ServiceIntegrationFeatures

enum class	State : uint8_t

Public Member Functions
	Main (const shared_ptr< IApplicationRep > &appRep, const shared_ptr< IServiceIntegrationRep > &serviceIntegrationRep=mkDefaultServiceIntegrationRep())

nonvirtual Containers::Set< ServiceIntegrationFeatures >	GetServiceIntegrationFeatures () const

nonvirtual void	Run (const CommandArgs &args, const Streams::OutputStream::Ptr< Characters::Character > &out=nullptr)

nonvirtual pid_t	GetServicePID () const

nonvirtual String	GetServiceStatusMessage () const

nonvirtual void	RunAsService ()

nonvirtual void	RunDirectly (const optional< Time::Duration > &runFor={})

nonvirtual void	ForcedStop (Time::DurationSeconds timeout)

nonvirtual void	ForcedRestart (Time::DurationSeconds timeout=Time::kInfinity, Time::DurationSeconds unforcedStopTimeout=Time::kInfinity)

Static Public Member Functions
static shared_ptr< IServiceIntegrationRep >	mkDefaultServiceIntegrationRep ()

Detailed Description

A service is a program that runs in the background on your computer, and has no user interface.

This is often very handy - and often useful to mix together with a related non-service (UI) program component.

This concept exists on both UNIX and Windows, but is implemented differently.

There are two different dimensions along which you can subtype the behavior of a service application: (1) the functionality the service provides (2) the OS service mechanism to use

Users of this class will themselves address #1, by subclassing from the IApplicationRep, and providing their application behavior. But users can also select different 'service implementation' strategies by selecting the IServiceIntegrationRep subtype to pass into the constructor. What service implementation strategies are available will depend on the OS you've built for, and often on command-line app arguments.

This class is sort of like a singleton, in that it can be instantiated only once, never copied, etc. But its unusual for the singleton pattern, since the user must explicitly construct it. The owner controls its lifetime.

Note that this class provides a convenient wrapper on requesting actions on the underlying service from EITEHR the process in which the service is run, or from any other process (via IPC - specific to the process service backend implementation).

This class is 'final' - since the intended use is to provide polymorphic behavior via the REP classes passed in to the CTOR.

Miscellaneous Notes: o No need for a –daemonize option for –Run-As-Service, because that's essentially what the –start command does

Example Usage

See also: Samples/SimpleService project
struct AppRep_ : Main::IApplicationRep {

AppRep_ () = default;

...

virtual void MainLoop (const std::function<void()>& startedCB) override

{

.... do your service and wait forever for thread abort

}

};

...

Sequence<String> args = Execution::ParseCommandLine (argc, argv);

Main m (make_shared<AppRep_> ());

m.Run (args);

Stroika::Frameworks::Service::Main::IApplicationRep
Definition Frameworks/Service/Main.h:529

Definition at line 149 of file Frameworks/Service/Main.h.

Member Enumeration Documentation

◆ ServiceIntegrationFeatures

enum class Stroika::Frameworks::Service::Main::ServiceIntegrationFeatures

strong

The caller COULD just call these operations and see if they fail, but the operations have side-effects. This lets the caller detect the features without the side-effects.

Definition at line 207 of file Frameworks/Service/Main.h.

◆ State

enum class Stroika::Frameworks::Service::Main::State : uint8_t

strong

Checks the state of the given service. NOTE - this works ACROSS PROCESSES. It can be called to ask in a controller exe if the serviceMain EXE is running. It also - COULD give the wrong answer - given races, so use with care.

Definition at line 240 of file Frameworks/Service/Main.h.

Constructor & Destructor Documentation

◆ Main()

Main::Main	(	const shared_ptr< IApplicationRep > &	appRep,
		const shared_ptr< IServiceIntegrationRep > &	serviceIntegrationRep = `mkDefaultServiceIntegrationRep ()`
	)

explicit

Note - besides the obvious, the Main () function also sets signal handlers to point to this objects signal handler.

Definition at line 145 of file Frameworks/Service/Main.cpp.

Member Function Documentation

◆ mkDefaultServiceIntegrationRep()

shared_ptr< Main::IServiceIntegrationRep > Main::mkDefaultServiceIntegrationRep ( )

static

The result type depends on your OS/compilation flags.

Definition at line 134 of file Frameworks/Service/Main.cpp.

◆ GetServiceIntegrationFeatures()

Containers::Set< Main::ServiceIntegrationFeatures > Stroika::Frameworks::Service::Main::GetServiceIntegrationFeatures ( ) const

The caller COULD just call these operations and see if they fail, but the operations have side-effects. This lets the caller detect the features without the side-effects.

Definition at line 32 of file Main.inl.

◆ Run()

void Main::Run	(	const CommandArgs &	args,
		const Streams::OutputStream::Ptr< Characters::Character > &	out = `nullptr`
	)

These arguments are command-line arguments. They will also be indirectly passed to the IApplicationRep. So a typical app main() might be: TBD

When this function returns, the calling main() should exit. The caller should also be prepared for exceptions to be thrown by Run - for example - in case of bad command line arguments.

Note also - some command line arguments are interpreted as meaning to send messages to another process hosing the service. While others cause this process to become the process main process, and run until told to exit.

Definition at line 158 of file Frameworks/Service/Main.cpp.

◆ GetServicePID()

pid_t Stroika::Frameworks::Service::Main::GetServicePID ( ) const

Return 0 if no service running ????

Definition at line 74 of file Main.inl.

◆ GetServiceStatusMessage()

String Main::GetServiceStatusMessage ( ) const

Return non-structured, human readable summary of service status

Definition at line 243 of file Frameworks/Service/Main.cpp.

◆ RunAsService()

void Main::RunAsService ( )

RunAsService () will not return until the service has terminated. It runs the service 'MainLoop'. When that happens, the calling application should exit.

This should NOT be called directly - except when command line arguments say "Run-As-Service".

This function / operation WILL FAIL if the service is already running (so this automatically implements protection against running multiple instances of the same service - singleton pattern.

If the startup of the service fails due to exception, it will be propagated back to the caller.

See also: RunDirectly

Definition at line 273 of file Frameworks/Service/Main.cpp.

◆ RunDirectly()

void Main::RunDirectly ( const optional< Time::Duration > & runFor = {} )

RunDirectly () is mostly a debug-handy/debug-friendly variant of RunAsService().

RunDirectly () will not return until the program has terminated. It runs the service 'MainLoop'. When that happens, the calling application should exit.

When using RunDirectly - other operations like 'status' and 'kill' etc - will NOT function. This bypasses the backend service mechanism - and just runs the application-specific code (typically so that can be debugged, but possibly also for testing or other purposes).

If the startup of the service fails due to exception, it will be propagated back to the caller.

See also: RunAsService

Definition at line 279 of file Frameworks/Service/Main.cpp.

◆ ForcedStop()

void Stroika::Frameworks::Service::Main::ForcedStop ( Time::DurationSeconds timeout )

Does a regular stop, but if that doesn't work (by the given timeout), do low-level force stop and cleanup as best as possible.

Definition at line 66 of file Main.inl.

◆ ForcedRestart()

void Main::ForcedRestart	(	Time::DurationSeconds	timeout = `Time::kInfinity`,
		Time::DurationSeconds	unforcedStopTimeout = `Time::kInfinity`
	)

Does ForcedStop(timeout) - ignoring errors if was already stopped, and then starts. This only fails if it couldn't (even forced) stop the service (ignoring timeout) or if it fails to restart the service.

Definition at line 285 of file Frameworks/Service/Main.cpp.

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

Classes

Public Types

Public Member Functions

Static Public Member Functions