Implements a graceful shutdown procedure for an application. More...

#include <process_anchor.h>

Inheritance diagram for process_anchor:

[legend]

Collaboration diagram for process_anchor:

[legend]

Public Member Functions
	process_anchor ()
	constructor does very little; setup() begins operation. More...

virtual	~process_anchor ()

	DEFINE_CLASS_NAME ("process_anchor")

bool	defunct () const
	returns true if the object has been marked as defunct. More...

void	set_defunct ()
	used by the derived class to mark that this object is about to exit. More...

bool	setup (application_instance handle, const basis::astring &application_name, int timing_cycle=0)
	constructs a process_anchor for the "application_name" specified. More...

void	register_anchor (window_handle anchor)
	this supports the anchor being created elsewhere. More...

virtual void	handle_startup ()
	derived classes can override this to catch the application startup. More...

virtual void	handle_timer ()
	invoked periodically if the anchor was setup() with a timer "cycle". More...

virtual void	handle_shutdown ()
	invoked just prior to the shutdown of this anchor. More...

Public Member Functions inherited from shutdown_alerter
	shutdown_alerter ()
	constructor does very little; setup() is what begins operation. More...

virtual	~shutdown_alerter ()

	DEFINE_CLASS_NAME ("shutdown_alerter")

bool	setup (const basis::astring &app_name, int timer_period=0)
	constructs a shutdown_alerter for the "app_name" specified. More...

bool	saw_interrupt ()
	reports whether the process saw an interrupt from the user. More...

Static Public Member Functions
static bool	close_this_program ()
	causes this particular program to shut down. More...

static bool	close_app_anchor (const basis::astring &app_name)
	closes the anchor object associated with "app_name". More...

static bool	launch (process_anchor &anchor, application_instance handle, const basis::astring &app, int cycle=0)
	establishes a process_anchor for the program named "app". More...

static basis::astring	make_well_known_title (const basis::astring &application_name)
	returns the string form of the well-known window title for the process_anchor. More...

static basis::astring	make_well_known_class (const basis::astring &application_name)
	same as above but for the anchor's class name. More...

Static Public Member Functions inherited from shutdown_alerter
static bool	is_defunct ()
	returns true if the object has been marked as defunct. More...

static void	set_defunct ()
	used by the derived class to mark that this object is about to exit. More...

static bool	launch_console (shutdown_alerter &alert, const basis::astring &app_name, int timer_period=0)
	this is used to begin execution of a console mode application. More...

static void	close_this_program ()
	causes this particular application to begin shutting down. More...

static bool	close_application (const basis::astring &app_name)
	attempts to close the application named "app_name". More...

static void	handle_OS_signal (int sig_id)
	processes the signal from the OS when its time to shut down. More...

Detailed Description

Implements a graceful shutdown procedure for an application.

