PSC_Service Class Reference

A main service loop. More...

#include <poser/core/service.h>

Static Public Member Functions
PSC_Event *	PSC_Service_readyRead (void)
	A file descriptor is ready for reading.
PSC_Event *	PSC_Service_readyWrite (void)
	A file descriptor is ready for writing.
PSC_Event *	PSC_Service_prestartup (void)
	The service is about to start.
PSC_Event *	PSC_Service_startup (void)
	The service started.
PSC_Event *	PSC_Service_shutdown (void)
	The service is shutting down.
PSC_Event *	PSC_Service_tick (void)
	The timer ticks.
PSC_Event *	PSC_Service_eventsDone (void)
	All events for one loop iteration are processed.
void	PSC_Service_registerRead (int id)
	Register a file descriptor for read monitoring.
void	PSC_Service_unregisterRead (int id)
	Unregister a file descriptor for read monitoring.
void	PSC_Service_registerWrite (int id)
	Register a file descriptor for write monitoring.
void	PSC_Service_unregisterWrite (int id)
	Unregister a file descriptor for write monitoring.
void	PSC_Service_registerPanic (PSC_PanicHandler handler)
	Register a panic handler.
void	PSC_Service_unregisterPanic (PSC_PanicHandler handler)
	Unregister a panic handler.
int	PSC_Service_setTickInterval (unsigned msec)
	Set the timer tick interval.
int	PSC_Service_loop (void)
	Run the service loop.
int	PSC_Service_run (void)
	Run the service.
void	PSC_Service_quit (void)
	Request the service to quit.
void	PSC_Service_shutdownLock (void)
	Delay shutdown of the service.
void	PSC_Service_shutdownUnlock (void)
	Allow shutdown to continue.
void	PSC_Service_panic (const char *msg)
	Trigger a service panic.

Detailed Description

A main service loop.

This class provides a service loop monitoring a set of file descriptors using the classic POSIX pselect() API. Therefore it is not suitable for thousands of concurrent clients. It is designed for portability with few dependencies and will work fine with up to a few hundred file descriptors.

Status changes on file descriptors are published as events. It also offers a configurable periodic "tick" event and handles standard signals (SIGINT and SIGTERM) for termination.

Finally, there's a panic function to quickly exit the loop and still give a chance for some (minimal) cleanup.

Member Function Documentation

PSC_Service_eventsDone()

PSC_Event * PSC_Service_eventsDone ( void  )

static

All events for one loop iteration are processed.

This event fires once per loop iteration. It can be used to delay an action until all events for the current iteration were processed.

PSC_Service_loop()

int PSC_Service_loop ( void  )

static

Run the service loop.

This runs the plain service loop. Callers are responsible to initialize a PSC_ThreadPool if needed, to call PSC_Daemon_run() if needed, to configure logging, etc. Use this if you need some custom setup. Otherwise, see PSC_Service_run().

Returns

an exit code

PSC_Service_panic()

void PSC_Service_panic ( const char *  msg )

static

Trigger a service panic.

A panic will jump directly back to the service loop and exit it immediately. Registered panic handlers are called and basic cleanup is attempted.

Parameters

msg	the panic message, will be logged at PSC_L_FATAL level

PSC_Service_prestartup()

PSC_Event * PSC_Service_prestartup ( void  )

static

The service is about to start.

This event fires early in the startup process. Especially, it fires before any attempt to switch to a different user. Therefore, it is recommended to use it to create TCP servers. This will allow to use low port numbers for listening when launched as the superuser (root).

A PSC_EAStartup object is passed as the event args. Startup can be aborted by setting a non-0 return code on it.

PSC_Service_quit()

void PSC_Service_quit ( void  )

static

Request the service to quit.

Once all events of the current loop iteration are processed, the service loop will exit cleanly.

PSC_Service_readyRead()

PSC_Event * PSC_Service_readyRead ( void  )

static

A file descriptor is ready for reading.

