err.texi

来自「开放gsl矩阵运算」· TEXI 代码 · 共 440 行 · 第 1/2 页

@code{GSL_ERROR} macro in the file @file{gsl_errno.h}.

@c @noindent
@c Here is a skeleton outline of a program which defines its own error
@c handler.  Imagine that the program does interactive data analysis --
@c there is a main loop which reads commands from the user and calls
@c library routines with user-supplied arguments,

@c @example
@c #include <setjmp.h>
@c #include <gsl/gsl_errno.h>

@c jmp_buf main_loop;
@c void my_error_handler (const char *reason, const char *file, int line);

@c main ()
@c @{
@c    gsl_set_error_handler (&my_error_handler);

@c    while (1) 
@c      @{
@c        .... /* read command from user */

@c        if (setjmp (main_loop) == 0)
@c          @{
@c             .... /* call GSL routines requested by user */
@c          @}
@c        else 
@c          @{
@c             .... /* my_error_handler bailed out, GSL gave an error */
@c          @}
@c      @}
@c @}

@c void
@c my_error_handler (const char *reason, const char *file, int line)
@c @{
@c     fprintf (stderr, "GSL error: %s\n", reason);
@c     longjmp (main_loop, 1);
@c @}
@c @end example

@c @noindent
@c Before entering the interactive loop the program uses
@c @code{gsl_set_error_handler} to provide its own error handler
@c @code{my_error_handler} for GSL error reports.  After this point the
@c function @code{my_error_handler} will be invoked whenever an error is
@c reported by GSL. The new error handler prints the cause of the error
@c (the string @code{reason}) and then does a non-local jump back to the
@c main loop.  This would allow the user to fix the command which
@c caused the error and try again.

@comment @node Error streams
@comment @section Error streams
@comment 
@comment GSL supports the concert of an error stream, which is a place where
@comment errors are logged as they occur.  An error stream allows the library to
@comment report an error message directly to the user rather than to the calling
@comment program.  This can sometimes be useful because it reduces the amount of
@comment error checking that the program needs to do.
@comment 
@comment For example, many mathematical functions compute floating point numbers
@comment or other numerical values.  The standard versions of these functions
@comment accept a pointer for storing their numerical result, so that the status
@comment can be returned separately.  For example, to compute the first-order
@comment Bessel function @math{J_1(x)} for @math{x=1.23} and obtain the status we
@comment write,
@comment 
@comment @example
@comment double result;
@comment int status = gsl_sf_bessel_J1_e (1.23, &result);
@comment @end example
@comment @comment 
@comment @noindent
@comment where @code{gsl_sf_bessel_J1_e} is the appropriate function from the
@comment special functions (@code{sf}) module.  The suffix @code{_e} appended to
@comment the function name indicates that the return value gives the error
@comment status.  This style of function is safe and avoids any confusion about
@comment what the return value means, but requires a lot of error checking. 
@comment 
@comment For many numerical functions it would be more intuitive to write
@comment something like @math{y = f(x)}.  The library provides functions with
@comment an alternative interface which allows this,
@comment 
@comment @example
@comment double result = gsl_sf_bessel_J1 (1.23)
@comment @end example
@comment @comment 
@comment @noindent
@comment However, in this case there is no way for the calling program to test
@comment for an error.  Instead if there are any errors (such as underflow) they
@comment are logged to the error stream, and can be examined by the user at the
@comment end of the run.  It is up to the programmer to decide which form is best
@comment suited to a given application.  For a truly robust program the error
@comment checking versions of the functions should be used, since they don't rely
@comment on the user examining the error stream.
@comment 
@comment @node Manipulating the error stream
@comment @section Manipulating the error stream
@comment 
@comment By default the error stream is sent to @code{stderr}, and you can
@comment redirect it to a file on the command line.  There are also two ways to
@comment change this within your program.  Firstly, the stream can be redirected
@comment to another file by providing a suitable file pointer.  Alternatively you
@comment can set up an error stream handler, which is a function that accepts
@comment error message strings.  By using an error stream handler function you
@comment have complete control over where the messages are stored.
@comment 
@comment @deftypefun {FILE *} gsl_set_stream (FILE * @var{new_stream})
@comment This function selects the stream used for GSL error messages.  After
@comment calling @code{gsl_set_stream} any further messages sent to the default
@comment stream handler will be printed on @var{new_stream}.  The previous stream
@comment is returned, so that you can close it or restore it later.  Note that the
@comment stream is stored in a static variable, so there can only be one error
@comment stream per program.
@comment @end deftypefun
@comment 
@comment @deftp {Data Type} gsl_stream_handler_t
@comment This is the type of GSL stream handler functions. A stream handler will
@comment be passed four arguments, specifying a label (such as @sc{error} or
@comment @sc{warning}), the source file in which the error occurred, the line
@comment number in that file and a description of the error.  The source file and
@comment line number are set at compile time using the @code{__FILE__} and
@comment @code{__LINE__} directives in the preprocessor. A stream handler
@comment function returns type @code{void}.  Stream handler functions should be
@comment defined like this,
@comment 
@comment @example
@comment void @var{handler} (const char * label, const char * file,
@comment               int line, const char * reason)
@comment @end example
@comment @end deftp
@comment 
@comment To request the use of your own stream handler you need to call the
@comment function @code{gsl_set_stream_handler} which is also declared in
@comment @file{gsl_errno.h},
@comment 
@comment @deftypefun gsl_stream_handler_t gsl_set_stream_handler (gsl_stream_handler_t @var{new_handler})
@comment 
@comment This functions sets a new stream handler, @var{new_handler}, for the GSL
@comment library routines.  The previous handler is returned (so that you can
@comment restore it later).  Note that the pointer to a user defined stream
@comment handler function is stored in a static variable, so there can only be
@comment one error handler per program.
@comment 
@comment @example
@comment old_handler = gsl_set_stream_handler (&my_error_stream); 
@comment 
@comment .....     /* code uses new handler */
@comment 
@comment gsl_set_stream_handler (old_handler); /* restore old handler */
@comment @end example
@comment 
@comment @noindent
@comment To use the default behavior (print the message to @code{stderr}) set the stream
@comment handler to @code{NULL},
@comment 
@comment @example
@comment old_handler = gsl_set_stream_handler (NULL); 
@comment @end example
@comment @end deftypefun

