The base-class for MagAO-X applications. More...

#include <MagAOXApp.hpp>

Inheritance diagram for MagAOX::app::MagAOXApp< _useINDI >:

Collaboration diagram for MagAOX::app::MagAOXApp< _useINDI >:

Classes
struct	indiCallBack
	Structure to hold the call-back details for handling INDI communications. More...

Public Types
typedef logger::logManager< logFileRaw >	logManagerT
	The log manager type. More...

Public Member Functions
	MagAOXApp (const std::string &git_sha1, const bool git_modified)
	Public c'tor. Handles uid, logs git repo status, and initializes static members. More...

	~MagAOXApp () noexcept(true)

virtual void	setDefaults (int argc, char **argv)
	Set the paths for config files. More...

virtual void	setupBasicConfig ()
	The basic MagAO-X configuration setup method. Should not normally be overridden. More...

virtual void	loadBasicConfig ()
	The basic MagAO-X configuration processing method. Should not normally be overridden. More...

virtual int	execute ()
	The execute method implementing the standard main loop. Should not normally be overridden. More...

Pure Virtual Functions
Derived applications must implement these.
virtual int	appStartup ()=0
	Any tasks to perform prior to the main event loop go here. More...

virtual int	appLogic ()=0
	This is where derived applications implement their main FSM logic. More...

virtual int	appShutdown ()=0
	Any tasks to perform after main loop exit go here. More...

Member Accessors
std::string	configName ()
	Get the config name. More...

std::string	driverInName ()
	Get the INDI input FIFO file name. More...

std::string	driverOutName ()
	Get the INDI output FIFO file name. More...

std::string	driverCtrlName ()
	Get the INDI control FIFO file name. More...

Protected Attributes
std::string	MagAOXPath
	The base path of the MagAO-X system. More...

std::string	m_configName
	The name of the configuration file (minus .conf). More...

std::string	sysPath
	The path to the system directory, for PID file, etc. More...

std::string	secretsPath
	Path to the secrets directory, where passwords, etc, are stored. More...

unsigned long	loopPause {MAGAOX_default_loopPause}
	The time in nanoseconds to pause the main loop. The appLogic() function of the derived class is called every loopPause nanoseconds. Default is 1,000,000,000 ns. Config with loopPause=X. More...

int	m_shutdown {0}
	Flag to signal it's time to shutdown. When not 0, the main loop exits. More...

Private Member Functions
	MagAOXApp ()=delete
	Default c'tor is deleted. More...

Logging
static logManagerT	m_log

template<typename logT , int retval = 0>
static int	log (const typename logT::messageT &msg, logPrioT level=logPrio::LOG_DEFAULT)
	Make a log entry. More...

template<typename logT , int retval = 0>
static int	log (logPrioT level=logPrio::LOG_DEFAULT)
	Make a log entry. More...

Signal Handling
static MagAOXApp *	m_self = nullptr
	Static pointer to this (set in constructor). Used to test whether a a MagAOXApp is already instatiated (a fatal error) and used for getting out of static signal handlers. More...

int	setSigTermHandler ()
	Sets the handler for SIGTERM, SIGQUIT, and SIGINT. More...

void	handlerSigTerm (int signum, siginfo_t siginf, void ucont)
	Handles SIGTERM, SIGQUIT, and SIGINT. Sets m_shutdown to 1 and logs the signal. More...

static void	_handlerSigTerm (int signum, siginfo_t siginf, void ucont)
	The handler called when SIGTERM, SIGQUIT, or SIGINT is received. Just a wrapper for handlerSigTerm. More...

Privilege Management
uid_t	m_euidReal
	The real user id of the proces (i.e. the lower privileged id of the user) More...

uid_t	m_euidCalled
	The user id of the process as called (i.e. the higher privileged id of the owner, root if setuid). More...

uid_t	m_suid
	The save-set user id of the process. More...

int	euidCalled ()
	Set the effective user ID to the called value, i.e. the highest possible. More...

int	euidReal ()
	Set the effective user ID to the real value, i.e. the file owner. More...

RT Priority
int	m_RTPriority {0}
	The real-time scheduling priority. Default is 0. More...

int	RTPriority (int prio)
	Set the real-time priority of this process. More...

PID Locking
Each MagAOXApp has a PID lock file in the system directory. The app will not startup if it detects that the PID is already locked, preventing duplicates. This is based on the configured name, not the invoked name (argv[0]).
std::string	pidFileName
	The name of the PID file. More...

pid_t	m_pid {0}
	This process's PID. More...

int	lockPID ()
	Attempt to lock the PID by writing it to a file. Fails if a process is already running with the same config name. More...

int	unlockPID ()
	Remove the PID file. More...

Application State
stateCodes::stateCodeT	m_state {stateCodes::UNINITIALIZED}
	The application's state. Never ever set this directly, use state(const stateCodeT & s). More...

int	m_stateLogged {0}
	Counter and flag for use to log errors just once. Never ever access directly, use stateLogged(). More...

stateCodes::stateCodeT	state ()
	Get the current state code. More...

void	state (const stateCodes::stateCodeT &s)
	Set the current state code. More...

