====================================================================
VOCAL Release 1.2.0 Heartbeat Library README 
====================================================================
Module:		Heartbeat Library
Release:	1.2.0 (aka. Asiago
Release Date:	February 22, 2001

====================================================================
LICENSE AND COPYRIGHT 
====================================================================
For information about licensing, please see the LICENSE file in
this directory, or http://www.vovida.org/license.html .

--------------------------------------------------------------------
This software consists of voluntary contributions made by Vovida
Networks, Inc. and many individuals on behalf of Vovida Networks,
Inc.  For more information on Vovida Networks, Inc., please see
http://www.vovida.org/.

All third party licenses and copyright notices and other required
legends also need to be complied with as well.

====================================================================
INTRODUCTION 
====================================================================
Heartbeat Library is to provide a mechanism to send and retrieve heartbeat
event to/from a multicast address.  It is to keep track of which server 
is active (sending) or inactive (not receiving). 

The Heartbeat Transmit Thread is to send heartbeat even to the multi
cast address.
The Heartbeat Receiving Thread is to listen to the mulicast address, and
pull the heartbeat even using the Udp stack.
The HouseKeeping Thread is to schedule the housekeeping task to check
for the heartbeat count every an interval (configurable through the GUI)

====================================================================
KNOWN LIMITATIONS
====================================================================
The responsibility of the heartbeat is to provide a hardware reliability 
check for the monitor. It is notdesigned as a software reliability check 
since whatever inputs that crashed the first program will probably just 
crash the backup server as well so there is not much point in trying 
to resolve software bugs via heartbeat.

====================================================================
GETTING STARTED
====================================================================
HARDWARE OR SOFTWARE REQUIREMENTS

INSTALLATION INSTRUCTIONS

BUILD OR COMPILE INSTRUCTIONS

USING THE SOFTWARE	

1. Create a heartbeat transmit thread with your application port identifier 
(i.e. sip port) as parameter.  
For e.g.  HeartbeatTxThread heartbeatTxThread(defaultPort);

2. Create a heartbeat receive thread which takes as parameter the ServerContainer 
used for storing heartbeat data.  
For e.g.  HeartbeatRxThread heartbeatRxThread( ServerContainer::instance() );

The job of the heartbeat receive thread is to pull multicast heartbeat messages 
off the udpstack, extract the server host & port info from the message and use 
it as a key to search against the Server Container.  If the key matches an entry 
in the Server Container, the heartbeat counter for that server is incremented by one.

3. Create a housekeeping thread which also takes as parameter the ServerContainer.  
For e.g.  HouseKeepingThread houseKeepingThread( ServerContainer::instance() );

The job of the housekeeping thread is to sleep for 250ms (or however long the heartbeat 
interval happens to be) and wake up to do a sweep through the Server Container.  
During the sweep, we check each server entry to see if the maximum number of 
heartbeats missed has been reached so the server is declared dead or if no 
heartbeats have been missed, the heartbeat counter is reset to 0.

Note: the ServerContainer derives from BaseServerContainer.

4. Run the threads. For e.g.
        heartbeatTxThread.run();
        heartbeatRxThread.run();
        houseKeepingThread.run();

5.  The main thread will be sleeping.  For e.g.
        while (true)
        {
            sleep ( 0xFFFFFFFF );
        }


====================================================================
SOURCE CODE INFORMATION
====================================================================
See "DIRECTORY STRUCTURE"

====================================================================
DIRECTORY STRUCTURE
====================================================================
The source code is in /vocal/heartbeat


====================================================================
CONTACT INFORMATION AND WEBSITE
====================================================================
We welcome your feedback, suggestions and contributions. Contact us via 
email if you have questions, feedback, code submissions, and bug reports.

For general inquiries - info@vovida.org

We have mailing lists for the VOCAL applications and proctocol stacks: 
VOCAL - vocal@vovida.org
COPS - cops@vovida.org
MGCP - mgcp@vovida.org
RADIUS - radius@vovida.org
RTP - rtp@vovida.org
SIP - sip@vovida.org
TRIP - trip@vovida.org
You can subscribe to the mailing lists on www.vovida.org. 

You can submit bug, patches, software contributions, and feature requests 
using Bugzilla.  Access Bugzilla from www.vovida.org. 

====================================================================
======================================================================

Copyright 2000-2003, Cisco Systems, Inc.
THE INFORMATION HEREIN IS PROVIDED ON AN "AS IS" BASIS, WITHOUT ANY
WARRANTIES OR REPRESENTATIONS, EXPRESS, IMPLIED OR STATUTORY, INCLUDING
WITHOUT LIMITATION, WARRANTIES OF NONINFRINGEMENT, MERCHANTABILITY OR
FITNESS FOR A PARTICULAR PURPOSE.

$Id: README,v 1.4.2.1 2003/03/28 05:25:48 bko Exp $
