Main Page   Compound List   File List   Compound Members   File Members   Related Pages  

appHeartbeatMonitor.h File Reference

Go to the source code of this file.

Compounds

struct  ping_data

Defines

#define STRING_LENGTH   256
#define FILE_LINE_LENGTH   256
#define REGISTRATION_TIMEOUT   3

Functions

int ahm_initialize (const char *a_fifoname, int *a_fifo_fd, void **a_reginfo)
int ahm_shutdown (void **a_client_reg_info)
int ahm_register (pid_t a_pid, unsigned long a_id, const char *a_recovery_script, const char *a_process_name, unsigned long a_min_interval, unsigned long a_max_interval, void **a_client_reg_info)
int ahm_unregister (void **a_client_reg_info)
int ahm_send_heartbeat (void)
int ahm_add_heartbeat_timer_callback (const void *a_client_reg_info)
int ahm_remove_heartbeat_timer_callback (void)
int ahm_send_heartbeat_to_fifo (int a_fifo_fd)


Define Documentation

#define FILE_LINE_LENGTH   256
 

#define REGISTRATION_TIMEOUT   3
 

This value determines when registration is considered a failure

#define STRING_LENGTH   256
 


Function Documentation

int ahm_add_heartbeat_timer_callback const void *    a_client_reg_info
 

This function may be used for sending heartbeats using the system timer. It should be called after registration has taken place. It uses the SIGALRM signal to call the ahm_send_heartbeat() function within the heartbeat interval. The heartbeat interval value used will be the minimum interval so as to not create a race condition with the daemon. Use of this function is optional and provided as a convenience for setting up recurring heartbeats.

Parameters:
a_client_reg_info  The client registration structure
Returns:
zero on successful installation of signal handler and timer setup. EINVAL if the client registration pointer is NULL non-zero on failure and the error code from setitimer() will be returned. See the manual page for this function for more info.

int ahm_initialize const char *    a_fifoname,
int *    a_fifo_fd,
void **    a_reginfo
 

This is the first function that a client application should call to start using the heartbeat service. The client must provide the name of the heartbeat FIFO that it will use to send heartbeat through. If the file exists already, then EEXIST will be returned from the mkfifo() call. The client application must provide a different FIFO name for each heartbeat that it wishes to generate. Any failure from issuing the mkfifo() call or the open() call to access the FIFO will be returned by this function. See the manual pages for these two function calls for more information.

After successful completion of this call, the client should issue ahm_register(). It is also convenient to set up a callback at this time to handle sending heartbeats so that a heartbeat is not missed immediately after registration if there is a short period between heartbeats.

Parameters:
a_fifoname  The name of the heartbeat FIFO
a_fifo_fd  The return location for the FIFO file descriptor. The client does not need to use this, it is there as a convenience if the client wishes to handle sending its own heartbeats.
a_reginfo  A pointer in which to store registration information. Memory is allocated here and freed upon calling ahm_shutdown().
Returns:
EINVAL if the fifo name is NULL ENOMEM if failed to allocate memory during registration zero on success

int ahm_register pid_t    a_pid,
unsigned long    a_id,
const char *    a_recovery_script,
const char *    a_process_name,
unsigned long    a_min_interval,
unsigned long    a_max_interval,
void **    a_client_reg_info
 

This function will fill in the internal registration structure and then create the heartbeat fifo and open it. If this succedes, it will then create the registration file. Successful return of this function does not guarantee successful registration. Successful registration is determined by two methods. The first is observing the log message indicating that the application successfully registered. The second is in being able to send a heartbeat within the timeout specified. If sending the heartbeat would block after the specified timeout, then the registration has failed. If the registration file is valid, the registration file will be removed. If it is invalid, the file will remain so that it can be inspected. The system log should be queried to further determine the failure of registration for this application.

For all strings provided, they are truncated to STRING_LENGTH. Applications using longer strings may fail registration due to truncation.