int	stateLogged ()
	Updates and returns the value of m_stateLogged. Will be 0 on first call after a state change, >0 afterwards. More...

INDI Interface
For reference: "Get" and "New" refer to properties we own. "Set" refers to properties owned by others. So we respond to GetProperties by listing our own properties, and NewProperty is a request to change a property we own. Whereas SetProperty is a notification that someone else has changed a property.
typedef std::pair< std::string, indiCallBack >	callBackValueType
	Value type of the indiCallBack map. More...

typedef std::unordered_map< std::string, indiCallBack >::iterator	callBackIterator
	Iterator type of the indiCallBack map. More...

typedef std::pair< callBackIterator, bool >	callBackInsertResult
	Return type of insert on the indiCallBack map. More...

indiDriver< MagAOXApp > *	m_indiDriver {nullptr}
	The INDI driver wrapper. Constructed and initialized by execute, which starts and stops communications. More...

std::mutex	m_indiMutex
	Mutex for locking INDI communications. More...

std::unordered_map< std::string, indiCallBack >	m_indiNewCallBacks
	Map to hold the NewProperty indiCallBacks for this App, with fast lookup by property name. More...

std::unordered_map< std::string, indiCallBack >	m_indiSetCallBacks
	Map to hold the SetProperty indiCallBacks for this App, with fast lookup by property name. More...

bool	m_allDefsReceived {false}
	Flat indicating that all registered Set properties have been updated since last Get. More...

std::string	m_driverInName
	Full path name of the INDI driver input FIFO. More...

std::string	m_driverOutName
	Full path name of the INDI driver output FIFO. More...

std::string	m_driverCtrlName
	Full path name of the INDI driver control FIFO. More...

pcf::IndiProperty	m_indiP_state
	indi Property to report the application state. More...

static constexpr bool	m_useINDI = _useINDI
	Flag controlling whether INDI is used. If false, then no INDI code ipRecv.getName()executes. More...

void	sendGetPropertySetList (bool all=false)

void	handleDefProperty (const pcf::IndiProperty &ipRecv)
	Handler for the DEF INDI properties notification. More...

void	handleGetProperties (const pcf::IndiProperty &ipRecv)
	Handler for the get INDI properties request. More...

void	handleNewProperty (const pcf::IndiProperty &ipRecv)
	Handler for the new INDI property request. More...

void	handleSetProperty (const pcf::IndiProperty &ipRecv)
	Handler for the set INDI property request. More...

int	registerIndiPropertyNew (pcf::IndiProperty &prop, const std::string &propName, const pcf::IndiProperty::Type &propType, const pcf::IndiProperty::PropertyPermType &propPerm, const pcf::IndiProperty::PropertyStateType &propState, int()(void , const pcf::IndiProperty &))
	Register an INDI property which is exposed for others to request a New Property for. More...

int	registerIndiPropertySet (pcf::IndiProperty &prop, const std::string &devName, const std::string &propName, int()(void , const pcf::IndiProperty &))
	Register an INDI property which is monitored for updates from others. More...

int	createINDIFIFOS ()
	Create the INDI FIFOs. More...

int	startINDI ()
	Start INDI Communications. More...

template<typename T >
void	updateIfChanged (pcf::IndiProperty &p, const std::string &el, const T &newVal)
	Update an INDI property element value if it has changed. More...

template<typename T >
int	sendNewProperty (const pcf::IndiProperty &ipSend, const std::string &el, const T &newVal)
	Send a newProperty command to another device (using the INDI Client interface) More...

Power Management
For devices which have remote power management (e.g. from one of the PDUs) we implement a standard power state monitoring and management component for the FSM. This is only enabled if the power management configuration options are set. If power management is enabled, then while power is off, appLogic will not be called. Instead a parrallel set of virtual functions is called, onPowerOff (to allow apps to perform cleanup) and whilePowerOff (to allow apps to keep variables updated, etc). Note that these could merely call appLogic if desired.
bool	m_powerMgtEnabled {false}

std::string	m_powerDevice

std::string	m_powerOutlet

std::string	m_powerElement {"state"}

int	m_powerState {-1}
	Current power state, 1=On, 0=Off, -1=Unk. More...

pcf::IndiProperty	m_indiP_powerOutlet

	INDI_SETCALLBACK_DECL (MagAOXApp, m_indiP_powerOutlet)

virtual int	onPowerOff ()
	This method is called when the change to poweroff is detected. More...

virtual int	whilePowerOff ()
	This method is called while the power is off, once per FSM loop. More...

Detailed Description

template<bool _useINDI = true>
class MagAOX::app::MagAOXApp< _useINDI >

The base-class for MagAO-X applications.

You can define a base configuration file for this class by writing

#define MAGAOX_configBase "relative/path/from/configDir.conf"

before including MagAOXApp.hpp. This would be used, for instance to have a config common to all filter wheels.

Todo:: do we need libMagAOX error handling? (a stack?)

Definition at line 68 of file MagAOXApp.hpp.

Member Typedef Documentation

◆ callBackInsertResult

template<bool _useINDI = true>

typedef std::pair<callBackIterator,bool> MagAOX::app::MagAOXApp< _useINDI >::callBackInsertResult

protected

Return type of insert on the indiCallBack map.