The advantage of the process_anchor (where it's actually a window, which is to say, under win32) is that it's hidden and has a well-known name. This allows it to be found through FindWindow to facilitate a graceful shutdown for the applications that use it. On linux, it is implemented with a shutdown_alerter object instead and is not implemented using windowing.

Definition at line 33 of file process_anchor.h.

Constructor & Destructor Documentation

◆ process_anchor()

process_anchor::process_anchor ( )

constructor does very little; setup() begins operation.

Definition at line 67 of file process_anchor.cpp.

◆ ~process_anchor()

process_anchor::~process_anchor ( )

virtual

Definition at line 83 of file process_anchor.cpp.

References NULL_POINTER, and basis::WHACK().

Member Function Documentation

◆ close_app_anchor()

bool process_anchor::close_app_anchor ( const basis::astring & app_name )

static

closes the anchor object associated with "app_name".

note that this closes ALL such anchors, so if the application had more than one instance running, they will all shut down. also note: the above doesn't seem to be implemented in the current version.

Definition at line 144 of file process_anchor.cpp.

References shutdown_alerter::close_application(), FUNCDEF, LOG, make_well_known_title(), and NULL_POINTER.

◆ close_this_program()

bool process_anchor::close_this_program ( )

static

causes this particular program to shut down.

this method is available for programs that support the graceful shutdown process. it causes the machinery of the process_anchor to alert the application that a graceful shutdown has been started. the method returns true if this program's process_anchor was found and sent the close message.

Definition at line 106 of file process_anchor.cpp.

References shutdown_alerter::close_this_program(), and NULL_POINTER.

◆ DEFINE_CLASS_NAME()

process_anchor::DEFINE_CLASS_NAME ( "process_anchor" )

◆ defunct()

bool process_anchor::defunct ( ) const

returns true if the object has been marked as defunct.

this means that it is either shutting down or soon will be.

Definition at line 124 of file process_anchor.cpp.

References shutdown_alerter::is_defunct().

◆ handle_shutdown()

void process_anchor::handle_shutdown ( )

virtual

invoked just prior to the shutdown of this anchor.

Reimplemented from shutdown_alerter.

Definition at line 104 of file process_anchor.cpp.

◆ handle_startup()

void process_anchor::handle_startup ( )

virtual

derived classes can override this to catch the application startup.

this function is guaranteed to be called after the event processing loop has started, but before much of anything else is done in the application.

Reimplemented from shutdown_alerter.

Definition at line 100 of file process_anchor.cpp.

◆ handle_timer()

void process_anchor::handle_timer ( )

virtual

invoked periodically if the anchor was setup() with a timer "cycle".

Reimplemented from shutdown_alerter.

Definition at line 102 of file process_anchor.cpp.

◆ launch()

bool process_anchor::launch	(	process_anchor &	anchor,
		application_instance	handle,
		const basis::astring &	app,
		int	cycle = `0`
	)

static

establishes a process_anchor for the program named "app".

on windows, this function will not return until WM_CLOSE is received; it is the main message loop for a simple application. the "handle" parameter should be coming from the main function for the program. note that the "window" should be constructed but not have any functions called on it yet. this is important since this function does all the setup. using a "window" derived from process_anchor is also okay. the "cycle" is passed to the setup() method.

Definition at line 339 of file process_anchor.cpp.

References shutdown_alerter::launch_console(), NULL_POINTER, and setup().

◆ make_well_known_class()

static basis::astring process_anchor::make_well_known_class ( const basis::astring & application_name )

static

same as above but for the anchor's class name.

◆ make_well_known_title()

static basis::astring process_anchor::make_well_known_title ( const basis::astring & application_name )

static

returns the string form of the well-known window title for the process_anchor.

this title identifies the "application_name" on ms-windows and is used for our hidden window. this is how the window can be found at runtime. note that this approach will only work properly if there is only one window by that name on a host at a time (due to how the windows are registered).

Referenced by close_app_anchor().

◆ register_anchor()

void process_anchor::register_anchor ( window_handle anchor )

this supports the anchor being created elsewhere.

when the object is created independently but should still function as an process_anchor, then this method can be used to hook in that external "window" into our support. this only makes sense for the windows version.

Definition at line 218 of file process_anchor.cpp.

◆ set_defunct()

void process_anchor::set_defunct ( )

used by the derived class to mark that this object is about to exit.

Definition at line 134 of file process_anchor.cpp.

References shutdown_alerter::set_defunct().

◆ setup()

bool process_anchor::setup	(	application_instance	handle,
		const basis::astring &	application_name,
		int	timing_cycle = `0`
	)

constructs a process_anchor for the "application_name" specified.

the instance "handle" is the link to the application. the anchor is created (and made hidden on windows) if successful. the standard here for the "application_name" is that it should not have any directory components, but it should be the full program name (including extension). if "timing_cycle" is non-zero, then it is used as a timer interval. every time the interval elapses, the handle_timer() method is invoked. note that this function is invoked by launch() and does not need to be called by a user unless launch() is not being used to control the anchor's lifetime.

Definition at line 190 of file process_anchor.cpp.

References NULL_POINTER, and shutdown_alerter::setup().

Referenced by launch().

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

/opt/feistymeow.org/feisty_meow/nucleus/library/processes/process_anchor.h
/opt/feistymeow.org/feisty_meow/nucleus/library/processes/process_anchor.cpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ process_anchor()

◆ ~process_anchor()

Member Function Documentation

◆ close_app_anchor()

◆ close_this_program()

◆ DEFINE_CLASS_NAME()

◆ defunct()

◆ handle_shutdown()

◆ handle_startup()

◆ handle_timer()

◆ launch()

◆ make_well_known_class()

◆ make_well_known_title()

◆ register_anchor()

◆ set_defunct()

◆ setup()