@node Using GSL error reporting in your own functions
@section Using GSL error reporting in your own functions
@cindex error handling macros
If you are writing numerical functions in a program which also uses GSL
code you may find it convenient to adopt the same error reporting
conventions as in the library.

To report an error you need to call the function @code{gsl_error} with a
string describing the error and then return an appropriate error code
from @code{gsl_errno.h}, or a special value, such as @code{NaN}.  For
convenience the file @file{gsl_errno.h} defines two macros which carry
out these steps:

@deffn {Macro} GSL_ERROR (@var{reason}, @var{gsl_errno})

This macro reports an error using the GSL conventions and returns a
status value of @code{gsl_errno}.  It expands to the following code fragment,

@example
gsl_error (reason, __FILE__, __LINE__, gsl_errno);
return gsl_errno;
@end example

@noindent
The macro definition in @file{gsl_errno.h} actually wraps the code
in a @code{do @{ ... @} while (0)} block to prevent possible
parsing problems.
@end deffn

Here is an example of how the macro could be used to report that a
routine did not achieve a requested tolerance.  To report the error the
routine needs to return the error code @code{GSL_ETOL}.

@example
if (residual > tolerance) 
  @{
    GSL_ERROR("residual exceeds tolerance", GSL_ETOL);
  @}
@end example

@deffn {Macro} GSL_ERROR_VAL (@var{reason}, @var{gsl_errno}, @var{value})

This macro is the same as @code{GSL_ERROR} but returns a user-defined
status value of @var{value} instead of an error code.  It can be used for
mathematical functions that return a floating point value.
@end deffn

Here is an example where a function needs to return a @code{NaN} because
of a mathematical singularity,

@example
if (x == 0) 
  @{
    GSL_ERROR_VAL("argument lies on singularity", 
                  GSL_ERANGE, GSL_NAN);
  @}
@end example