Definition at line 416 of file MagAOXApp.hpp.

◆ callBackIterator

template<bool _useINDI = true>

typedef std::unordered_map<std::string, indiCallBack>::iterator MagAOX::app::MagAOXApp< _useINDI >::callBackIterator

protected

Iterator type of the indiCallBack map.

Definition at line 413 of file MagAOXApp.hpp.

◆ callBackValueType

template<bool _useINDI = true>

typedef std::pair<std::string, indiCallBack> MagAOX::app::MagAOXApp< _useINDI >::callBackValueType

protected

Value type of the indiCallBack map.

Definition at line 410 of file MagAOXApp.hpp.

◆ logManagerT

template<bool _useINDI = true>

typedef logger::logManager<logFileRaw> MagAOX::app::MagAOXApp< _useINDI >::logManagerT

The log manager type.

Definition at line 74 of file MagAOXApp.hpp.

Constructor & Destructor Documentation

◆ MagAOXApp() [1/2]

template<bool _useINDI = true>

MagAOX::app::MagAOXApp< _useINDI >::MagAOXApp ( )

privatedelete

Default c'tor is deleted.

◆ MagAOXApp() [2/2]

template<bool _useINDI>

MagAOX::app::MagAOXApp< _useINDI >::MagAOXApp	(	const std::string &	git_sha1,
		const bool	git_modified
	)

Public c'tor. Handles uid, logs git repo status, and initializes static members.

Only one MagAOXApp can be instantiated per program. Hence this c'tor will issue exit(-1) if the static self-pointer m_self is already initialized.

euid is set to 'real' to ensure that the application has normal privileges unless explicitly needed.

Reference: http://man7.org/linux/man-pages/man2/getresuid.2.html

The git repository status is required to create a MagAOXApp. Derived classes should include the results of running gengithead.sh and pass the defined sha1 and modified flags.

Parameters

[in]	git_sha1	The current SHA1 hash of the git repository
[in]	git_modified	Whether or not the repo is modified.

Definition at line 624 of file MagAOXApp.hpp.

◆ ~MagAOXApp()

template<bool _useINDI>

MagAOX::app::MagAOXApp< _useINDI >::~MagAOXApp ( )

noexcept

Definition at line 652 of file MagAOXApp.hpp.

Member Function Documentation

◆ _handlerSigTerm()

template<bool _useINDI>

void MagAOX::app::MagAOXApp< _useINDI >::_handlerSigTerm	(	int	signum,
		siginfo_t *	siginf,
		void *	ucont
	)

staticprivate

The handler called when SIGTERM, SIGQUIT, or SIGINT is received. Just a wrapper for handlerSigTerm.

Parameters

[in]	signum	specifies the signal.
[in]	siginf	ignored by MagAOXApp
[in]	ucont	ignored by MagAOXApp

Definition at line 1009 of file MagAOXApp.hpp.

◆ appLogic()

template<bool _useINDI = true>

virtual int MagAOX::app::MagAOXApp< _useINDI >::appLogic ( )

pure virtual

This is where derived applications implement their main FSM logic.

This will be called every loopPause nanoseconds until the application terminates.

FSM state will be whatever it is on exti from appStartup.

Should return -1 on an any unrecoverable errors which will caues app to terminate. Could also set m_shutdown=1. Return 0 on success, or at least intent to continue.

◆ appShutdown()

template<bool _useINDI = true>

virtual int MagAOX::app::MagAOXApp< _useINDI >::appShutdown ( )

pure virtual

Any tasks to perform after main loop exit go here.

Should be able to handle case where appStartup and/or appLogic have not run.

◆ appStartup()

template<bool _useINDI = true>

virtual int MagAOX::app::MagAOXApp< _useINDI >::appStartup ( )

pure virtual

Any tasks to perform prior to the main event loop go here.

This is called after signal handling is installed. FSM state is stateCodes::INITIALIZED when this is called.

Set m_shutdown = 1 on any fatal errors here.

◆ configName()

template<bool _useINDI>

std::string MagAOX::app::MagAOXApp< _useINDI >::configName ( )

Get the config name.

Returns: the current value of m_configName

Definition at line 1770 of file MagAOXApp.hpp.

◆ createINDIFIFOS()

template<bool _useINDI>

int MagAOX::app::MagAOXApp< _useINDI >::createINDIFIFOS ( )

protected

Create the INDI FIFOs.

Changes permissions to max available and creates the FIFOs at the configured path.

Todo:: make driver FIFO path full configurable.

Definition at line 1402 of file MagAOXApp.hpp.

◆ driverCtrlName()

template<bool _useINDI>

std::string MagAOX::app::MagAOXApp< _useINDI >::driverCtrlName ( )

Get the INDI control FIFO file name.

Returns: the current value of m_driverCtrlName

Definition at line 1788 of file MagAOXApp.hpp.

Referenced by MagAOX::app::indiDriver< MagAOX::app::MagAOXApp >::indiDriver().

◆ driverInName()

template<bool _useINDI>

std::string MagAOX::app::MagAOXApp< _useINDI >::driverInName ( )

Get the INDI input FIFO file name.

Returns: the current value of m_driverInName

Definition at line 1776 of file MagAOXApp.hpp.

