onSignal
virtual void onSignal(int signal);Receives a signal forwarded by CProgram in ordinary thread context. Override this to customize handling; the default implementation exits for signals classified as fatal.
Essentials
CProgram
Application options, configuration, signals, and process-wide lifecycle helpers.
#include <mc/CProgram.h>Register options before constructing CProgram. Configuration is process-wide, and cArgs() exposes the resolved arguments.
The default program name comes from the resolved executable path, so configuration selection follows the actual binary. MC_HOME selects the framework home directory.
Jump to a declaration · 29
cArgs
cExit
cHome
cOption
CProgram
CProgram::args
CProgram::configure
CProgram::CProgram
CProgram::delegate
CProgram::exit
CProgram::ExitFunc
CProgram::handleSignal
CProgram::home
CProgram::isFatal
CProgram::onExit
CProgram::option
CProgram::parseArgs
CProgram::setDelegate
CProgram::setUsage
CProgram::signalName
CProgram::stackTrace
CProgram::threads
CProgram::usage
CProgramDelegate
CProgramDelegate::onSignal
cReconfigure
cSetUsage
cThreads
cUsage
CProgramDelegate
class CProgramDelegateMethods
CProgram
class CProgramTypes, constants & data
using ExitFunc = std::function<void(void)>;Methods
CProgram
Initializes process-wide arguments, configuration, and signal handling. Register options first; constructing a second program instance raises CError.
setDelegate
static void setDelegate(CProgramDelegate* delegate);Installs a borrowed signal delegate; nullptr restores the default delegate. Replacement is synchronized with dispatch, so keep the delegate alive until it is safely replaced.
delegate
static CProgramDelegate* delegate();Returns the current borrowed signal delegate. Retrieving the pointer does not extend its lifetime.
args
static const cvar& args();Returns the resolved, process-wide argument/configuration value. The reference is borrowed; coordinate access with reconfiguration, which replaces its contents.
configure
static void configure();Loads and resolves the program configuration using the current process-wide arguments.
option
static void option(const cstr& names, const cvar& def, const cstr& description = "", bool required = false, bool multi = false);Registers option aliases separated by :. The default determines value conversion; required and multi control validation and repeated values.
parseArgs
static cvar parseArgs(int argc, char** argv);Parses arguments using registered options. Program options use one hyphen, such as -out; double-hyphen arguments select framework configuration.
exit
static void exit(int status);Runs coordinated resource shutdown and registered exit callbacks, then terminates with the supplied status. This function does not return.
isFatal
static bool isFatal(int signal);Reports whether the signal is in Catalyst’s terminating-signal classification. It does not indicate that every such signal can be intercepted by the program.
signalName
static cstr signalName(int signal);Returns the symbolic signal name, such as SIGTERM, or a numeric description for an unknown signal.
setUsage
static void setUsage(const cstr& usage);Sets the introductory usage text. usage() appends the registered option descriptions and defaults.
usage
static cstr usage();Builds usage text from the program name, custom introduction, and registered options. It returns text rather than printing or exiting.
home
static const cstr& home();Returns the resolved framework home directory after initialization, including any MC_HOME selection.
threads
static const size_t threads();Returns the process-wide worker-count default derived from the available hardware, with at least one thread.
stackTrace
static cstr stackTrace();Captures a formatted stack trace of the calling thread. This is a current trace, unlike a trace retained by an earlier CError.
handleSignal
static void handleSignal(int signal);Dispatches a signal to the current delegate in ordinary thread context. It is not an async-signal-safe POSIX signal handler; an escaping delegate exception triggers controlled exit.
onExit
static void onExit(ExitFunc f);Registers a callback for controlled program exit.
Free functions & types
Functions
cOption
inline void cOption(const cstr& names, const cvar& def, const cstr& description = "", bool required = false, bool multi = false);Convenience wrapper for CProgram::option(), written .option(...) in Cosmic. Register options before constructing CProgram. Registers option aliases separated by :. The default determines value conversion; required and multi control validation and repeated values.
cExit
inline void cExit(int status);Convenience wrapper for CProgram::exit(). Runs coordinated resource shutdown and registered exit callbacks, then terminates with the supplied status. This function does not return.
cSetUsage
inline void cSetUsage(const cstr& usage);Convenience wrapper for CProgram::setUsage(). Sets the introductory usage text. usage() appends the registered option descriptions and defaults.
cUsage
inline cstr cUsage();Convenience wrapper for CProgram::usage(). Builds usage text from the program name, custom introduction, and registered options. It returns text rather than printing or exiting.
cHome
inline const cstr& cHome();Convenience wrapper for CProgram::home(). Returns the resolved framework home directory after initialization, including any MC_HOME selection.
cThreads
inline size_t cThreads();Convenience wrapper for CProgram::threads(). Returns the process-wide worker-count default derived from the available hardware, with at least one thread.
cArgs
inline const cvar& cArgs();Convenience wrapper for CProgram::args(), written .args() in Cosmic. Returns the resolved, process-wide argument/configuration value. The reference is borrowed; coordinate access with reconfiguration, which replaces its contents.
cReconfigure
inline void cReconfigure();Convenience wrapper for CProgram::configure(). Loads and resolves the program configuration using the current process-wide arguments.