Parameters:
a_pid  The actual pid of the process. A PID greater than 1 is valid.
a_id  A number used to identify this specific registration instance for this client. Any number is valid.
a_recovery_script  The absolute path to a recovery script or executable. This script is not verified until the registration is processed by the heartbeat service.
a_min_interval  This is the minimum amount of time for sending a heartbeat. The heartbeat service does not use this value. It is solely for use with timer callbacks, but must provided. It must be less than the a_max_interval, but not less than 10ms. Upper bound restrictions are identical to that of a_max_interval with the addition of being less than a_max_interval.
a_max_interval  This is the maximum amount of time (in milliseconds) the heartbeat service should wait for a heartbeat from this application. Any value greater than 10ms and less than the maximum value stored in a long divided by 1000, is accepted. This range is determined by the need to convert the value in milliseconds to microseconds and store this value in a type long.
a_client_reg_info  This is a pointer to registration specific information. This is private and not manipluated by the client application.
Returns:
Returns zero on success. On error it will return a non-zero value which will be the error codes from mkfifo, or open, depending upon which of these fail. If the client registration structure pointer is invalid or any of the registration parameters are invalid, it will return EINVAL.

Todo:
Provide upper bound checks for the intervals so that when multiplying by 1000, it does not go over the max value of long and thus become negative.

int ahm_remove_heartbeat_timer_callback void   
 

Uninstalls the signal handler and removes the timer issuing the SIGALRM signal. This is the companion function to ahm_add_heartbeat_timer_callback().

Returns:
zero on successful removal of signal handler and stopping timer. Non-zero on failure and the error code from setitimer() will be returned. See the manual page for this function for more info.

int ahm_send_heartbeat void   
 

This may be used by the client application to send a single heartbeat. It may also be used by the client as a callback, such as in setting up a signal handler for a timer. It may also be called before calling ahm_add_heartbeat_callback() and it will block for a maximum amount of time (REGISTRATION_TIMEOUT) until it can write to the FIFO. This functionality is provided so that the application will know if registration has succeeded within a certain reasonable amount of time.

This function is also used when the client calls ahm_add_heartbeat_timer_callback(), which handles installing a signal handler and a timer for sending heartbeats.

This function is used to send a single heartbeat to the heartbeat FIFO. It will timeout after REGISTRATION_TIMEOUT seconds, afterwhich it will be assumed that registration has failed if this is the first call. If after the first successful write and the function returns without sending a heartbeat, it is assumed that the heartbeat service is down. In such a case, as long as the registration file remains, then the client should continue to attempt to send a heartbeat to the service. Failure to continue to send a heartbeat, even when the service appears to be down or not responding, could result in an undesirable recovery being initiated by the service when it returns to receive heartbeats.

NOTE: This function does not handle multiple heartbeats from a single application due to how the FIFO file descriptor is handled.

Returns:
returns zero if heartbeat sent successfully, returns non-zero if it failed to send the heartbeat. EINVAL if the client registration pointer is NULL EBADF if the FIFO file descriptor is invalid. ETIMEDOUT if the heartbeat could not be sent within the registration timeout (i.e. REGISTRATION_TIMEOUT). If the actual write to the FIFO fails, then the return value will pertain to that returned by the write() function call. See the manual page for write for more information.

int ahm_send_heartbeat_to_fifo int    a_fifo_fd
 

This function sends a heartbeat to a specific FIFO descriptor. In all other aspects, it is identical to ahm_send_heartbeat().

Parameters:
a_fifo_fd  A FIFO descriptor to which the heartbeat should be sent.
Returns:
returns zero if heartbeat sent successfully, returns non-zero if it failed to send the heartbeat. EINVAL if the client registration pointer is NULL EBADF if the FIFO file descriptor is invalid. ETIMEDOUT if the heartbeat could not be sent within the registration timeout (i.e. REGISTRATION_TIMEOUT). If the actual write to the FIFO fails, then the return value will pertain to that returned by the write() function call. See the manual page for write for more information.

int ahm_shutdown void **    a_client_reg_info
 

The unregister function must be called before this function, in order for proper termination of the heartbeat service connection. Failure to call unregister will cause the client to be recovered.

Parameters:
a_client_reg_info  The private client registration information.
Returns:
zero on success; non-zero on error.

int ahm_unregister void **    a_client_reg_info
 

Removes the registration file, closes and removes the hearbeat FIFO. The client information remains and the application may re-register without having to call initialize(). However, once shutdown() is called, the registration information is removed.

Parameters:
a_client_reg_info  The client registration information. This is private.
Returns:
zero on successful unregistration. non-zero on failure. In the case of failure, memory may not be freed and the registration file may continue to exist. The application may be recovered, though how this is handled is unpredicatable depending upon the application's state.

Todo:
Do we need to uninstall the signal handler if one was installed to handle heartbeats?


Generated on Wed Oct 30 15:14:42 2002 for Application Heartbeat Monitor Client Library by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002