Referenced by MagAOX::app::indiDriver< MagAOX::app::MagAOXApp >::indiDriver().

◆ driverOutName()

template<bool _useINDI>

std::string MagAOX::app::MagAOXApp< _useINDI >::driverOutName ( )

Get the INDI output FIFO file name.

Returns: the current value of m_driverOutName

Definition at line 1782 of file MagAOXApp.hpp.

Referenced by MagAOX::app::indiDriver< MagAOX::app::MagAOXApp >::indiDriver().

◆ euidCalled()

template<bool _useINDI>

int MagAOX::app::MagAOXApp< _useINDI >::euidCalled ( )

protected

Set the effective user ID to the called value, i.e. the highest possible.

If setuid is set on the file, this will be super-user privileges.

Reference: http://pubs.opengroup.org/onlinepubs/009695399/functions/seteuid.html

Returns: 0 on success; -1 on error from setuid().

Definition at line 1050 of file MagAOXApp.hpp.

◆ euidReal()

template<bool _useINDI>

int MagAOX::app::MagAOXApp< _useINDI >::euidReal ( )

protected

Set the effective user ID to the real value, i.e. the file owner.

Reference: http://pubs.opengroup.org/onlinepubs/009695399/functions/seteuid.html

Returns: 0 on success; -1 on error from setuid().

Definition at line 1069 of file MagAOXApp.hpp.

◆ execute()

template<bool _useINDI>

int MagAOX::app::MagAOXApp< _useINDI >::execute ( void )

virtual

The execute method implementing the standard main loop. Should not normally be overridden.

Todo:: Need a heartbeat update here.

Definition at line 781 of file MagAOXApp.hpp.

◆ handleDefProperty()

template<bool _useINDI>

void MagAOX::app::MagAOXApp< _useINDI >::handleDefProperty ( const pcf::IndiProperty & ipRecv )

Handler for the DEF INDI properties notification.

Uses the properties registered in m_indiSetCallBacks to process the notification. This is called by m_indiDriver's indiDriver::handleDefProperties.

Parameters

[in] ipRecv The property being sent.

Definition at line 1542 of file MagAOXApp.hpp.

◆ handleGetProperties()

template<bool _useINDI>

void MagAOX::app::MagAOXApp< _useINDI >::handleGetProperties ( const pcf::IndiProperty & ipRecv )

Handler for the get INDI properties request.

Uses the properties registered in m_indiCallBacks to respond to the request. This is called by m_indiDriver's indiDriver::handleGetProperties.

Parameters

[in] ipRecv The property being requested.

Definition at line 1548 of file MagAOXApp.hpp.

◆ handleNewProperty()

template<bool _useINDI>

void MagAOX::app::MagAOXApp< _useINDI >::handleNewProperty ( const pcf::IndiProperty & ipRecv )

Handler for the new INDI property request.

Uses the properties registered in m_indiCallBacks to respond to the request, looking up the callback for this property and calling it.

This is called by m_indiDriver's indiDriver::handleGetProperties.

Todo:: handle errors, are they FATAL?

Todo:: log invalid NewProperty request, though it probably can't get this far.

Todo:: log an error here because callBack should not be null

Parameters

[in] ipRecv The property being changed.

Definition at line 1594 of file MagAOXApp.hpp.

◆ handlerSigTerm()

template<bool _useINDI>

void MagAOX::app::MagAOXApp< _useINDI >::handlerSigTerm	(	int	signum,
		siginfo_t *	siginf,
		void *	ucont
	)

private

Handles SIGTERM, SIGQUIT, and SIGINT. Sets m_shutdown to 1 and logs the signal.

Parameters

[in]	signum	specifies the signal.
[in]	siginf	ignored by MagAOXApp
[in]	ucont	ignored by MagAOXApp

Definition at line 1018 of file MagAOXApp.hpp.

Referenced by MagAOX::app::MagAOXApp< _useINDI >::_handlerSigTerm().

◆ handleSetProperty()

template<bool _useINDI>

void MagAOX::app::MagAOXApp< _useINDI >::handleSetProperty ( const pcf::IndiProperty & ipRecv )

Handler for the set INDI property request.

This is called by m_indiDriver's indiDriver::handleSetProperties.

Todo:: handle errors, are they FATAL?

Todo:: log an error here because callBack should not be null

Todo:: log invalid SetProperty request.

Parameters

[in] ipRecv The property being changed.

Definition at line 1616 of file MagAOXApp.hpp.

◆ INDI_SETCALLBACK_DECL()

template<bool _useINDI = true>

MagAOX::app::MagAOXApp< _useINDI >::INDI_SETCALLBACK_DECL	(	MagAOXApp< _useINDI >	,
		m_indiP_powerOutlet
	)

◆ loadBasicConfig()

template<bool _useINDI>

void MagAOX::app::MagAOXApp< _useINDI >::loadBasicConfig ( )

virtual

The basic MagAO-X configuration processing method. Should not normally be overridden.

This method processes the standard MagAO-X key=value pairs.

Though it is virtual, it should not normally be overridden unless you need to depart from the MagAO-X standard.

Processing of app specific config goes in loadConfig() implemented by the derived class.