The file descriptor is used as the id of the event, so handlers must be registered using the file descriptor of interest as the id. A pointer to the id is also passed as the event arguments.

PSC_Service_readyWrite()

PSC_Event * PSC_Service_readyWrite ( void  )

static

A file descriptor is ready for writing.

The file descriptor is used as the id of the event, so handlers must be registered using the file descriptor of interest as the id. A pointer to the id is also passed as the event arguments.

PSC_Service_registerPanic()

void PSC_Service_registerPanic ( PSC_PanicHandler  handler )

static

Register a panic handler.

When PSC_Service_panic() is called, the registered handlers are called before exiting the service loop.

Parameters

handler

the panic handler

PSC_Service_registerRead()

void PSC_Service_registerRead ( int  id )

static

Register a file descriptor for read monitoring.

For a file descriptor registered for read monitoring, a PSC_Service_readyRead() event will be created when it's ready to read.

Parameters

id	the file descriptor to monitor

PSC_Service_registerWrite()

void PSC_Service_registerWrite ( int  id )

static

Register a file descriptor for write monitoring.

For a file descriptor registered for write monitoring, a PSC_Service_readyWrite() event will be created when it's ready to write.

Parameters

id	the file descriptor to monitor

PSC_Service_run()

int PSC_Service_run ( void  )

static

Run the service.

This automates everything needed for the service and runs the service loop. For configuration, see PSC_RunOpts. It will typically be called at the end of a main() function, after doing some configuration.

Returns

an exit code

PSC_Service_setTickInterval()

int PSC_Service_setTickInterval ( unsigned  msec )

static

Set the timer tick interval.

This sets the interval at which PSC_Service_tick() events are fired. The default is 1000ms (1 second).

Parameters

msec	tick interval in milliseconds

Returns

0 on success, -1 on error

PSC_Service_shutdown()

PSC_Event * PSC_Service_shutdown ( void  )

static

The service is shutting down.

This event fires when the service starts to shut down. Any cleanup should be done here.

Note you can delay the shutdown by calling PSC_Service_shutdownLock() if you need to do some asynchronous cleanup work.

PSC_Service_shutdownLock()

void PSC_Service_shutdownLock ( void  )

static

Delay shutdown of the service.

To be used from the PSC_Service_shutdown() event, in case some asynchronous cleanup work has to be done that needs the service loop active.

Service shutdown will be delayed until PSC_Service_shutdownUnlock() was called the same amount of times as PSC_Service_shutdownLock().

PSC_Service_shutdownUnlock()

void PSC_Service_shutdownUnlock ( void  )

static

Allow shutdown to continue.

See PSC_Service_shutdownLock()

PSC_Service_startup()

PSC_Event * PSC_Service_startup ( void  )

static

The service started.

This event fires after all other startup completed successfully. It can be useful for any late initialization work. If you don't use PSC_Service_run(), you might want to reconfigure logging here and call Daemon_launched().

A PSC_EAStartup object is passed as the event args. Startup can be aborted by setting a non-0 return code on it.

PSC_Service_tick()

PSC_Event * PSC_Service_tick ( void  )

static

The timer ticks.

This event fires periodically, by default once per second. Call PSC_Service_setTickInterval() to change that.

PSC_Service_unregisterPanic()

void PSC_Service_unregisterPanic ( PSC_PanicHandler  handler )

static

Unregister a panic handler.

The given handler is no longer called on a PSC_Service_panic().

Parameters

handler

the panic handler

PSC_Service_unregisterRead()

void PSC_Service_unregisterRead ( int  id )

static

Unregister a file descriptor for read monitoring.

PSC_Service_readyRead() events will no longer be created for the given file descriptor.

Parameters

id	the file descriptor

PSC_Service_unregisterWrite()

void PSC_Service_unregisterWrite ( int  id )

static

Unregister a file descriptor for write monitoring.

PSC_Service_readyWrite() events will no longer be created for the given file descriptor.

Parameters

id	the file descriptor

---

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

• poser/core/service.h