%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  handlers.tex        LiDIA documentation
%%  
%%  This file contains the documentation of LiDIA's handlers
%%  
%%  Copyright (c) 1995 by the LiDIA Group
%%  
%%  Authors: Thomas Papanikolaou
%%  

\begin{lidia_man}
\markright{\BF{system\_handlers}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\NAME
\BF{system handlers} \DOTFILL warning, error, memory and debug handlers

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\ABSTRACT
\LiDIA's system handlers are functions which allow easy
warning, error, memory and debug handling in \LiDIA\  programs.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\DESCRIPTION
In the following let \TT{xxx} stand for \TT{lidia\_warning, lidia\_error,
lidia\_memory} or \TT{lidia\_debug}. A \TT{xxx\_handler} in \LiDIA\  consists
of three parts:


\fcode{void}{default\_xxx\_handler}{}
{
this is the function which realizes the handling proposed by
the \LiDIA\ system. For example, the \TT{default\_error\_handler}
prints an error message and then exits the program.}


\fcode{{xxx\_handler\_ptr}}{xxx\_handler}{}
{
this is a pointer which by default points to the
\TT{default\_xxx\_handler}.}


\fcode{{xxx\_handler\_ptr}}{set\_xxx\_handler}{xxx\_handler\_ptr}
{
this is a function which allows to replace the default handler
by a user-defined handler. The new handler must have the type
\TT{xxx\_handler\_ptr}.}

According to the description above, the following handlers are 
available:


\begin{verbatim}
typedef void (*error_handler_ptr)(char *, char *);
error_handler_ptr lidia_error_handler;

\end{verbatim}

The \IndexSUBTT{system\_handlers}{lidia\_error\_handler} must be
called with two character pointers (strings). The first string
should include the name of the class in which the error occured
and the second the exact position and the description of the
error. The \TT{lidia\_error\_handler} produces an error message
of the format

\begin{center}
\TT{lidia\_error\_handler::classname::exact position and description}
\end{center}

and exits using \TT{abort()}.

An extended version of \TT{lidia\_error\_handler} is 
\TT{lidia\_error\_handler\_c}. This function must be called with
two character pointers and a non-empty, valid piece of C++ code
(commas are not allowed in this code). On call, it executes the
code and the \TT{lidia\_error\_handler}. \TT{lidia\_error\_handler\_c}
is implemented by the macro


\begin{verbatim}
 #define lidia_error_handler_c(f, m, code)\
 { code; lidia_error_handler(f, m); }

\end{verbatim}

The \TT{lidia\_warning\_handler} and the \TT{lidia\_debug\_handler} work in the
same way but in contrast to the \TT{error\_handler} they do not
abort execution. To include warning and debug handling
in \LiDIA, the following compilation flags have to be defined
before building the library:

\centerline{\TT{-DLIDIA\_WARNINGS -DLIDIA\_DEBUG=level}}

\TT{level} can be any integer greater than zero. The greater the
\TT{level} the less debug information will be produced on
execution. The default value of \TT{LIDIA\_DEBUG} is 1
(print all debug information).


\begin{verbatim}
 #define debug_handler(file, msg)\
 lidia_debug_handler(file, msg)

 #define debug_handler_l(file, msg, level)\
 if (LIDIA_DEBUG <= level)\
 lidia_debug_handler(file, msg)

 #define debug_handler_c(name, msg, level, code)\
 { if (LIDIA_DEBUG <= level)\
 lidia_debug_handler(name, msg);\
 code; }

\end{verbatim}

Finally, the \BF{memory\_handler} is intented to be used as a
check after allocating vectors of objects. Therefore, it has an
additional pointer argument (the vector the user tried to
allocate). If the allocation was not successful (memory exhausted),
a message is printed and the program aborts execution.
Otherwise no message is printed. Again, to allow memory handling
in \LiDIA, it is necessary to define the compilation flag 

\centerline{\TT{-DLIDIA\_MEMORY}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\SEEALSO
UNIX manual page abort(3)

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\WARNINGS
The compilation flags \TT{LIDIA\_WARNINGS}, \TT{LIDIA\_DEBUG} and
\TT{LIDIA\_MEMORY} must be defined before compiling \LiDIA.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\EXAMPLES
\begin{verbatim}
 #include <LiDIA/error.h>
 #include <LiDIA/memory.h>

 int main()
 {

   char *s;

   if (1 != (2 - 1))
     lidia_error_handler("main()", "if::math. error");

   s = new char[100000];

   memory_handler(s, "main()", "allocating 100000 chars");

 }
\end{verbatim}	

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\AUTHOR
Thomas Papanikolaou

\end{lidia_man}