Definition at line 747 of file MagAOXApp.hpp.

◆ lockPID()

template<bool _useINDI>

int MagAOX::app::MagAOXApp< _useINDI >::lockPID ( )

protected

Attempt to lock the PID by writing it to a file. Fails if a process is already running with the same config name.

First checks the PID file for an existing PID. If found, interrogates /proc to determine if that process is running and if so if the command line matches. If a matching process is currently running, then this returns an error.

Will not fail if a PID file exists but the stored PID does not correspond to a running process with the same command line name.

Reference: https://linux.die.net/man/3/getpid

Returns: 0 on success.; -1 on any error, including creating the PID file or if this app is already running.

Definition at line 1138 of file MagAOXApp.hpp.

◆ log() [1/2]

template<bool _useINDI>

template<typename logT , int retval>

int MagAOX::app::MagAOXApp< _useINDI >::log	(	const typename logT::messageT &	msg,
		logPrioT	level = `logPrio::LOG_DEFAULT`
	)

static

Make a log entry.

Wrapper for logManager::log

Template Parameters

logT	the log entry type
retval	the value returned by this method.

Parameters

[in]	msg	the message to log
[in]	level	[optional] the log level. The default is used if not specified.

Definition at line 943 of file MagAOXApp.hpp.

◆ log() [2/2]

template<bool _useINDI>

template<typename logT , int retval>

int MagAOX::app::MagAOXApp< _useINDI >::log ( logPrioT level = logPrio::LOG_DEFAULT )

static

Make a log entry.

Wrapper for logManager::log

Template Parameters

logT	the log entry type
retval	the value returned by this method.

Parameters

[in] level [optional] the log level. The default is used if not specified.

Definition at line 953 of file MagAOXApp.hpp.

◆ onPowerOff()

template<bool _useINDI = true>

virtual int MagAOX::app::MagAOXApp< _useINDI >::onPowerOff ( )

inlineprotectedvirtual

This method is called when the change to poweroff is detected.

Returns: 0 on success.; -1 on any error which means the app should exit.

Definition at line 568 of file MagAOXApp.hpp.

◆ registerIndiPropertyNew()

template<bool _useINDI = true>

int MagAOX::app::MagAOXApp< _useINDI >::registerIndiPropertyNew	(	pcf::IndiProperty &	prop,
		const std::string &	propName,
		const pcf::IndiProperty::Type &	propType,
		const pcf::IndiProperty::PropertyPermType &	propPerm,
		const pcf::IndiProperty::PropertyStateType &	propState,
		int()(void , const pcf::IndiProperty &)
	)

protected

Register an INDI property which is exposed for others to request a New Property for.

Returns: 0 on success.; -1 on error.

Todo:

needs error logging

needs exception handling

is a failure to register a FATAL error?

Parameters

[out]	prop	the property to register
[in]	propName	the name of the property
[in]	propType	the type of the property
[in]	propPerm	the permissions of the property
[in]	propState	the state of the property

Definition at line 1351 of file MagAOXApp.hpp.

◆ registerIndiPropertySet()

template<bool _useINDI = true>

int MagAOX::app::MagAOXApp< _useINDI >::registerIndiPropertySet	(	pcf::IndiProperty &	prop,
		const std::string &	devName,
		const std::string &	propName,
		int()(void , const pcf::IndiProperty &)
	)

protected

Register an INDI property which is monitored for updates from others.

Returns: 0 on success.; -1 on error.

Todo:

needs error logging

needs exception handling

is a failure to register a FATAL error?

Parameters

[out]	prop	the property to register
[in]	devName	the device which owns this property
[in]	propName	the name of the property

Definition at line 1379 of file MagAOXApp.hpp.

◆ RTPriority()

template<bool _useINDI>

int MagAOX::app::MagAOXApp< _useINDI >::RTPriority ( int prio )

protected

Set the real-time priority of this process.

This method attempts to set euid to 'called' with euidCalled. It then sets the priority but will fail if it does not have sufficient privileges. Regardless, it will then restore privileges with euidReal.

If prio < 0, it is changed to 0. If prio is > 99, then it is changed to 99.

Returns: 0 on success.; -1 on an error. In this case priority will not have been changed.

Parameters

[in] prio the desired new RT priority

Definition at line 1089 of file MagAOXApp.hpp.

◆ sendGetPropertySetList()

template<bool _useINDI>

void MagAOX::app::MagAOXApp< _useINDI >::sendGetPropertySetList ( bool all = false )

Definition at line 1514 of file MagAOXApp.hpp.

◆ sendNewProperty()

template<bool _useINDI>

template<typename T >

int MagAOX::app::MagAOXApp< _useINDI >::sendNewProperty	(	const pcf::IndiProperty &	ipSend,
		const std::string &	el,
		const T &	newVal
	)

protected

Send a newProperty command to another device (using the INDI Client interface)

Copies the input IndiProperty, then updates the element with the new value.

Returns: 0 on success.; -1 on an errory.

Parameters

[in]	ipSend	The property to send a "new" INDI command for
[in]	el	The element of the property to change
[in]	newVal	The value to request for the element.

Definition at line 1702 of file MagAOXApp.hpp.

