module_init.cpp File Reference

#include "precompiled.h"
#include "lib/module_init.h"
#include "lib/sysdep/cpu.h"

Include dependency graph for module_init.cpp:

Functions
Status	ModuleInit (volatile ModuleInitState *initState, Status(*init)())
	calls a user-defined init function if initState is zero. More...
Status	ModuleShutdown (volatile ModuleInitState *initState, void(*shutdown)())
	calls a user-defined shutdown function if initState is "initialized". More...

Variables
static const Status	UNINITIALIZED = 0
static const Status	BUSY = ERR::AGAIN
static const Status	INITIALIZED = INFO::SKIPPED

Function Documentation

ModuleInit()

Status ModuleInit	(	volatile ModuleInitState *	initState,
		Status(*)()	init
	)

calls a user-defined init function if initState is zero.

Returns

INFO::SKIPPED if already initialized, a Status if the previous invocation failed, or the value returned by the callback.

postcondition: initState is "initialized" if the callback returned INFO::OK, otherwise its Status return value (which prevents shutdown from being called).

thread-safe: subsequent callers spin until the callback returns (this prevents using partially-initialized modules)

note that callbacks typically reference static data and thus do not require a function argument, but that can later be added if necessary.

ModuleShutdown()

Status ModuleShutdown	(	volatile ModuleInitState *	initState,
		void(*)()	shutdown
	)

calls a user-defined shutdown function if initState is "initialized".

Returns

INFO::OK if shutdown occurred, INFO::SKIPPED if initState was zero (uninitialized), otherwise the Status returned by ModuleInit.

postcondition: initState remains set to the Status, or has been reset to zero to allow multiple init/shutdown pairs, e.g. in self-tests.

note: there is no provision for reference-counting because that turns out to be problematic (a user might call shutdown immediately after init; if this is the first use of the module, it will be shutdown prematurely, which is at least inefficient and possibly dangerous). instead, shutdown should only be called when cleanup is necessary (e.g. at exit before leak reporting) and it is certain that the module is no longer in use.

Variable Documentation

BUSY

const Status BUSY = ERR::AGAIN

static

INITIALIZED

const Status INITIALIZED = INFO::SKIPPED

static

UNINITIALIZED

const Status UNINITIALIZED = 0

static