Ichthyostega
8e250839f4
During the last months, a lot of gradual changes to policies and guidelines had been finalised and documented. Moreover, recent clarifications regarding memory management in the render engine will lead to a clearer definition of the »Vault« Layer's role, with some ''engine code'' expected to move down. On this occasion, I reworked relevant sections in the documentation to confirm the role that now falls to central parts of the overall architecture. Notably I decided to rename those parts related to the application backbone as »Vessel« — to underpin the more active and defining role they assumed.
83 lines
3 KiB
C++
83 lines
3 KiB
C++
/*
|
||
LIFECYCLE.hpp - interface for registering and triggering lifecycle callbacks
|
||
|
||
Copyright (C)
|
||
2008, Hermann Vosseler <Ichthyostega@web.de>
|
||
|
||
**Lumiera** is free software; you can redistribute it and/or modify it
|
||
under the terms of the GNU General Public License as published by the
|
||
Free Software Foundation; either version 2 of the License, or (at your
|
||
option) any later version. See the file COPYING for further details.
|
||
|
||
*/
|
||
|
||
/** @file lifecycle.hpp
|
||
** Installing and invoking of application lifecycle event callbacks.
|
||
** This service is a facade for and implemented by the vessel::LifecycleRegistry.
|
||
** By placing a static LifecycleHook variable or by calling LifecycleHook::add,
|
||
** a callback can be registered to be executed on a specific application lifecycle
|
||
** event. Examples being #ON_BASIC_INIT, #ON_GLOBAL_INIT. Other subsystems may
|
||
** register additional events for more specific purpose.
|
||
**
|
||
** @note the implementation resides in lib/lifecycle.cpp and gets linked into liblumiera.so
|
||
** @see vessel::Voyage
|
||
** @see main.cpp
|
||
*/
|
||
|
||
|
||
#ifndef VESSEL_LIFECYCLE_H
|
||
#define VESSEL_LIFECYCLE_H
|
||
|
||
|
||
#include "lib/symbol.hpp"
|
||
#include "lib/nocopy.hpp"
|
||
|
||
|
||
|
||
namespace vessel {
|
||
|
||
using lib::Symbol;
|
||
|
||
//defined in liblumiera.so
|
||
extern CStr ON_BASIC_INIT; ///< automatic static init. treated specially to run as soon as possible
|
||
extern CStr ON_GLOBAL_INIT; ///< to be triggered in main() @note no magic!
|
||
extern CStr ON_GLOBAL_SHUTDOWN; ///< to be triggered at the end of main() @note no magic!
|
||
|
||
extern CStr ON_EMERGENCY; ///< activated on shutdown after premature failure of a subsystem
|
||
|
||
|
||
// client code is free to register and use additional lifecycle events
|
||
|
||
|
||
|
||
/**
|
||
* define and register a callback for a specific lifecycle event.
|
||
* The purpose of this class is to be defined as a static variable in the implementation
|
||
* of some subsystem (i.e. in the cpp file), providing the ctor with the pointer to a
|
||
* callback function. Thus the specified callback gets enrolled when the corresponding
|
||
* object file is loaded. The event ON_BASIC_INIT is handled specifically, firing off the
|
||
* referred callback function as soon as possible. All other labels are just arbitrary (string)
|
||
* constants and it is necessary that "someone" cares to fire off the lifecycle events
|
||
* at the right place. For example, lumiera-main (and the test runner) calls
|
||
* \c LifecycleHook::trigger(ON_GLOBAL_INIT) (and..SHUTDOWN)
|
||
* @note duplicate or repeated calls with the same callback are NOP
|
||
*/
|
||
class LifecycleHook
|
||
: util::NonCopyable
|
||
{
|
||
public:
|
||
typedef void (*Hook)(void);
|
||
|
||
LifecycleHook (Symbol eventLabel, Hook callbackFun);
|
||
|
||
/** alternative, static interface for registering a callback */
|
||
static void add (Symbol eventLabel, Hook callbackFun);
|
||
|
||
/** trigger lifecycle callbacks registered under the given label */
|
||
static void trigger (Symbol eventLabel);
|
||
};
|
||
|
||
|
||
|
||
} // namespace vessel
|
||
#endif /*VESSEL_LIFECYCLE_H*/
|