Referenced by MagAOX::app::MagAOXApp< _useINDI >::sendNewProperty().

◆ setDefaults()

template<bool _useINDI>

void MagAOX::app::MagAOXApp< _useINDI >::setDefaults	(	int	argc,
		char **	argv
	)

virtual

Set the paths for config files.

Replaces the mx::application defaults with the MagAO-X config system.

This function parses the CL for "-n" or "--name".

Do not override this unless you intend to depart from the MagAO-X standard.

Parameters

[in]	argc	standard command line result specifying number of arguments in argv
[in]	argv	standard command line result containing the arguments.

Definition at line 660 of file MagAOXApp.hpp.

◆ setSigTermHandler()

template<bool _useINDI>

int MagAOX::app::MagAOXApp< _useINDI >::setSigTermHandler ( )

private

Sets the handler for SIGTERM, SIGQUIT, and SIGINT.

Definition at line 960 of file MagAOXApp.hpp.

◆ setupBasicConfig()

template<bool _useINDI>

void MagAOX::app::MagAOXApp< _useINDI >::setupBasicConfig ( )

virtual

The basic MagAO-X configuration setup method. Should not normally be overridden.

This method sets up the config system with the standard MagAO-X key=value pairs.

Though it is virtual, it should not normally be overridden unless you need to depart from the MagAO-X standard.

Setting up app specific config goes in setupConfig() implemented in the derived class.

Definition at line 731 of file MagAOXApp.hpp.

◆ startINDI()

template<bool _useINDI>

int MagAOX::app::MagAOXApp< _useINDI >::startINDI ( )

protected

Start INDI Communications.

Returns: 0 on success; -1 on error. This is fatal.

Definition at line 1466 of file MagAOXApp.hpp.

◆ state() [1/2]

template<bool _useINDI>

stateCodes::stateCodeT MagAOX::app::MagAOXApp< _useINDI >::state ( )

Get the current state code.

Returns: m_state

Definition at line 1301 of file MagAOXApp.hpp.

◆ state() [2/2]

template<bool _useINDI>

void MagAOX::app::MagAOXApp< _useINDI >::state ( const stateCodes::stateCodeT & s )

Set the current state code.

If no change, returns immediately with no actions.

If it is a change, the state change is logged. Also resets m_stateLogged to 0.

Parameters

[in] s The new application state

Definition at line 1307 of file MagAOXApp.hpp.

◆ stateLogged()

template<bool _useINDI>

int MagAOX::app::MagAOXApp< _useINDI >::stateLogged ( )

Updates and returns the value of m_stateLogged. Will be 0 on first call after a state change, >0 afterwards.

This method exists to facilitate logging the reason for a state change once, but not logging it on subsequent event loops. Returns the current value upon entry, but updates before returning so that the next call returns the incremented value. Example usage:

if( connection_failed ) //some condition set this to true
{
   state( stateCodes::NOTCONNECTED );
   if(!stateLogged()) log<text_log>("Not connected");
}

In this example, the log entry is made the first time the state changes. If there are no changes to a different state in the mean time, then when the event loop gets here again and decides it is not connected, the log entry will not be made.

Returns: current value of m_stateLogged, that is the value before it is incremented.

Definition at line 1332 of file MagAOXApp.hpp.

◆ unlockPID()

template<bool _useINDI>

int MagAOX::app::MagAOXApp< _useINDI >::unlockPID ( )

protected

Remove the PID file.

Definition at line 1285 of file MagAOXApp.hpp.

◆ updateIfChanged()

template<bool _useINDI>

template<typename T >

void MagAOX::app::MagAOXApp< _useINDI >::updateIfChanged	(	pcf::IndiProperty &	p,
		const std::string &	el,
		const T &	newVal
	)

protected

Update an INDI property element value if it has changed.

Will only peform a SetProperty if the new element value has changed compared to the stored value. This comparison is done in the true type of the value.

Parameters

[in,out]	p	The property containing the element to possibly update
[in]	el	The element name
[in]	newVal	the new value

Definition at line 1644 of file MagAOXApp.hpp.

◆ whilePowerOff()

template<bool _useINDI = true>

virtual int MagAOX::app::MagAOXApp< _useINDI >::whilePowerOff ( )

inlineprotectedvirtual

This method is called while the power is off, once per FSM loop.

Returns: 0 on success.; -1 on any error which means the app should exit.

Definition at line 575 of file MagAOXApp.hpp.

Member Data Documentation

◆ loopPause

template<bool _useINDI = true>

unsigned long MagAOX::app::MagAOXApp< _useINDI >::loopPause {MAGAOX_default_loopPause}

protected

The time in nanoseconds to pause the main loop. The appLogic() function of the derived class is called every loopPause nanoseconds. Default is 1,000,000,000 ns. Config with loopPause=X.

Definition at line 86 of file MagAOXApp.hpp.

◆ m_allDefsReceived

template<bool _useINDI = true>

bool MagAOX::app::MagAOXApp< _useINDI >::m_allDefsReceived {false}

protected

Flat indicating that all registered Set properties have been updated since last Get.

Definition at line 407 of file MagAOXApp.hpp.

◆ m_configName

template<bool _useINDI = true>

std::string MagAOX::app::MagAOXApp< _useINDI >::m_configName

