Non-virtual destructors for classes that are unlikely to be base classes

[pingcheck] / Readme

     Table of Contents
=======================================
1. Introduction
2. Code Conventions
3. Source Code
4. Configuration File
5. References



1.   Introduction
=======================================
This application provides means to check the availability of remote hosts
through pings to them.


1.1. Rationale
---------------------------------------
The application uses ICMP echo requests messages to verify if a given host
is available or not.

The host's address can be an IP or a DNS.


1.2. How to use
---------------------------------------
There are many ways to invoke the application, the simplest is just type:
  ./libpingcheck
which uses the configuration values from the configuration file (describled in
the Configuration File section).


1.3. Resources
---------------------------------------
Further information about the problem domain can be found in the References
section.


1.4. Legal Issues
---------------------------------------
All rights reserved to Intra2net AG.



2.   Code Conventions
=======================================
This section describes the code conventions that must be followed when maintain
this code.


2.1. Data Types
---------------------------------------
This section is a guideline about the type you MUST use when declaring
variables and constants. These types were chose to provide portability and
improve code reradability.

- Use the std::string to represent array of characters.

- Use int32_t, int16_t and int8_t (or their unsigned couter parts) - instead of
  int, short and char, respectively - when the variable or constant MUST have a
  specific size (e.g. like in the protocol headers). This documents that the
  variable has the given number of bits. This states clear the intent of the
  original programmer and avoids improper modifications.

- Use only int for regular integer numbers that do not require any specific
  size. And document that a variable is non-negative using assertions. Do not
  use unsigned types to say a number will never be negative.

- Use std::size_t for integers that represent sizes of vectors, objects or
  buffers. Thus leaving the size difinition to the platform.


2.2. Coding Style
---------------------------------------
The coding style used in this program is in accordance with the Intra2net,
which can be found in the following source:

- http://intranet/support_wiki/doku.php?id=entwicklung:codingstyle


2.3. Versioning
---------------------------------------
Version is built as follows:
  major.minor[-[a|b|rc]]
where:
- major represents big changes in application functionality.
- minor means small changes of bug fixes.
- a, b and rc stand for Alpha, Beta and Release Candidate respectivelly. Though
  they are optional and not required in public release.


2.4. Error Handling
---------------------------------------
There are two basic kinds of errors that shall happen in the program, errors
that the program can recover (expected) and errors that the progam can not or
should not recover from (exceptional errors). Bellow the description and the
method adopted to deal with each one:
- Expected: these errors can occur and must be handled by boolean return values.
  (i.e. if a host is down, if the address was not resolved). This errors can
  happen, but THE PROGRAM MUST CONTINUE TO OPERATE EVEN IF THEY HAPPEN.
- Exceptional: these are the kinds of errors that should not occur. They must be
  handled by exceptions and THE PROGRAM MUST HALT IF THEY HAPPEN.
Thus, to keep things as simple as possible, this program adopts just two kinds
of error detection and handling:
- Return Boolean Value for expected errors and
- Handle Exceptions for exceptional errors.


2.5. Assertions
---------------------------------------
Also, it is good to use ASSERTS to document assumptions about:
- method's argument values. If you expect that a parameter have certain values,
  assert it (preconditions)
- and if you expect the method deliver a certain value, assert in the end of
  the method (postcondition).
This is known by programming by contract.



3.   Source Code
=======================================
In this section is presented an overview of the source code and key design
decisions.


3.1. Main directories
---------------------------------------
The sources are spread over these distincts directories:
- src: contains the main application.
- test: where is located the unit tests.
- conf: keeps default and example configuration files.


3.2. Main concept of application operation
---------------------------------------
This application makes extensive use of asynchronous timers-handlers from
Boost ASIO. So this section describes briefly how ASIO works. More information
can be found in the References section.

The basic idea is to have a handler which will be called when a timer expires.
After the timer expires, you have to schedule the timer again to call your
handler once more. Given the declaration of the timer:

    boost::asio::deadline_timer my_timer( my_io_service );

you must specify when it will expire:

    my_timer.expires_at( some_time_in_seconds + seconds( interval_in_seconds ) );

and which method will handle when the timer expires.

    my_timer.async_wait( boost::bind( &MyClass::my_handle_method, this ) );

Then, the my_io_service service can be called to perform a loop:

    my_io_service.run();



4.   Configuration file
=======================================
In this section are describled the configuration items, along with they
possible values and meanings. This section is organized in each major
configuration block.


4.1. General
---------------------------------------
This configurations are shared among and affect all the hosts.
- hosts-down-limit: an absolute number, which ranges from 0 to the number of
  hosts available. This value represents the minimum number of hosts that have
  to fail (i.e. do not reply to the ping) in order to alert any external system.
- ping-fail-limit: percentage of pings to a host that can fail. If the
  percentage of failed pings to a host exceed this number, then the host is
  considered down.
- status-notifier-cmd: the command line that is called when a host is down, or
  up. Accepted variables are:
    ${status} - down or up
- link-up-interval: how long (in minutes) the pings don't have to fail
  in order to consider the link up, or stable.


4.2. Host
---------------------------------------
- name: the DNS or IP of the host to ping. Take in consideration that, if a
  DNS is given, the application pings all IPs in the look up table, however, if
  IP is provide, it is the only which will be pinged.
- interval: the host will be pinged every "interval" seconds.



5.   References
=======================================
[1]  http://tools.ietf.org/html/rfc792
[2]  http://en.wikipedia.org/wiki/Ping
[3]  http://en.wikipedia.org/wiki/Internet_Control_Message_Protocol
[4]  http://www.boost.org/doc/libs/1_45_0/doc/html/boost_asio.html
[5]  http://www.boost.org/doc/libs/1_45_0/doc/html/program_options.html