---

Application Heartbeat Monitor Client Library Documentation

0.2

This is a library that applications can use to connect to the Application Heartbeat Service.

Usage
Compilation
Add -lappHeartbeatMonitor to the compiler options and include appHeartbeatMonitor.h in the source.

Becoming monitored
There are four functions the client application must call:

1. ahm_initialize()
2. ahm_register()
3. ahm_unregister()
4. ahm_shutdown()

ahm_initialize
The initialize function is called before an application registers. The shutdown function should be called to free up memory that this function allocates. The application must provide a pointer for private data to be stored. This is used to store intialization information, registration and unregistration information.

ahm_register
This method registers the application with the heartbeat monitor. This method should be called when the application is ready to begin being monitored. After this method is called, if the application exits without unregistering, the heartbeat monitor will attempt to recover it.

ahm_unregister
Upon return from this call, the client may safely exit without the possibility of being recovered by the heartbeat monitor. Shutdown should still be called in order to free the private data maintained for the application.

ahm_shutdown
This method frees the structure that contains the client registration information and other internal information.

Helper Functions
Use of the first three of these functions limits the number of heartbeats a client can produce to only one heartbeat. If your application would like to send multiple heartbeats, it should either implement its own heartbeat function using the FIFO descriptor returned from the ahm_initialize() function or use the ahm_send_heartbeat_to_fifo() function.

1. ahm_add_heartbeat_timer_callback()
2. ahm_remove_heartbeat_timer_callback()
3. ahm_send_heartbeat()
4. ahm_send_heartbeat_to_fifo()

ahm_add_heartbeat_timer_callback
This function installs a signal handler for SIGALRM and installs a timer that will invoke the signal.

ahm_remove_heartbeat_timer_callback
This is the companion function to ahm_add_heartbeat_timer_callback. It removes the signal handler and turns off the timer generating those signals.

ahm_send_heartbeat
This function may be used by an application to send a single heartbeat. The client may desire to incorporate this call within its main event loop, but ensuring that it is called with enough frequency that the application doesn't miss a heartbeat.

ahm_send_heartbeat_to_fifo
This function is used to send a heartbeat to a specific FIFO. It is identical to ahm_send_heartbeat with this one exception.

---