protected

The name of the configuration file (minus .conf).

Definition at line 80 of file MagAOXApp.hpp.

◆ m_driverCtrlName

template<bool _useINDI = true>

std::string MagAOX::app::MagAOXApp< _useINDI >::m_driverCtrlName

protected

Full path name of the INDI driver control FIFO.

This is currently only used to signal restarts.

Definition at line 427 of file MagAOXApp.hpp.

◆ m_driverInName

template<bool _useINDI = true>

std::string MagAOX::app::MagAOXApp< _useINDI >::m_driverInName

protected

Full path name of the INDI driver input FIFO.

Definition at line 419 of file MagAOXApp.hpp.

◆ m_driverOutName

template<bool _useINDI = true>

std::string MagAOX::app::MagAOXApp< _useINDI >::m_driverOutName

protected

Full path name of the INDI driver output FIFO.

Definition at line 422 of file MagAOXApp.hpp.

◆ m_euidCalled

template<bool _useINDI = true>

uid_t MagAOX::app::MagAOXApp< _useINDI >::m_euidCalled

private

The user id of the process as called (i.e. the higher privileged id of the owner, root if setuid).

Definition at line 247 of file MagAOXApp.hpp.

◆ m_euidReal

template<bool _useINDI = true>

uid_t MagAOX::app::MagAOXApp< _useINDI >::m_euidReal

private

The real user id of the proces (i.e. the lower privileged id of the user)

Definition at line 246 of file MagAOXApp.hpp.

◆ m_indiDriver

template<bool _useINDI = true>

indiDriver<MagAOXApp>* MagAOX::app::MagAOXApp< _useINDI >::m_indiDriver {nullptr}

protected

The INDI driver wrapper. Constructed and initialized by execute, which starts and stops communications.

Definition at line 383 of file MagAOXApp.hpp.

◆ m_indiMutex

template<bool _useINDI = true>

std::mutex MagAOX::app::MagAOXApp< _useINDI >::m_indiMutex

protected

Mutex for locking INDI communications.

Definition at line 386 of file MagAOXApp.hpp.

◆ m_indiNewCallBacks

template<bool _useINDI = true>

std::unordered_map< std::string, indiCallBack> MagAOX::app::MagAOXApp< _useINDI >::m_indiNewCallBacks

protected

Map to hold the NewProperty indiCallBacks for this App, with fast lookup by property name.

The key for these is the property name.

Definition at line 399 of file MagAOXApp.hpp.

◆ m_indiP_powerOutlet

template<bool _useINDI = true>

pcf::IndiProperty MagAOX::app::MagAOXApp< _useINDI >::m_indiP_powerOutlet

protected

Definition at line 561 of file MagAOXApp.hpp.

◆ m_indiP_state

template<bool _useINDI = true>

pcf::IndiProperty MagAOX::app::MagAOXApp< _useINDI >::m_indiP_state

protected

indi Property to report the application state.

Definition at line 537 of file MagAOXApp.hpp.

◆ m_indiSetCallBacks

template<bool _useINDI = true>

std::unordered_map< std::string, indiCallBack> MagAOX::app::MagAOXApp< _useINDI >::m_indiSetCallBacks

protected

Map to hold the SetProperty indiCallBacks for this App, with fast lookup by property name.

The key for these is device.name

Definition at line 404 of file MagAOXApp.hpp.

◆ m_log

template<bool _useINDI = true>

MagAOXApp< _useINDI >::logManagerT MagAOX::app::MagAOXApp< _useINDI >::m_log

static

Definition at line 192 of file MagAOXApp.hpp.

◆ m_pid

template<bool _useINDI = true>

pid_t MagAOX::app::MagAOXApp< _useINDI >::m_pid {0}

protected

This process's PID.

Definition at line 306 of file MagAOXApp.hpp.

◆ m_powerDevice

template<bool _useINDI = true>

std::string MagAOX::app::MagAOXApp< _useINDI >::m_powerDevice

protected

Definition at line 555 of file MagAOXApp.hpp.

◆ m_powerElement

template<bool _useINDI = true>

std::string MagAOX::app::MagAOXApp< _useINDI >::m_powerElement {"state"}

protected

Definition at line 557 of file MagAOXApp.hpp.

◆ m_powerMgtEnabled

template<bool _useINDI = true>

bool MagAOX::app::MagAOXApp< _useINDI >::m_powerMgtEnabled {false}

protected

Definition at line 553 of file MagAOXApp.hpp.

◆ m_powerOutlet

template<bool _useINDI = true>

std::string MagAOX::app::MagAOXApp< _useINDI >::m_powerOutlet

protected

Definition at line 556 of file MagAOXApp.hpp.

◆ m_powerState

template<bool _useINDI = true>

int MagAOX::app::MagAOXApp< _useINDI >::m_powerState {-1}

protected

Current power state, 1=On, 0=Off, -1=Unk.

Definition at line 559 of file MagAOXApp.hpp.

◆ m_RTPriority

template<bool _useINDI = true>

int MagAOX::app::MagAOXApp< _useINDI >::m_RTPriority {0}

private

The real-time scheduling priority. Default is 0.

Definition at line 278 of file MagAOXApp.hpp.

