The VisAO Camera
VisAOApp_base.h
Go to the documentation of this file.
1 /************************************************************
2 * VisAOApp_base.h
3 *
4 * Author: Jared R. Males (jrmales@email.arizona.edu)
5 *
6 * Declarations for the basic VisAO application, implements the command fifos
7 *
8 * Developed as part of the Magellan Adaptive Optics system.
9 ************************************************************/
10 
11 /** \file VisAOApp_base.h
12  * \author Jared R. Males
13  * \brief Declarations for VisAOApp_base.
14  *
15 */
16 
17 #ifndef __VisAOApp_base_h__
18 #define __VisAOApp_base_h__
19 
20 #include <string>
21 #include <iostream>
22 #include <sstream>
23 #include <sched.h>
24 #include <poll.h>
25 
26 #include "libvisao.h"
27 #include "statusboard.h"
28 #include "profiler.h"
29 
30 #include "Logger.h"
31 
32 ///Global set by SIGTERM.
33 extern int TimeToDie;
34 
35 extern std::string global_app_name;
36 
37 ///The namespace for VisAO software.
38 namespace VisAO
39 {
40 
41 
42 
43 ///The base class for VisAO applications.
44 /** Provides the fifo management and SIGIO handling. Essentially a wrapper to the \ref fifoutils.h "fifo utilities" of the VisAO library.
45  * Does not provide config file or logger facilities. These are added by instead using \ref VisAOApp_standalone or deriving from
46  * \ref Arcetri::AOApp
47 */
49 {
50 public:
51  ///Default constructor
52  VisAOApp_base();
53 
54  ///Virtual destructor
55  virtual ~VisAOApp_base();
56 
57 private:
58  uid_t euid_real; ///< The real user id of the proces
59  uid_t euid_called; ///< The user id of the process as called (that is when the constructor gets called).
60  uid_t suid; ///< The save-set user id of the process
61 
62  int RT_priority; ///< The real-time scheduling priority. Default is 0.
63 
64 
65 public:
66  int set_euid_called(); ///< Changes the user id of the process to euid_called
67  int set_euid_real(); ///< Changes the user id fo the process to the real user id.
68 
69 
70  /// Set the real-time priority of the current process.
71  /** Elevates the user id to uid_called.
72  * \param prio the desired priority
73  * \retval 0 on success
74  * \retval -1 on failure
75  */
76  int set_RT_priority(int prio);
77 
78  /// Get the real-time priority of the current process.
80 
81 protected:
82  std::string app_name; ///<The name of the application.
83 
84  double pause_time; ///< Time to pause during application main loop.
85 
86 public:
87 
88  ///Set the application name.
89  int set_app_name(std::string an);
90 
91  ///Get the application name.
92  virtual std::string get_app_name(){ return app_name;}
93 
94  ///Install fifo channels.
95  /** Call this after paths set, but before connect_fifo_list.
96  * \param usethreads if true the threaded versions of the handlers are installed.
97  * \retval 0 on success.
98  * \retval -1 on failure.
99  */
100  virtual int setup_baseApp(bool usethreads = false);
101 
102  ///Create fifo names, then installs the fifo channels.
103  /** Bools provide control over which fifo channels are used.
104  * assumes com_path is the base path of the fifos. adds _com_remote_in (for example) is added.
105  * \param remfifo if true the remote fifo is created and installed.
106  * \param locfifo if true the local fifo is created and installed.
107  * \param scrfifo if true the script fifo is created and installed.
108  * \param autfifo if true the auto fifo is created and installed.
109  * \param usethreads if true the threaded versions of the handlers are installed.
110  * \retval 0 on success.
111  * \retval -1 on failure.
112  */
113  virtual int setup_baseApp(bool remfifo, bool locfifo, bool scrfifo, bool autfifo, bool usethreads = false);
114 
115  ///Mutex used by the threaded versions of the standard command handlers.
116  pthread_mutex_t my_mutex;
117 
118 protected:
119  fifo_list fl; ///<The list of named-pipe fifos used for inter-process comms.
120 
121  std::string com_path; ///< The control fifo path base name
122 
123  std::string com_path_remote; ///<The path for the remote control fifos
124  std::string com_path_local; ///<The path for the local control fifos
125  std::string com_path_script; ///<The path for the script control fifos
126  std::string com_path_auto; ///<The path for the auto control fifos
127 
128  double wait_to; ///< The timeout for waiting on responses from FIFOs in seconds.
129 
130 
131 public:
132  ///Allocate the fifo_list.
133  /** Calls setup_fifo_list(&fl, nfifos).
134  * \param nfifos is the number of fifos we need
135  * \retval 0 on success.
136  * \retval -1 o failure.
137  */
138  int setup_fifo_list(int nfifos);
139 
140  /// Connect the fifo_list with exclusive locking.
141  /** Calls \ref connect_fifo_list(fifo_list *) "connect_fifo_list"(&fl).
142  * \retval 0 on success.
143  * \retval -1 on failure.
144  */
145  int connect_fifo_list();
146 
147  /// Connect the fifo_list without exclusive locking.
148  /** Calls \ref connect_fifo_list_nolock(fifo_list *) "connect_fifo_list_nolock"(&fl).
149  * \retval 0 on success.
150  * \retval -1 on failure.
151  */
153 
154  /// Setup the SIGIO signal handling
155  /** Uses the sigaction facilities.
156  * \retval 0 on success.
157  * \retval -1 on failure.
158  */
159  int setup_sigio();
160 
161  /// Setup SIGIO signal handling using realtime signals
162  /** Uses the sigaction facilities. Also installs the backup handler for standard SIGIO.
163  * \retval 0 on success.
164  * \retval -1 on failure.
165  */
166  int setup_RTsigio();
167 
168  ///Check for pending reads for the fifo list while using the RT signals.
170 
171  /// Write data to a fifo_channel, and get a response if desired.
172  /** Calls \ref write_fifo_channel(fifo_channel *, const char*, int) "write_fifo_channel(&fl.fifo_ch[ch], str, len)"
173  * If the fifo_channel is timedout, this will not write to that channel again until the file is opened on the other end
174  * as detected by fstat access time.
175  * \param ch the channel to write to.
176  * \param com the buffer to write
177  * \param comlen the length of the buffer to write, including the '\0' character
178  * \param resp is a string pointer to be filled in with the server_response. Set to 0 if no response is desired.
179  * \retval 0 on success
180  * \retval -1 on failure
181  */
182  int write_fifo_channel(int ch, const char *com, int comlen, std::string * resp);
183 
184  /// Write data to a fifo_channel, with a sequence message attached, and get a response if desired.
185  /** Calls \ref write_fifo_channel(fifo_channel *, const char*, int) "write_fifo_channel(&fl.fifo_ch[ch], str, len)"
186  * If the fifo_channel is timedout, this will not write to that channel again until the file is opened on the other end
187  * as detected by fstat access time.
188  * \param ch the channel to write to.
189  * \param com the buffer to write
190  * \param comlen the length of the buffer to write
191  * \param resp is a string pointer to be filled in with the server_response. Set to 0 if no response is desired.
192  * \param sm is the sequence message.
193  * \retval 0 on success
194  * \retval -1 on failure
195  */
196  int write_fifo_channel(int ch, const char *com, int comlen, std::string * resp, char *sm);
197 
198  /// Check, and wait if neccessary, for data on a fifo channel.
199  /** Waits for wait_to seconds, then times out. Reports only the first in any series of timeouts on one channel.
200  * \param resp a pointer to a std::string, on exit is a copy of server_response or "" on timeout
201  * \param ch is the fifo_list channel number to wait on.
202  * \retval 0 on success
203  * \retval -1 on failure.
204  * \todo get_fifo_channel_response is a busy wait. should select or poll instead, but with signal safety.
205  */
206  int get_fifo_channel_response(std::string * resp, int ch);
207 
208  /// Set the wait timeout for fifo channel responses.
209  /** \param to the desired timeout.
210  * \retval 0 on success.
211  * \retval -1 on failure (if < 0)
212  */
213  int set_wait_to(double to);
214 
215  /// Get the wait timeout for fifo channel responses.
216  /** \retval wait_to
217  */
218  double get_wait_to(){return wait_to;}
219 
220 protected:
221  ///The current control mode.
222  /** Is static so it can be used by static RTDB handlers.
223  */
224  static int control_mode;
225 
226  ///The default control mode.
227  /** If not -1, then this mode is always returned to, instead of NONE.
228  */
230 
231 public:
232  ///The control modes.
233  enum control_modes{CMODE_NONE, CMODE_REMOTE, CMODE_LOCAL, CMODE_SCRIPT, CMODE_AUTO, CMODE_max};
234 
235 
236  virtual int request_control(int cmode); ///< Calls \ref request_control(int,bool) "request_control(cmode, 0)"
237 
238  ///Attempts to change the control type.
239  /** \param cmode The requested control mode \see control_modes.
240  * \param override If not true, forces the change no matter what current mode is.
241  * \retval control_mode if successful.
242  * \retval -1 if unsuccessful.
243  */
244  virtual int request_control(int cmode, bool override);
245 
246  /// Processing for remote commands
247  /** The handler calls __remote_command, which in turn calls \ref remote_command, which is where the
248  * app specific processing should be done.
249  * This contains the \ref control_mode logic for the remote control state, which is processed before
250  * the call to \ref remote_command.
251  * \param com is the command string to be processed.
252  * \returns the application response.
253  */
254  virtual std::string __remote_command(std::string com, char *seqmsg);
255  /// Called by \ref __remote_command after control state logic.
256  /** This should be overriden by derived classes.
257  * \param com is the command string to be processed.
258  * \returns the application response.
259  */
260  virtual std::string remote_command(std::string com);
261  virtual std::string remote_command(std::string com, char *seqmsg);
262 
263  /// Processing for local commands
264  /** The handler calls __local_command, which in turn calls \ref local_command, which is where the
265  * app specific processing should be done.
266  * This contains the \ref control_mode logic for the local control state, which is processed before
267  * the call to \ref local_command.
268  * \param com is the command string to be processed.
269  * \returns the application response.
270  */
271  virtual std::string __local_command(std::string com, char *seqmsg);
272 
273  /// Called by \ref __local_command after control state logic.
274  /** This should be overriden by derived classes.
275  * \param com is the command string to be processed.
276  * \returns the application response.
277  */
278  virtual std::string local_command(std::string com);
279  virtual std::string local_command(std::string com, char *seqmsg);
280 
281  /// Processing for script commands - not normally overriden.
282  /** The handler calls __script_command, which in turn calls \ref script_command, which is where the
283  * app specific processing should be done.
284  * This contains the \ref control_mode logic for the script control state, which is processed before
285  * the call to \ref script_command.
286  * \param com is the command string to be processed.
287  * \returns the application response.
288  */
289  virtual std::string __script_command(std::string com, char *seqmsg);
290 
291  /// Called by \ref __script_command after control state logic.
292  /** This should be overriden by derived classes.
293  * \param com is the command string to be processed.
294  * \returns the application response.
295  */
296  virtual std::string script_command(std::string com);
297  virtual std::string script_command(std::string com, char *seqmsg);
298 
299  /// Processing for auto commands - to be overriden.
300  /** The handler always calls auto_command, which after app specific processing should call \ref post_auto_command.
301  * This is so app specific processing happens first in auto mode, for speed.
302  * \param com is the command string to be processed.
303  * \returns the application response.
304  */
305  virtual std::string auto_command(std::string com, char *seqmsg);
306 
307  /// Processing for auto commands - not normally overriden.
308  /** The handler calls auto_command, which in turn should call post_auto_command, which
309  * contains the \ref control_mode logic for the auto control state, which is processed after
310  * the call to \ref auto_command for speed.
311  * \param com is the command string to be processed.
312  * \returns the application response.
313  */
314  virtual std::string post_auto_command(std::string com, char *seqmsg = 0);
315 
316  ///Convenience function to return the control type string, e.g. "REMOTE"
317  std::string control_mode_string();
318 
319  ///Convenience function to return the control type response string, e.g. "A\n"
320  std::string control_mode_response();
321 
322  /** @name Error reporting and logging
323  * Some generic error reporting and logging facilities
324  */
325  //@{
326  protected:
327  std::ostringstream logss; ///< Conveninence string stream for building log messages.
328 
329  public:
330  /// Report an error. Also calls log_msg.
331  /** \param emsg the message to report.
332  * \param LogLevel is the logger level for the error report. For errors this is usually Logger::LOG_LEVEL_ERROR or Logger::LOG_LEVEL_FATAL
333  */
334  virtual void error_report(int LogLevel, std::string emsg);
335 
336  /// Log a message.
337  /** \param lmsg the message to log.
338  * \param LogLevel is the logger level for the message.
339  */
340  virtual void log_msg(int LogLevel, std::string lmsg);
341  //@}
342 
343  /** @name profiler
344  * interface to the VisAO profiler
345  */
346  //@{
347  protected:
348  VisAO::profiler * profile;
349  std::string profile_path;
350  int use_profiler;
351 
352  public:
353  VisAO::profiler * get_profile(){return profile;}
354  int get_use_profiler(){return use_profiler;}
355  int start_profiler();
356  //@}
357 
358  /** @name statusboard facilities
359  * manage the shared memory status board
360  */
361  //@{
362  protected:
363  void * statusboard_shmemptr; ///<The pointer to the shared memory block for the statusboard
364  key_t statusboard_shmemkey; ///<The key used to lookup the shared memory
365  int statusboard_shmemid; ///<The ID of the shared memory block.
366 
367  /// Creates and attaches to the statusboard shared memory
368  /** \param sz is the desired size (should be sizeof(xxxxx_status_board))
369  * \retval 0 on success
370  * \retval -1 on failure
371  */
372  int create_statusboard(size_t sz);
373 
374  public:
375  /// Get the status board shared memory pointer.
376  /** \retval the shared memory pointer void *
377  */
379 
380  /// Set the status board shared memory key. Does nothing else.
381  /** \param mkey is the key
382  * \retval 0 on success (always)
383  */
385 
386  /// Get the status board shared memory key.
387  /** \retval the shared memory key
388  */
390 
391  /// Update the status board.
392  /** Overridden versions should call this as VisAOApp_bas::update_statusboard so the basics are taken care of.
393  * \retval 0 on success
394  * \retval -1 on failure
395  */
396  virtual int update_statusboard();
397  //@}
398 
399  /** @name Data Logging
400  * Provides logging of process data at intervals, or upon a change in state.
401  */
402  //@{
403  protected:
404  std::ofstream dataof;
405 
406  bool dataFileOpen;
407  double dataFileOpenTime;
408 
409  double data_log_time_length;
410  std::string data_save_path;
411  std::string data_file_prefix;
412 
413  std::string getDataFileName();
414 
415  int checkDataFileOpen();
416 
417  public:
418  ///Log data at intervals
419  virtual void dataLogger(timeval tv);
420  //@}
421 
422 };
423 
424 int com_remote_handler(fifo_channel *); ///<\ref __fifo_channel "fifo_channel" handler for remote commands
425 int com_local_handler(fifo_channel *); ///<\ref __fifo_channel "fifo_channel" handler for local commands
426 int com_script_handler(fifo_channel *); ///<\ref __fifo_channel "fifo_channel" handler for script commands
427 int com_auto_handler(fifo_channel *); ///<\ref __fifo_channel "fifo_channel" handler for auto commands
428 
429 /// Thread version of the \ref __fifo_channel "fifo_channel" handler for remote commands.
430 /** Creates a thread using \ref __com_remote_thread_handler in the detached state.
431 * Note: The thread fifo handlers are no longer maintained as of 3 July 2011. Use with caution.
432  */
433 int com_remote_thread_handler(fifo_channel * fc);
434 /// The start function for remote handling with a thread.
435 /** Note: The thread fifo handlers are no longer maintained as of 3 July 2011. Use with caution.
436 */
437 void * __com_remote_thread_handler(void * ptr);
438 
439 /// Thread version of the \ref __fifo_channel "fifo_channel" handler for local commands.
440 /** Creates a thread using \ref __com_local_thread_handler in the detached state.
441 * Note: The thread fifo handlers are no longer maintained as of 3 July 2011. Use with caution.
442  */
443 int com_local_thread_handler(fifo_channel * fc);
444 
445 /// The start function for local handling with a thread.
446 /** Note: The thread fifo handlers are no longer maintained as of 3 July 2011. Use with caution.
447 */
448 void * __com_local_thread_handler(void * ptr);
449 
450 /// Thread version of the \ref __fifo_channel "fifo_channel" handler for script commands.
451 /** Creates a thread using \ref __com_script_thread_handler in the detached state.
452 * Note: The thread fifo handlers are no longer maintained as of 3 July 2011. Use with caution.
453  */
454 int com_script_thread_handler(fifo_channel * fc);
455 /// The start function for script handling with a thread.
456 /** Note: The thread fifo handlers are no longer maintained as of 3 July 2011. Use with caution.
457 */
458 void * __com_script_thread_handler(void * ptr);
459 
460 /// Thread version of the \ref __fifo_channel "fifo_channel" handler for auto commands.
461 /** Creates a thread using \ref __com_auto_thread_handler in the detached state.
462  * Note: The thread fifo handlers are no longer maintained as of 3 July 2011. Use with caution.
463  */
464 int com_auto_thread_handler(fifo_channel * fc);
465 /// The start function for auto handling with a thread.
466 /** Note: The thread fifo handlers are no longer maintained as of 3 July 2011. Use with caution.
467 */
468 void * __com_auto_thread_handler(void * ptr);
469 
470 ///Utility function for parsing command buffers line by line.
471 /** This alters com, so make a copy if we need it somewhere else.
472 */
473 int getnextline(std::string *comln, std::string * com);
474 
475 
476 
477 /***** profiler stuff *****/
478 
479 void * __start_profiler(void * ptr);
480 
481 } //namespace VisAO
482 #endif //__VisAOApp_base_h__
483 
virtual ~VisAOApp_base()
Virtual destructor.
int get_RT_priority()
Get the real-time priority of the current process.
Definition: VisAOApp_base.h:79
std::string control_mode_string()
Convenience function to return the control type string, e.g. "REMOTE".
void * __com_remote_thread_handler(void *ptr)
The start function for remote handling with a thread.
int statusboard_shmemid
The ID of the shared memory block.
int com_local_handler(fifo_channel *fc)
fifo_channel handler for local commands
int com_remote_thread_handler(fifo_channel *fc)
Thread version of the fifo_channel handler for remote commands.
int com_auto_thread_handler(fifo_channel *fc)
Thread version of the fifo_channel handler for auto commands.
control_modes
The control modes.
static int default_control_mode
The default control mode.
double wait_to
The timeout for waiting on responses from FIFOs in seconds.
void * __com_auto_thread_handler(void *ptr)
The start function for auto handling with a thread.
int TimeToDie
Global set by SIGTERM.
int setup_sigio()
Setup the SIGIO signal handling.
pthread_mutex_t my_mutex
Mutex used by the threaded versions of the standard command handlers.
std::ostringstream logss
Conveninence string stream for building log messages.
void * statusboard_shmemptr
The pointer to the shared memory block for the statusboard.
virtual void error_report(int LogLevel, std::string emsg)
Report an error. Also calls log_msg.
virtual std::string __local_command(std::string com, char *seqmsg)
Processing for local commands.
int RT_priority
The real-time scheduling priority. Default is 0.
Definition: VisAOApp_base.h:62
int set_RT_priority(int prio)
Set the real-time priority of the current process.
A structure to hold a list of fifo_channels.
Definition: fifoutils.h:204
std::string com_path
The control fifo path base name.
virtual int update_statusboard()
Update the status board.
virtual int setup_baseApp(bool usethreads=false)
Install fifo channels.
int check_fifo_list_RTpending()
Check for pending reads for the fifo list while using the RT signals.
uid_t euid_real
The real user id of the proces.
Definition: VisAOApp_base.h:58
std::string com_path_local
The path for the local control fifos.
std::string app_name
The name of the application.
Definition: VisAOApp_base.h:82
int setup_fifo_list(int nfifos)
Allocate the fifo_list.
VisAOApp_base()
Default constructor.
key_t get_statusboard_shmemkey()
Get the status board shared memory key.
Declarations for the VisAO status information structures.
uid_t euid_called
The user id of the process as called (that is when the constructor gets called).
Definition: VisAOApp_base.h:59
std::string com_path_remote
The path for the remote control fifos.
std::string com_path_script
The path for the script control fifos.
virtual std::string __script_command(std::string com, char *seqmsg)
Processing for script commands - not normally overriden.
VisAO software utilitites, declarations.
key_t statusboard_shmemkey
The key used to lookup the shared memory.
virtual std::string auto_command(std::string com, char *seqmsg)
Processing for auto commands - to be overriden.
int getnextline(std::string *comln, std::string *com)
Utility function for parsing command buffers line by line.
std::string control_mode_response()
Convenience function to return the control type response string, e.g. "A\n".
int com_script_handler(fifo_channel *fc)
fifo_channel handler for script commands
fifo_list fl
The list of named-pipe fifos used for inter-process comms.
std::string com_path_auto
The path for the auto control fifos.
The base class for VisAO applications.
Definition: VisAOApp_base.h:48
int get_fifo_channel_response(std::string *resp, int ch)
Check, and wait if neccessary, for data on a fifo channel.
double pause_time
Time to pause during application main loop.
Definition: VisAOApp_base.h:84
virtual std::string remote_command(std::string com)
Called by __remote_command after control state logic.
virtual int request_control(int cmode)
Calls request_control(cmode, 0).
int com_script_thread_handler(fifo_channel *fc)
Thread version of the fifo_channel handler for script commands.
int com_local_thread_handler(fifo_channel *fc)
Thread version of the fifo_channel handler for local commands.
int set_app_name(std::string an)
Set the application name.
uid_t suid
The save-set user id of the process.
Definition: VisAOApp_base.h:60
virtual void dataLogger(timeval tv)
Log data at intervals.
int set_statusboard_shmemkey(key_t mkey)
Set the status board shared memory key. Does nothing else.
virtual std::string __remote_command(std::string com, char *seqmsg)
Processing for remote commands.
virtual std::string script_command(std::string com)
Called by __script_command after control state logic.
void * __com_script_thread_handler(void *ptr)
The start function for script handling with a thread.
int set_wait_to(double to)
Set the wait timeout for fifo channel responses.
int create_statusboard(size_t sz)
Creates and attaches to the statusboard shared memory.
virtual std::string get_app_name()
Get the application name.
Definition: VisAOApp_base.h:92
double get_wait_to()
Get the wait timeout for fifo channel responses.
int set_euid_called()
Changes the user id of the process to euid_called.
int connect_fifo_list()
Connect the fifo_list with exclusive locking.
static int control_mode
The current control mode.
int setup_RTsigio()
Setup SIGIO signal handling using realtime signals.
virtual std::string local_command(std::string com)
Called by __local_command after control state logic.
int com_auto_handler(fifo_channel *fc)
fifo_channel handler for auto commands
int connect_fifo_list_nolock()
Connect the fifo_list without exclusive locking.
void * __com_local_thread_handler(void *ptr)
The start function for local handling with a thread.
The namespace of VisAO software.
virtual std::string post_auto_command(std::string com, char *seqmsg=0)
Processing for auto commands - not normally overriden.
void * get_statusboard_shmemptr()
Get the status board shared memory pointer.
virtual void log_msg(int LogLevel, std::string lmsg)
Log a message.
int set_euid_real()
Changes the user id fo the process to the real user id.
int com_remote_handler(fifo_channel *fc)
fifo_channel handler for remote commands
int write_fifo_channel(int ch, const char *com, int comlen, std::string *resp)
Write data to a fifo_channel, and get a response if desired.