From: Guilherme Maciel Ferreira Date: Thu, 28 Apr 2011 09:44:10 +0000 (+0200) Subject: Split Readme file. X-Git-Tag: v1.0~64 X-Git-Url: http://developer.intra2net.com/git/?a=commitdiff_plain;h=afdd699de368c4fb547aa94acfb88fd2799eba91;p=pingcheck Split Readme file. - code conventions moved to Readme.code --- diff --git a/Readme b/Readme index 4487cc1..3d4efbe 100644 --- a/Readme +++ b/Readme @@ -1,10 +1,9 @@ Table of Contents ======================================= 1. Introduction -2. Code Conventions -3. Source Code -4. Configuration File -5. References +2. Configuration File +3. Command line +4. References @@ -42,129 +41,14 @@ 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 +2. 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 +2.1. General --------------------------------------- This configurations are shared among and affect all the hosts. - source-network-interface: the local network interface from where the ping @@ -185,7 +69,7 @@ This configurations are shared among and affect all the hosts. in order to consider the link up, or stable. -4.2. Host +2.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 @@ -194,7 +78,16 @@ This configurations are shared among and affect all the hosts. -5. References +3. Command line +======================================= +The command line accepts the general configuration file options plus the +following: +- config-file: command line to specify a file where the hosts and other + configuration information are provided. + + + +4. References ======================================= [1] http://tools.ietf.org/html/rfc792 [2] http://en.wikipedia.org/wiki/Ping diff --git a/Readme.code b/Readme.code new file mode 100644 index 0000000..dda9fcf --- /dev/null +++ b/Readme.code @@ -0,0 +1,122 @@ + Table of Contents +======================================= +1. Code Conventions +2. Source Code + + + +1. Code Conventions +======================================= +This section describes the code conventions that must be followed when maintain +this code. + + +1.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. + + +1.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 + + +1.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. + + +1.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. + + +1.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. + + + +2. Source Code +======================================= +In this section is presented an overview of the source code and key design +decisions. + + +2.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. + + +2.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(); + + +