◆ m_self

template<bool _useINDI = true>

MagAOXApp< _useINDI > * MagAOX::app::MagAOXApp< _useINDI >::m_self = nullptr

staticprivate

Static pointer to this (set in constructor). Used to test whether a a MagAOXApp is already instatiated (a fatal error) and used for getting out of static signal handlers.

Definition at line 223 of file MagAOXApp.hpp.

◆ m_shutdown

template<bool _useINDI = true>

int MagAOX::app::MagAOXApp< _useINDI >::m_shutdown {0}

protected

Flag to signal it's time to shutdown. When not 0, the main loop exits.

Definition at line 88 of file MagAOXApp.hpp.

◆ m_state

template<bool _useINDI = true>

stateCodes::stateCodeT MagAOX::app::MagAOXApp< _useINDI >::m_state {stateCodes::UNINITIALIZED}

private

The application's state. Never ever set this directly, use state(const stateCodeT & s).

Definition at line 331 of file MagAOXApp.hpp.

◆ m_stateLogged

template<bool _useINDI = true>

int MagAOX::app::MagAOXApp< _useINDI >::m_stateLogged {0}

private

Counter and flag for use to log errors just once. Never ever access directly, use stateLogged().

Definition at line 333 of file MagAOXApp.hpp.

◆ m_suid

template<bool _useINDI = true>

uid_t MagAOX::app::MagAOXApp< _useINDI >::m_suid

private

The save-set user id of the process.

Definition at line 248 of file MagAOXApp.hpp.

◆ m_useINDI

template<bool _useINDI = true>

constexpr bool MagAOX::app::MagAOXApp< _useINDI >::m_useINDI = _useINDI

staticprotected

Flag controlling whether INDI is used. If false, then no INDI code ipRecv.getName()executes.

Definition at line 380 of file MagAOXApp.hpp.

◆ MagAOXPath

template<bool _useINDI = true>

std::string MagAOX::app::MagAOXApp< _useINDI >::MagAOXPath

protected

The base path of the MagAO-X system.

Definition at line 78 of file MagAOXApp.hpp.

◆ pidFileName

template<bool _useINDI = true>

std::string MagAOX::app::MagAOXApp< _useINDI >::pidFileName

protected

The name of the PID file.

Definition at line 304 of file MagAOXApp.hpp.

◆ secretsPath

template<bool _useINDI = true>

std::string MagAOX::app::MagAOXApp< _useINDI >::secretsPath

protected

Path to the secrets directory, where passwords, etc, are stored.

Definition at line 84 of file MagAOXApp.hpp.

◆ sysPath

template<bool _useINDI = true>

std::string MagAOX::app::MagAOXApp< _useINDI >::sysPath

protected

The path to the system directory, for PID file, etc.

Definition at line 82 of file MagAOXApp.hpp.

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

/home/jrmales/Source/MagAOX/libMagAOX/app/MagAOXApp.hpp

Classes

Public Types

Public Member Functions

Protected Attributes

Private Member Functions

Logging

Signal Handling

Privilege Management

RT Priority

PID Locking

Application State

INDI Interface

Power Management

Detailed Description

template<bool _useINDI = true> class MagAOX::app::MagAOXApp< _useINDI >

Member Typedef Documentation

◆ callBackInsertResult

◆ callBackIterator

◆ callBackValueType

◆ logManagerT

Constructor & Destructor Documentation

◆ MagAOXApp() [1/2]

◆ MagAOXApp() [2/2]

◆ ~MagAOXApp()

Member Function Documentation

◆ _handlerSigTerm()

◆ appLogic()

◆ appShutdown()

◆ appStartup()

◆ configName()

◆ createINDIFIFOS()

◆ driverCtrlName()

◆ driverInName()

◆ driverOutName()

◆ euidCalled()

◆ euidReal()

◆ execute()

◆ handleDefProperty()

◆ handleGetProperties()

◆ handleNewProperty()

◆ handlerSigTerm()

◆ handleSetProperty()

◆ INDI_SETCALLBACK_DECL()

◆ loadBasicConfig()

◆ lockPID()

◆ log() [1/2]

◆ log() [2/2]

◆ onPowerOff()

◆ registerIndiPropertyNew()

◆ registerIndiPropertySet()

◆ RTPriority()

◆ sendGetPropertySetList()

◆ sendNewProperty()

◆ setDefaults()

◆ setSigTermHandler()

◆ setupBasicConfig()

◆ startINDI()

◆ state() [1/2]

◆ state() [2/2]

◆ stateLogged()

◆ unlockPID()

◆ updateIfChanged()

◆ whilePowerOff()

Member Data Documentation

◆ loopPause

◆ m_allDefsReceived

◆ m_configName

◆ m_driverCtrlName

◆ m_driverInName

◆ m_driverOutName

◆ m_euidCalled

◆ m_euidReal

◆ m_indiDriver

◆ m_indiMutex

◆ m_indiNewCallBacks

◆ m_indiP_powerOutlet

◆ m_indiP_state

◆ m_indiSetCallBacks

◆ m_log

◆ m_pid

template<bool _useINDI = true>
class MagAOX::app::MagAOXApp< _useINDI >