2053 lines
73 KiB
Text
2053 lines
73 KiB
Text
\input texinfo @c -*-texinfo-*-
|
|
|
|
@c $Id: chf.texi,v 2.2 2001/01/25 12:06:29 cibrario Exp $
|
|
@c %**start of header
|
|
@setfilename chf.info
|
|
@settitle Chf library (libChf r2.2) Documentation
|
|
@setchapternewpage on
|
|
@iftex
|
|
@afourpaper
|
|
@end iftex
|
|
@c %**end of header
|
|
|
|
@ifinfo
|
|
This manual documents the Condition Handling Facility library (libChf r2.2).
|
|
|
|
The Chf library provides a centralized, unified method of generating and
|
|
signaling exceptional conditions, establishing exception handlers, and
|
|
printing status and error messages.
|
|
@end ifinfo
|
|
|
|
@titlepage
|
|
@title CHF library Documentation
|
|
@subtitle Condition Handling Facility library
|
|
@subtitle (libChf r2.2)
|
|
@author Ivan Cibrario B.
|
|
@end titlepage
|
|
|
|
@node Top, Overview, (dir), (dir)
|
|
|
|
@ifinfo
|
|
This manual describes the Condition Handling Facility library, and
|
|
applies to its release 2.2.
|
|
@end ifinfo
|
|
|
|
@menu
|
|
* Overview::
|
|
* Initialization and exit::
|
|
* Condition generation and signal::
|
|
* General condition handling::
|
|
* Structured condition handling::
|
|
* Chf conditions::
|
|
* Message retrieval::
|
|
* Multithreading support::
|
|
* Other useful macro definitions::
|
|
* Other useful functions::
|
|
* Changes since release 1::
|
|
* Changes since release 2.1::
|
|
* Function Index::
|
|
* Data Type Index::
|
|
* Concept Index::
|
|
|
|
@c @detailmenu --- The Detailed Node Listing ---
|
|
|
|
Initialization and exit
|
|
|
|
* ChfInit()::
|
|
* ChfMsgcatInit()::
|
|
* ChfStaticInit()::
|
|
* ChfWin32Init()::
|
|
* ChfExit()::
|
|
* ChfAbort()::
|
|
* Library header::
|
|
|
|
Condition generation and signal
|
|
|
|
* Generating a condition::
|
|
* Signaling a condition::
|
|
|
|
Generating a condition
|
|
|
|
* ChfCondition::
|
|
* ChfEnd::
|
|
* ChfSeverity::
|
|
* ChfErrnoCondition::
|
|
|
|
Signaling a condition
|
|
|
|
* ChfSignal()::
|
|
|
|
Condition handling
|
|
|
|
* Condition handlers::
|
|
* Condition descriptors::
|
|
* Condition handling state::
|
|
* Handler actions::
|
|
* Default handler::
|
|
|
|
Condition handlers
|
|
|
|
* ChfHandler::
|
|
* ChfPushHandler()::
|
|
* ChfPopHandler()::
|
|
|
|
Structured condition handling
|
|
|
|
* Syntax of structured condition handlers::
|
|
* Chf behavior during structured condition handling::
|
|
|
|
Chf behavior during structured condition handling
|
|
|
|
* ChfTry::
|
|
* ChfCatch::
|
|
* ChfEndTry::
|
|
|
|
Message retrieval
|
|
|
|
* Retrieving a message::
|
|
* Reserved module identifiers::
|
|
* Defining a new message retrieval subsystem::
|
|
|
|
Retrieving a message
|
|
|
|
* ChfGetMessage()::
|
|
* ChfBuildMessage()::
|
|
|
|
@c @end detailmenu
|
|
@end menu
|
|
|
|
@node Overview, Initialization and exit, Top, Top
|
|
@chapter Overview
|
|
@cindex Overview
|
|
@cindex Win32 Support
|
|
|
|
The Condition Handling facility library
|
|
provides a centralized, unified method of generating and
|
|
signaling exceptional conditions. This method can be used either in
|
|
conjunction with, or in alternative to, the traditional style of handling
|
|
error conditions by returning distinguished error values when an error
|
|
occurs in a procedure, and checking for these values after each procedure
|
|
invocation.
|
|
|
|
It serves many different purposes:
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
It helps to gather and make available as much information as possible when
|
|
an error occurs, such as which source module detected it, its severity,
|
|
and any other ancillary information the user may find useful.
|
|
|
|
@item
|
|
It provides an unified method to log and print error messages, and to
|
|
internationalize applications.
|
|
|
|
@item
|
|
By means of condition handlers, it gives the user a convenient way to
|
|
implement global exception recovery actions in an application.
|
|
|
|
@item
|
|
It may improve the readability of the source code, because less explicit
|
|
checks for error conditions are required.
|
|
|
|
@end itemize
|
|
|
|
Since release @code{2.2}, the Chf library also supports Unicode-based Win32
|
|
systems, notably Windows CE. Implementation details of the Win32 version
|
|
of the library will be discussed in the documentation, and will be
|
|
highlighted by the @strong{Win32} keyword. Moreover, the following
|
|
general notes apply:
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
All library functions, when compiled for Win32, handle Unicode
|
|
character strings (array of @code{TCHAR}) instead of ASCII strings
|
|
(array of @code{char}); this change is transparent and the documentation
|
|
does not reflect it.
|
|
|
|
@item
|
|
Library functions @code{sigsetjmp()} and @code{siglongjmp()} are not
|
|
supported; accordingly, they are replaced by
|
|
@code{setjmp()} and @code{longjmp()}. The non-local control transfer
|
|
context buffer, @code{sigjmp_buf} is also replaced by @code{jmp_buf};
|
|
this change is transparent and the documentation does not reflect it.
|
|
|
|
@item
|
|
The reentrant flavor of the Chf library is not yet supported. Multithreaded
|
|
application must serialize Chf accesses themselves.
|
|
|
|
@item
|
|
The @code{ChfErrnoCondition} macro is not supported, and has no effect.
|
|
|
|
@item
|
|
The default condition handler does not display the condition message
|
|
on the standard error stream.
|
|
|
|
@item
|
|
The @code{CHF_ABORT} initialization flag is not fully supported;
|
|
when used, the Chf library invokes @code{exit(EXIT_FAILURE)}
|
|
instead of @code{abort()} (not supported by Win32) to abort the application.
|
|
|
|
@end itemize
|
|
|
|
The following terms will be used often throughout this document:
|
|
|
|
@table @code
|
|
@item Exception
|
|
@cindex Exception
|
|
An @dfn{exception} is an event that changes the normal flow of instruction
|
|
execution, and is usually caused by an error condition. Any procedure can
|
|
generate an exception using the @code{ChfGenerate} macro, and then
|
|
raise or signal it using the @code{ChfSignal()} function call.
|
|
|
|
@item Condition
|
|
@cindex Condition
|
|
An informational state which exists when an exception occurs, and encloses
|
|
information about the exception itself. The term @dfn{condition} is preferred,
|
|
since the term exception usually implies an error.
|
|
|
|
@item Condition handling
|
|
@cindex Condition handling
|
|
When a condition is detected during the execution of a procedure, the
|
|
procedure can signal the condition. The
|
|
hierarchy of currently active condition handlers is then permitted to
|
|
respond to the condition; the procedure response is called
|
|
@dfn{condition handling}.
|
|
|
|
The condition handlers are themselves procedures and they are called
|
|
with the usual calling conventions; the only exception is that, in the
|
|
current release of the Chf library, they cannot establish condition
|
|
handlers of their own.
|
|
|
|
A procedure can establish a condition handler using the function
|
|
@code{ChfPushHandler()}, that pushes a new condition handler on top of
|
|
a LIFO handler stack; the condition handler stays active until a
|
|
matching call to @code{ChfPopHandler()}, that pops the topmost handler
|
|
from the handler stack is executed, or until an execution stack
|
|
unwind occurs.
|
|
|
|
Another way to implicitly establishing and removing condition handlers
|
|
is to use the structured condition handling macros.
|
|
@xref{Structured condition handling}, for more information.
|
|
|
|
@end table
|
|
|
|
@node Initialization and exit, Condition generation and signal, Overview, Top
|
|
@chapter Initialization and exit
|
|
@cindex Initialization and exit
|
|
@cindex Initialization
|
|
@cindex Exit
|
|
|
|
Before using any function of the Chf library, it must be correctly
|
|
initialized. Since the library has a generic interface towards the
|
|
message retrieval subsystem (@pxref{Message retrieval}),
|
|
more than one initialization function exist, one each for every message
|
|
retrieval subsystem the library supports, plus one custom initialization
|
|
function to use if a custom message retrieval subsystem is used.
|
|
After initialization, the library accesses the message retrieval subsystem
|
|
transparently, and its peculiarities are no longer visible to the users.
|
|
|
|
All initialization functions, when successful, register a default condition
|
|
handler. @xref{Default handler}.
|
|
|
|
Moreover, each module using the Chf library must include the header file
|
|
@code{Chf.h} and provide some basic definitions. @xref{Library header}.
|
|
|
|
@menu
|
|
* ChfInit()::
|
|
* ChfMsgcatInit()::
|
|
* ChfStaticInit()::
|
|
* ChfWin32Init()::
|
|
* ChfExit()::
|
|
* ChfAbort()::
|
|
* Library header::
|
|
@end menu
|
|
|
|
@node ChfInit(), ChfMsgcatInit(), Initialization and exit, Initialization and exit
|
|
@section ChfInit()
|
|
@cindex Initialization
|
|
@deftypefn Function int ChfInit (const char *app_name, const ChfOptions options, void *mrs_data, ChfMrsGet mrs_get, ChfMrsExit mrs_exit, const int condition_stack_size, const int handler_stack_size, const int exit_code)
|
|
|
|
This function initializes the Chf library using a custom message retrieval
|
|
subsystem, and returns to the caller a condition code; that code will be either
|
|
@code{CHF_S_OK} if the initialization was successful, or one of the other
|
|
values listed below.
|
|
|
|
Arguments:
|
|
|
|
@table @code
|
|
@item app_name
|
|
is the name of the application. It can be used by condition
|
|
handlers to print out error messages.
|
|
|
|
@item options
|
|
is the bitwise or of the following option identifiers:
|
|
|
|
@table @code
|
|
|
|
@item CHF_DEFAULT
|
|
Represents the default value for all options.
|
|
|
|
@item CHF_ABORT
|
|
If this flag is set, the Chf library will use @code{abort()} instead of
|
|
either @code{exit(exit_code)} or @code{pthread_exit(exit_code)} to abort
|
|
the application when an unrecoverable exception occurs. This forces a
|
|
core dump that may be useful for debugging purposes.
|
|
|
|
@strong{Win32:} This flag is not fully supported; the Chf library
|
|
invokes @code{exit(EXIT_FAILURE)} instead of @code{abort()} (not
|
|
supported by Win32) to abort the application.
|
|
|
|
@end table
|
|
|
|
@item mrs_data
|
|
Private data pointer for the custom message retrieval subsystem.
|
|
|
|
@item mrs_get
|
|
Message retrieval subsystem's 'Get Message' function.
|
|
|
|
@item mrs_exit
|
|
Message retrieval subsystem's 'Exit' function.
|
|
|
|
@item condition_stack_size
|
|
Size of the condition stack. This value determines the maximum number of
|
|
pending conditions, i.e. conditions that have been generated but have
|
|
not been signaled yet. A condition that is being signaled is
|
|
still pending until the signaling sequence completes.
|
|
|
|
@item handler_stack_size
|
|
Size of the handler stack. This value determines the maximum number of
|
|
active condition handlers the application can have. A condition handler is
|
|
activated when a @code{ChfPushHandler()} is executed for it, and it is
|
|
deactivated when the corresponding @code{ChfPopHandler()} completes.
|
|
In addition, each execution of the @code{ChfTry} macro also pushes
|
|
a condition handler; the handler is removed when @code{ChfEndTry}
|
|
is executed.
|
|
|
|
@item exit_code
|
|
This is the exit code the Chf library will use to exit either the
|
|
application or the offending thread when an unrecoverable exception
|
|
occurs.
|
|
|
|
@end table
|
|
|
|
Return values:
|
|
|
|
@table @code
|
|
|
|
@item CHF_S_OK
|
|
The Chf library has been successfully initialized.
|
|
|
|
@item CHF_F_MALLOC
|
|
Dynamic memory allocation failed during initialization.
|
|
|
|
@end table
|
|
|
|
Notes:
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
It's necessary to invoke successfully @code{ChfInit()}, either directly
|
|
or indirectly, through another Chf initialization function, before using
|
|
any other Chf function; otherwise, they will either fail and abort the
|
|
application (when multithreading support is not enabled), or have
|
|
unpredictable results (when multithreading support is enabled).
|
|
|
|
@item
|
|
This function will call @code{ChfAbort()} with abort code
|
|
@code{CHF_ABORT_DUP_INIT} if the Chf library has already been initialized
|
|
before. Notice that when multithreading support is enabled, @code{ChfInit()}
|
|
must be invoked only once before starting multithreaded operation.
|
|
|
|
@end itemize
|
|
@end deftypefn
|
|
|
|
@node ChfMsgcatInit(), ChfStaticInit(), ChfInit(), Initialization and exit
|
|
@section ChfMsgcatInit()
|
|
@cindex Initialization
|
|
@cindex Internationalization
|
|
@deftypefn Function int ChfMsgcatInit (const char *app_name, const ChfOptions options, const char *msgcat_name, const int condition_stack_size, const int handler_stack_size, const int exit_code)
|
|
|
|
This function initializes the Chf library and activates the message retrieval
|
|
subsystem based on @code{catgets()}, offering support for
|
|
text-based internationalized applications.
|
|
|
|
The argument @code{msgcat_name} is the name of the application/locale
|
|
specific message catalog to be used to retrieve the messages. The other
|
|
arguments have the meaning already described for @code{ChfInit()},
|
|
@xref{ChfInit()}.
|
|
|
|
@strong{Win32:} This function is not supported and always returns
|
|
@code{CHF_F_NOT_AVAILABLE}.
|
|
|
|
Return values:
|
|
|
|
@table @code
|
|
|
|
@item CHF_S_OK
|
|
The Chf library has been successfully initialized.
|
|
|
|
@item CHF_F_SETLOCALE
|
|
the @code{setlocale()} function has failed during initialization.
|
|
|
|
@item CHF_F_CATOPEN
|
|
the @code{catopen()} function has failed and therefore the message catalog was
|
|
not opened.
|
|
|
|
@item CHF_F_MALLOC
|
|
Dynamic memory allocation failed during initialization.
|
|
|
|
@item CHF_F_NOT_AVAILABLE
|
|
Function not available on current platform.
|
|
|
|
@end table
|
|
|
|
Notes:
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
It's necessary to invoke successfully either @code{ChfMsgcatInit()},
|
|
or another Chf initialization function described in this chapter,
|
|
before using any other Chf function.
|
|
|
|
@item
|
|
This function will call @code{ChfAbort()} with abort code
|
|
@code{CHF_ABORT_DUP_INIT} if the Chf library has already been initialized
|
|
before.
|
|
|
|
@end itemize
|
|
@end deftypefn
|
|
|
|
@node ChfStaticInit(), ChfWin32Init(), ChfMsgcatInit(), Initialization and exit
|
|
@section ChfStaticInit()
|
|
@cindex Initialization
|
|
@deftypefn Function int ChfStaticInit (const char *app_name, const ChfOptions options, const ChfTable *table, const size_t table_size, const int condition_stack_size, const int handler_stack_size, const int exit_code)
|
|
|
|
This function initializes the Chf library and activates the static
|
|
message retrieval subsystem using the message table @code{table},
|
|
of @code{table_size} elements. This is the simplest message retrieval
|
|
subsystem currently supported, and supports applications that must work
|
|
with minimal operating system assistance.
|
|
|
|
Return values:
|
|
|
|
@table @code
|
|
|
|
@item CHF_S_OK
|
|
The Chf library has been successfully initialized.
|
|
|
|
@item CHF_F_MALLOC
|
|
Dynamic memory allocation failed during initialization.
|
|
|
|
@end table
|
|
|
|
Notes:
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
It's necessary to invoke successfully either @code{ChfStaticInit()},
|
|
or another Chf initialization function described in this section,
|
|
before using any other Chf function.
|
|
|
|
@item
|
|
This function will call @code{ChfAbort()} with abort code
|
|
@code{CHF_ABORT_DUP_INIT} if the Chf library has already been initialized
|
|
before.
|
|
|
|
@end itemize
|
|
@end deftypefn
|
|
|
|
@deftp {Data type} ChfTable
|
|
@cindex Standalone message table
|
|
This data type is a structure representing an element of a standalone message
|
|
table, to be used with the static message retrieval subsystem. Each table
|
|
element associates a pair (@code{module_id}, @code{code}) with a message
|
|
fragment or template. It has the following fields:
|
|
|
|
@table @code
|
|
@item int module
|
|
The module identifier of the message fragment to be defined.
|
|
|
|
@item int code
|
|
The condition code of the message fragment to be defined.
|
|
|
|
@item char *msg_template
|
|
The message fragment or template associated with
|
|
(@code{module_id}, @code{code}).
|
|
|
|
@end table
|
|
@end deftp
|
|
|
|
@node ChfWin32Init(), ChfExit(), ChfStaticInit(), Initialization and exit
|
|
@section ChfWin32Init()
|
|
@cindex Initialization
|
|
@cindex Internationalization
|
|
@deftypefn Function int ChfWin32Init (const char *app_name, const ChfOptions options, HINSTANCE instance, const int condition_stack_size, const int handler_stack_size, const int exit_code)
|
|
|
|
This function initializes the Chf library and activates the message
|
|
retrieval subsystem based on the Win32 function @code{LoadString()},
|
|
offering limited support for Win32 internationalized applications.
|
|
|
|
This function does not support message sets, so the linear message id
|
|
passed to it is made by @code{module_id*1000 + condition_code}.
|
|
|
|
The @code{instance} argument is the handle of the calling application
|
|
instance; it will be used as an argument to @code{LoadString()}. All
|
|
other arguments have the meaning already described for @code{ChfInit()},
|
|
@xref{ChfInit()}.
|
|
|
|
@strong{Win32:} This function is supported on Win32 only, and always
|
|
returns @code{CHF_F_NOT_AVAILABLE} when invoked on Unix platforms.
|
|
Notice also that on Win32 the @code{ChfAbort()} function will be able to
|
|
print out the abort message only if Chf has been initialized correctly
|
|
and the @code{GetActiveWindow()} function yields a valid window handle
|
|
when @code{ChfAbort()} is invoked.
|
|
|
|
Return values:
|
|
|
|
@table @code
|
|
|
|
@item CHF_S_OK
|
|
The Chf library has been successfully initialized.
|
|
|
|
@item CHF_F_MALLOC
|
|
Dynamic memory allocation failed during initialization.
|
|
|
|
@item CHF_F_NOT_AVAILABLE
|
|
Function not available on current platform.
|
|
|
|
@end table
|
|
|
|
Notes:
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
It's necessary to invoke successfully either @code{ChfWin32Init()},
|
|
or another Chf initialization function described in this chapter,
|
|
before using any other Chf function.
|
|
|
|
@item
|
|
This function will call @code{ChfAbort()} with abort code
|
|
@code{CHF_ABORT_DUP_INIT} if the Chf library has already been initialized
|
|
before.
|
|
|
|
@end itemize
|
|
@end deftypefn
|
|
|
|
@node ChfExit(), ChfAbort(), ChfWin32Init(), Initialization and exit
|
|
@section ChfExit()
|
|
@cindex Exit
|
|
@deftypefn Function void ChfExit (void)
|
|
|
|
This function shuts down the Chf library and returns nothing to the caller;
|
|
after calling @code{ChfExit()} the application can continue, but any
|
|
subsequent call to other Chf functions,
|
|
except to the initialization functions, will either abort
|
|
the application using @code{ChfAbort()} with abort code @code{CHF_ABORT_INIT}
|
|
(when multithreading support is not enabled) or have unpredictable results
|
|
(when multithreading support is enabled).
|
|
|
|
Notes:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
This function will call @code{ChfAbort()} with abort code @code{CHF_ABORT_INIT}
|
|
if Chf hasn't been initialized yet.
|
|
|
|
@item
|
|
When multithreading support is enabled, it is responsibility of the
|
|
application designer to ensure that no other Chf functions,
|
|
except initialization functions, will be
|
|
called after this function has been.
|
|
@end itemize
|
|
@end deftypefn
|
|
|
|
@node ChfAbort(), Library header, ChfExit(), Initialization and exit
|
|
@section ChfAbort()
|
|
@cindex Abort
|
|
@deftypefn Function void ChfAbort (const int abort_code)
|
|
This function prints the message associated with @code{abort_code} and
|
|
then immediately aborts either the application or the invoking
|
|
thread. The abort is performed either:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
using @code{abort()} if either Chf has not been correctly initialized
|
|
yet, or the Chf option flag @code{CHF_ABORT} has been set during
|
|
initialization. Since this is mainly intended to be a debugging aid,
|
|
@code{abort()} is used whether or not multithreading support is enabled.
|
|
@strong{Win32:} The @code{CHF_ABORT} flag is not fully supported; when
|
|
this flag is set the Chf library invokes @code{exit(EXIT_FAILURE)} instead
|
|
of @code{abort()} (not supported by Win32) to abort the application.
|
|
@item
|
|
using either @code{exit(exit_code)} or @code{pthread_exit(exit_code)}
|
|
if the above mentioned flag is clear. The former function is used when
|
|
multithreading support is not enabled, the latter when it is. The
|
|
argument @code{exit_code} is the value of the @code{exit_code} argument
|
|
given to the Chf initialization function.
|
|
@end itemize
|
|
|
|
The following abort messages are currently defined:
|
|
|
|
@table @code
|
|
@item "Not initialized"
|
|
The Chf library has not been correctly initialized.
|
|
@item "Temporary message buffer overflow"
|
|
The temporary message buffer used by Chf to combine the additional condition
|
|
arguments with the message template was overflowed. Shorten the message.
|
|
@item "Invalid action from last chance handler"
|
|
The condition handler registered first, that usually is the default
|
|
condition handler, has returned an invalid action code.
|
|
@item "Already initialized"
|
|
One of the Chf initialization functions was called when Chf was already
|
|
initialized.
|
|
@item "Unwind request while unwinding"
|
|
A condition handler has requested an unwind action when Chf was already
|
|
unwinding. This is not allowed.
|
|
@item "Improperly handled condition"
|
|
No condition handlers were able to properly handle the current condition
|
|
group. This should not occur if the default condition handler is active
|
|
as the last chance handler.
|
|
@item "Fatal condition while unwinding"
|
|
A fatal condition was signaled while Chf was unwinding. This is not
|
|
allowed because is would require another unwind to be recovered.
|
|
@item "Condition stack overflow"
|
|
An attempt was made to generate a condition while the Chf condition
|
|
CHF_F_COND_STACK_FULL (condition stack full) was being signaled.
|
|
@item "Can't prime a new Chf context"
|
|
Chf was unable to clone the master Chf context when a thread
|
|
first attempted to access its context. This message is generated
|
|
only when multithreading support is enabled.
|
|
@item "Pthread interaction failed"
|
|
An unrecoverable error occurred when Chf invoked a @code{pthread}
|
|
function. This message is generated only when multithreading support
|
|
is enabled.
|
|
@end table
|
|
|
|
No message is printed if the @code{abort_code} is @code{CHF_ABORT_SILENT};
|
|
this code is used, for example, by the default condition handler to terminate
|
|
the application when a @code{CHF_FATAL} condition occurs.
|
|
|
|
Notes:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
This function is called by other Chf library functions only when they
|
|
detect an unrecoverable failure. Even if it has a public prototype, the user
|
|
should never invoke this function.
|
|
@item
|
|
@strong{Win32:} Since the standard error stream is not available, this
|
|
function is able to display the abort message only if it is able to
|
|
obtain a valid main window handle, that is, if the
|
|
@code{GetActiveWindow()} function yields a valid value when invoked.
|
|
@end itemize
|
|
|
|
@end deftypefn
|
|
|
|
@node Library header, , ChfAbort(), Initialization and exit
|
|
@section Library header
|
|
@cindex Library header
|
|
|
|
The library header @code{Chf.h} must be included by all source modules using
|
|
the Chf library. Prior to include it, the following macro definitions must
|
|
be made:
|
|
|
|
@table @code
|
|
@item CHF_MODULE_ID
|
|
This macro must expand into an integer representing the module identifier
|
|
of the module the source file belongs. The module identifiers with value
|
|
less than 10 are reserved for Chf internal use.
|
|
@xref{Reserved module identifiers}.
|
|
|
|
All conditions generated by the source module will use this module
|
|
identifier. Even if this macro could in principle be redefined through the
|
|
source, it is generally inconvenient to have functions belonging to different
|
|
application's modules in the same source file, so it is discouraged.
|
|
This definition is mandatory.
|
|
|
|
@item CHF_EXTENDED_INFO
|
|
If this macro is set, all conditions generated by the source module
|
|
will include the file name and the line number as additional information
|
|
items. This can be useful for debugging purposes. This definition is
|
|
optional.
|
|
@end table
|
|
|
|
@strong{Win32:} The @code{tchar.h} system header must be included
|
|
before including @code{Chf.h}.
|
|
|
|
@node Condition generation and signal, General condition handling, Initialization and exit, Top
|
|
@chapter Condition generation and signal
|
|
@cindex Condition generation and signal
|
|
|
|
@menu
|
|
* Generating a condition::
|
|
* Signaling a condition::
|
|
@end menu
|
|
|
|
@node Generating a condition, Signaling a condition, Condition generation and signal, Condition generation and signal
|
|
@section Generating a condition
|
|
@cindex Generating a condition
|
|
|
|
When an unusual or noteworthy condition occurs, the application may generate
|
|
a condition that describes it.
|
|
|
|
@menu
|
|
* ChfCondition::
|
|
* ChfEnd::
|
|
* ChfSeverity::
|
|
* ChfErrnoCondition::
|
|
@end menu
|
|
|
|
@node ChfCondition, ChfEnd, Generating a condition, Generating a condition
|
|
@subsection ChfCondition
|
|
@deftypefn Macro {} ChfCondition {...}
|
|
|
|
This macro starts the definition of a condition using the current
|
|
application's module specifier @code{CHF_MODULE_ID}; it must be followed by
|
|
these additional, mandatory, arguments:
|
|
|
|
@table @code
|
|
@item int condition_code
|
|
This argument is the condition code; it uniquely identifies a condition
|
|
within the scope of the current application's module.
|
|
|
|
@item ChfSeverity severity
|
|
This value represents the severity of the condition. @xref{ChfSeverity}.
|
|
@end table
|
|
|
|
Moreover, zero or more additional argument can follow; they will be
|
|
immediately combined with the message template corresponding to the
|
|
pair (@code{CHF_MODULE_ID}, @code{condition_code}) using @code{sprintf()}.
|
|
All format specifiers of the latter function are allowed in the message
|
|
template.
|
|
|
|
As stated before, the message template is retrieved using the message
|
|
retrieval subsystem (@pxref{Message retrieval}) using the current Chf
|
|
module identifier @code{CHF_MODULE_ID} as the message set, and the
|
|
condition code @code{condition_code} as the message number.
|
|
|
|
If in the condition stack there isn't any condition yet, a new condition group
|
|
is created, otherwise the new condition is linked on top of the current
|
|
condition group. The condition stack supports multiple nested condition
|
|
groups for use in condition handlers: any condition generated inside a
|
|
condition handler starts a new condition group that can be individually
|
|
handled and signaled.
|
|
|
|
This function calls the Chf function @code{ChfAbort()} if one of the following
|
|
unrecoverable error condition occurs:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Chf has not been initialized correctly (abort code @code{CHF_ABORT_INIT})
|
|
|
|
@item
|
|
there is an overflow in the internal buffer used during the
|
|
generation of the partial message associated with the condition
|
|
(abort code @code{CHF_ABORT_MSG_OVF})
|
|
|
|
@item
|
|
there was an attempt to generate a condition while the Chf condition
|
|
@code{CHF_F_COND_STACK_FULL} (condition stack full) was being signaled
|
|
(abort code @code{CHF_ABORT_COND_STACK_OVF})
|
|
|
|
@end itemize
|
|
@end deftypefn
|
|
|
|
|
|
@node ChfEnd, ChfSeverity, ChfCondition, Generating a condition
|
|
@subsection ChfEnd
|
|
@deftypefn Macro {} ChfEnd
|
|
|
|
This macro terminates the generation of the condition, started
|
|
with @code{ChfCondition}; it must be followed by @code{;}. For example:
|
|
|
|
@example
|
|
ChfCondition
|
|
<condition_code>, <severity>, <additional_info>
|
|
ChfEnd;
|
|
@end example
|
|
|
|
@end deftypefn
|
|
|
|
@c 2.1, cibrario, 26-May-2000
|
|
@c Expanded description of severity codes
|
|
@node ChfSeverity, ChfErrnoCondition, ChfEnd, Generating a condition
|
|
@subsection ChfSeverity
|
|
@deftp {Data type} ChfSeverity
|
|
The severity code of a condition is an enumerated type, and can assume one
|
|
of the following values:
|
|
|
|
@table @code
|
|
@item CHF_SUCCESS
|
|
This condition represents the successful completion of an application's
|
|
action; when generated in an application's module it is usually signaled
|
|
immediately after generation, it is not reported to the module caller
|
|
and does not disrupt the normal control flow of the application.
|
|
|
|
@item CHF_INFO
|
|
This condition conveys an information message to the application's user,
|
|
but it in no way represents an error indication; when generated in an
|
|
application's module it is usually signaled immediately after
|
|
generation, it is not reported to the module caller and does not disrupt
|
|
the normal control flow of the application.
|
|
|
|
@item CHF_WARNING
|
|
This condition has been generated to warn the application's user that a
|
|
potentially abnormal situation occurred, but the application's module
|
|
was able to complete successfully the action that was requested to it,
|
|
perhaps incompletely. It is usually not signaled immediately after
|
|
generation, it is reported to the caller using some status reporting
|
|
mechanism, and it requires only a minimal, local disruption of the
|
|
control flow of the application to be recovered.
|
|
|
|
@item CHF_ERROR
|
|
An error occurred and the application's module was not able to complete its
|
|
work, but it still may be possible to perform a local recovery and resume the
|
|
normal application's control flow. It is usually not signaled immediately
|
|
after generation and it is reported to the caller using some status
|
|
reporting mechanism.
|
|
|
|
@item CHF_FATAL
|
|
A fatal error occurred, and a global recovery action is required, because
|
|
the normal application's control flow can't be safely resumed. The Chf library
|
|
enforces that, when @code{ChfSignal()} is called with a fatal condition, the
|
|
control will never return to the instruction following the @code{ChfSignal()}
|
|
call. It is usually signaled immediately after generation.
|
|
|
|
@end table
|
|
@end deftp
|
|
|
|
@node ChfErrnoCondition, , ChfSeverity, Generating a condition
|
|
@subsection ChfErrnoCondition
|
|
@deftypefn Macro {} ChfErrnoCondition
|
|
|
|
This macro generates a condition from the current value of the @code{errno}
|
|
variable. The module identifier of the condition is set to the special
|
|
value @code{CHF_ERRNO_SET}. The severity is always @code{CHF_ERROR}.
|
|
|
|
@strong{Win32:} This macro is not supported and has no effect when invoked.
|
|
|
|
@end deftypefn
|
|
|
|
|
|
@node Signaling a condition, , Generating a condition, Condition generation and signal
|
|
@section Signaling a condition
|
|
@cindex Signaling a condition
|
|
|
|
A condition already generated with one of the macros discussed in the
|
|
previous section can be signaled using the following function, that starts
|
|
the condition signaling sequence.
|
|
|
|
@menu
|
|
* ChfSignal()::
|
|
@end menu
|
|
|
|
@node ChfSignal(), , Signaling a condition, Signaling a condition
|
|
@subsection ChfSignal()
|
|
@cindex ChfSignal()
|
|
@deftypefn Function void ChfSignal (void)
|
|
@end deftypefn
|
|
|
|
This function signals the current condition group. If the final action
|
|
requested by the condition handlers invoked during the signaling operation
|
|
was @code{CHF_CONTINUE} and the overall severity of the condition group
|
|
was lower than @code{CHF_FATAL}, this function will return to the caller,
|
|
otherwise either a non-local control transfer will occur (@code{CHF_UNWIND})
|
|
or the invoking application/thread will be terminated.
|
|
|
|
During the signaling of a condition group the following actions are
|
|
accomplished:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
First of all, a check is made to ensure that the Chf subsystem has been
|
|
correctly initialized. If not, the function @code{ChfAbort} is called.
|
|
@item
|
|
The state of Chf is changed to @code{CHF_SIGNALING} if it was @code{CHF_IDLE},
|
|
and to @code{CHF_SIGNAL_UNWINDING} if it was @code{CHF_UNWINDING}.
|
|
@item
|
|
If there is not any active condition group, the function does nothing more,
|
|
restores the saved Chf state and returns to the caller.
|
|
@item
|
|
If there is an active condition group, the currently active condition handlers
|
|
are invoked, starting from the one registered last.
|
|
@item
|
|
Each condition handler can recursively invoke @code{ChfGenerate()} and
|
|
@code{ChfSignal()}. @code{ChfGenerate()}, when invoked, will create a new
|
|
condition group, and @code{ChfSignal()} will signal the condition group
|
|
just created.
|
|
@item
|
|
When the Chf state is @code{CHF_SIGNALING}, any new condition group generated
|
|
but not yet signaled when the current handler exits is merged
|
|
with the condition group currently being signaled, in order to allow
|
|
the condition handlers to add their own conditions to the condition
|
|
group. If the severity of the previous condition group was @code{CHF_FATAL},
|
|
the severity of the new group is forced to @code{CHF_FATAL}, too.
|
|
When the Chf state is @code{CHF_UNWINDING}, the condition group for
|
|
which the unwind has been requested is 'frozen', no further
|
|
modifications are allowed on it, and the new condition group is simply
|
|
discarded.
|
|
@item
|
|
The condition handlers calling sequence terminates when either the handler
|
|
stack is exhausted (all condition handlers have been called) or when an
|
|
handler requests either the action @code{CHF_CONTINUE},
|
|
@code{CHF_UNWIND} or @code{CHF_UNWIND_KEEP}.
|
|
Please note that the @code{CHF_CONTINUE} action cannot be requested if
|
|
the severity of the condition group is @code{CHF_FATAL}; when this occurs,
|
|
the action is automatically changed to @code{CHF_RESIGNAL} instead.
|
|
@item
|
|
If the action @code{CHF_CONTINUE} has been requested and it is allowed, Chf
|
|
discards the current condition group, restored the saved Chf state and
|
|
returns to the instruction following the call to @code{ChfSignal()}, that
|
|
started the signaling activities.
|
|
@item
|
|
If either one of the actions @code{CHF_UNWIND} or @code{CHF_UNWIND_KEEP}
|
|
has been requested and it is allowed, that is,
|
|
no other unwinds are already in progress, the current Chf state is set
|
|
to @code{CHF_UNWINDING} and all handlers that were registered
|
|
after the handler that requested the unwind are called again, starting
|
|
from the one registered last, so that they can perform any final cleanup
|
|
operation they require for proper operation. The handler that requested
|
|
the unwind is called again, too, in the same fashion. Immediately after
|
|
this, the unwinded condition handlers are removed from the handler stack
|
|
and discarded, the current condition group and any other group generated
|
|
after it are destroyed, the Chf state is changed back to @code{CHF_IDLE}
|
|
and a non-local control transfer is executed through a
|
|
@code{siglongjmp()}, using the @code{unwind_context} associated with the
|
|
handler that requested the unwind as target. The @code{ChfSignal()}
|
|
invocation that started the signaling activities will never return to
|
|
the caller. If the requested action is @code{CHF_UNWIND_KEEP} everything
|
|
goes as described above, except that the current condition group and
|
|
any other group generated after it are @strong{not} destroyed, so they can
|
|
still be accessed after the non-local control transfer has taken place.
|
|
@item
|
|
If no handlers were able to handle the condition, the invoking
|
|
application/thread is terminated with @code{ChfAbort()}.
|
|
@item
|
|
If an handler returned an invalid action code and it is not the condition
|
|
handler that was registered first, a new condition group is generated and
|
|
immediately signaled, containing the condition @code{CHF_F_INVALID_ACTION}
|
|
with module identifier @code{CHF_SET}.
|
|
@end itemize
|
|
|
|
@c 2.1, cibrario, 18-May-2000
|
|
@c Renamed 'condition handling' -> 'general condition handling'
|
|
@node General condition handling, Structured condition handling, Condition generation and signal, Top
|
|
@chapter Condition handling
|
|
@cindex Condition handling
|
|
|
|
@menu
|
|
* Condition handlers::
|
|
* Condition descriptors::
|
|
* Condition handling state::
|
|
* Handler actions::
|
|
* Default handler::
|
|
@end menu
|
|
|
|
@node Condition handlers, Condition descriptors, General condition handling, General condition handling
|
|
@section Condition handlers
|
|
@cindex Condition handlers
|
|
|
|
The Chf library maintains a LIFO stack of active condition handlers. Each
|
|
condition handler is a function which has type @code{ChfHandler}.
|
|
Moreover, the functions described below are available to push and pop
|
|
a condition handler to/from the condition handler stack.
|
|
|
|
@menu
|
|
* ChfHandler::
|
|
* ChfPushHandler()::
|
|
* ChfPopHandler()::
|
|
@end menu
|
|
|
|
@node ChfHandler, ChfPushHandler(), Condition handlers, Condition handlers
|
|
@subsection ChfHandler
|
|
@cindex ChfHandler
|
|
@deftp {Data Type} ChfHandler
|
|
|
|
The condition handler data type is defined as follows:
|
|
|
|
@example
|
|
typedef /* Condition handler */
|
|
ChfAction (*ChfHandler)(
|
|
const ChfDescriptor *,
|
|
const ChfState,
|
|
ChfPointer
|
|
);
|
|
@end example
|
|
|
|
The condition handler receives the following arguments when invoked:
|
|
|
|
@table @code
|
|
|
|
@item const ChfDescriptor *
|
|
is a pointer to the condition group that is being signaled.
|
|
|
|
@item const ChfState
|
|
represents the current state of the condition handling facility.
|
|
|
|
@item ChfPointer
|
|
is a copy of the @code{handler_context} pointer passed to the
|
|
@code{ChfPushHandler()} invocation that established the condition
|
|
handler.
|
|
|
|
@end table
|
|
|
|
The handler must return an action code, represented by a value
|
|
of type @code{ChfAction}.
|
|
|
|
Before returning, the condition handler can generate other conditions,
|
|
without signaling them, with the purpose of better specify the current
|
|
condition group; these conditions will be added on top of the current
|
|
group when the handler returns. The next handler, if any, will be invoked
|
|
on the updated condition group.
|
|
|
|
The severity @code{CHF_FATAL} is 'sticky', that is, any new condition
|
|
linked to a condition group where the topmost condition has that
|
|
severity will be forced to the same severity level.
|
|
|
|
If the condition handler itself generates and signals a new condition
|
|
group, its superior condition handlers will be invoked on the new
|
|
condition group only. When the new signaling sequence is completed,
|
|
the old sequence will be resumed if appropriate, i.e. if a superior
|
|
handler has requested the @code{CHF_CONTINUE} action and the severity
|
|
of the new condition group allows it to do so.
|
|
|
|
@end deftp
|
|
|
|
|
|
@node ChfPushHandler(), ChfPopHandler(), ChfHandler, Condition handlers
|
|
@subsection ChfPushHandler()
|
|
@cindex Condition handlers
|
|
@cindex Adding condition handlers
|
|
@deftypefn Function void ChfPushHandler (ChfHandler new_handler, void *unwind_context, ChfPointer handler_context)
|
|
|
|
This function pushes the new condition handler @code{new_handler} with
|
|
its associated @code{siglongjmp()} context, pointed by
|
|
@code{unwind_context}, into the handler stack. If @code{new_handler} is
|
|
@code{CHF_NULL_HANDLER}, the special builtin structured condition
|
|
handling helper is pushed; see @ref{Structured condition handling}, for
|
|
further information.
|
|
|
|
Moreover, this function saves a copy of the opaque pointer
|
|
@code{handler_context}; it will be passed to @code{new_handler} upon each
|
|
subsequent activation, and therefore can be used as a private handler context
|
|
pointer. The user must ensure that the information pointed by
|
|
@code{handler_context}, if any, will remain valid until @code{new_handler}
|
|
is popped from the condition stack.
|
|
|
|
The pointer @code{handler_context} may be set to the special (null) value
|
|
@code{CHF_NULL_POINTER} to indicate that the handler hasn't any private
|
|
context information.
|
|
|
|
If, in the future, the handler will request the @code{CHF_UNWIND}
|
|
action, the @code{sigsetjmp()} function invocation that established
|
|
@code{unwind_context} will appear to return again.
|
|
|
|
The pointer @code{unwind_context} can be the reserved (null) pointer
|
|
@code{CHF_NULL_CONTEXT}; in this case, if the handler will request the
|
|
@code{CHF_UNWIND} action, the invoking application/thread will be
|
|
silently terminated calling @code{ChfAbort()} with abort code
|
|
@code{CHF_ABORT_SILENT}.
|
|
|
|
If an error occurs during the execution, the function generates
|
|
and immediately signals one of the conditions listed below; the function
|
|
will never return directly to the caller, since all conditions have
|
|
severity @code{CHF_FATAL}.
|
|
|
|
@table @code
|
|
|
|
@item CHF_F_BAD_STATE
|
|
Bad Chf state for requested operation. A new handler can be added to the
|
|
handler stack only if the condition handling subsystem is idle.
|
|
|
|
@item CHF_F_HDLR_STACK_FULL,
|
|
The handler stack is full and the new handler can't be added.
|
|
|
|
@end table
|
|
|
|
Notes:
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
This function will call @code{ChfAbort()} with abort code @code{CHF_ABORT_INIT}
|
|
if Chf hasn't been initialized.
|
|
|
|
@end itemize
|
|
@end deftypefn
|
|
|
|
@node ChfPopHandler(), , ChfPushHandler(), Condition handlers
|
|
@subsection ChfPopHandler()
|
|
@cindex Condition handlers
|
|
@cindex Removing condition handlers
|
|
@deftypefn Function void ChfPopHandler (void)
|
|
|
|
This function pops the topmost condition handler from the handler stack and
|
|
returns to the caller.
|
|
|
|
If an error occurs during the execution, the function generates
|
|
and immediately signals one of the conditions listed below; the function
|
|
will never return directly to the caller, since all conditions have
|
|
severity @code{CHF_FATAL}.
|
|
|
|
@table @code
|
|
|
|
@item CHF_F_BAD_STATE
|
|
Bad Chf state for requested operation. Handlers can be removed from the
|
|
handler stack only if the condition handling subsystem is idle.
|
|
|
|
@item CHF_F_HDLR_STACK_EMPTY
|
|
The handler stack is empty.
|
|
|
|
@end table
|
|
|
|
Notes:
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
This function will call @code{ChfAbort()} with abort code @code{CHF_ABORT_INIT}
|
|
if Chf hasn't been initialized.
|
|
|
|
@end itemize
|
|
|
|
@end deftypefn
|
|
|
|
|
|
@node Condition descriptors, Condition handling state, Condition handlers, General condition handling
|
|
@section Condition descriptors
|
|
@cindex Condition descriptors
|
|
@deftp {Data Type} ChfDescriptor
|
|
|
|
The condition descriptor contains all information Chf has about a
|
|
condition code. Its fields must not be accessed directly, but using
|
|
the macros the Chf library provides for this purpose.
|
|
|
|
@end deftp
|
|
|
|
The following macros are provided to access a condition descriptor:
|
|
|
|
@deftypefn Macro {ChfDescriptor *} ChfGetNextDescriptor (Chf Descriptor *d)
|
|
@cindex Next condition descriptor
|
|
|
|
Returns to the caller the condition descriptor that hierarchically
|
|
follows @code{d} in the current condition group, or the special
|
|
value @code{CHF_NULL_DESCRIPTOR} if @code{d} is the last descriptor of the
|
|
group.
|
|
|
|
@end deftypefn
|
|
|
|
@deftypefn Macro int ChfGetModuleId (Chf Descriptor *d)
|
|
@cindex Module identifier
|
|
|
|
Returns to the caller the identifier of the module that generated
|
|
the condition @code{d}.
|
|
|
|
@end deftypefn
|
|
|
|
@deftypefn Macro int ChfGetConditionCode (Chf Descriptor *d)
|
|
@cindex Condition Code
|
|
|
|
Returns to the caller the condition code of the condition @code{d}.
|
|
|
|
@end deftypefn
|
|
|
|
@deftypefn Macro ChfSeverity ChfGetSeverity (Chf Descriptor *d)
|
|
@cindex Severity
|
|
|
|
Returns to the caller the severity level of the condition @code{d}.
|
|
@xref{ChfSeverity}.
|
|
|
|
@end deftypefn
|
|
|
|
@deftypefn Macro int ChfGetLineNumber (Chf Descriptor *d)
|
|
@cindex Line number
|
|
|
|
Returns to the caller the source line number where the condition @code{d}
|
|
was generated. This piece of information is available only if the
|
|
Chf compile-time option @code{CHF_EXTENDED_INFO} was set when the source
|
|
file that generated the condition was compiled, otherwise the special
|
|
value @code{CHF_UNKNOWN_LINE_NUMBER} is returned instead.
|
|
|
|
@end deftypefn
|
|
|
|
@deftypefn Macro {const char *} ChfGetFileName (Chf Descriptor *d)
|
|
@cindex File name
|
|
|
|
Returns to the caller the file name where the condition @code{d}
|
|
was generated. This piece of information is available only if the
|
|
Chf compile-time option @code{CHF_EXTENDED_INFO} was set when the source
|
|
file that generated the condition was compiled, otherwise the special
|
|
value @code{CHF_UNKNOWN_FILE_NAME} is returned instead.
|
|
|
|
@end deftypefn
|
|
|
|
@deftypefn Macro {char *} ChfGetPartialMessage (Chf Descriptor *d)
|
|
@cindex Partial condition message
|
|
|
|
Returns to the caller the partial condition message that was associated
|
|
with the condition @code{d} when it was generated. The partial condition
|
|
message contains the result of the execution of @code{sprintf()} using
|
|
the message template associated with the condition as format, and the
|
|
ancillary condition arguments as additional arguments.
|
|
|
|
@end deftypefn
|
|
|
|
|
|
|
|
@node Condition handling state, Handler actions, Condition descriptors, General condition handling
|
|
@section Condition handling state
|
|
@cindex Condition handling state
|
|
@deftp {Data Type} ChfState
|
|
This enumerated type describes the current state of the Condition Handling
|
|
Facility. It can have one of the following values:
|
|
|
|
@table @code
|
|
@item CHF_UNKNOWN
|
|
The Chf library has not been initialized, or the initialization has failed.
|
|
Normally, the user never sees this value, because the main use of
|
|
@code{ChfState} values is inside condition handlers, and they are never
|
|
invoked when the Chf library has not been initialized correctly.
|
|
|
|
@item CHF_IDLE
|
|
This is the normal state of the condition handling facility. In this state,
|
|
the condition stack contains zero or more condition descriptors corresponding
|
|
to conditions that have been generated but have not been signaled yet.
|
|
The application follows its normal control flow.
|
|
|
|
@item CHF_SIGNALING
|
|
The Condition Handling Facility is invoking the hierarchy of active
|
|
condition handlers because @code{ChfSignal()} has been invoked with a
|
|
non-empty condition stack. None of the condition handlers invoked so far
|
|
has requested an unwind operation.
|
|
|
|
@item CHF_UNWINDING
|
|
The Condition Handling Facility is unwinding one or more condition handlers,
|
|
because another, superior, handler has requested an unwind operation.
|
|
All handlers being unwinded are called once with Chf in this state to allow
|
|
them to perform any final cleanup operation, and immediately after that
|
|
they are removed from the condition stack. During unwind,
|
|
the action code returned by the handler being unwinded is ignored.
|
|
|
|
@item CHF_SIGNAL_UNWINDING
|
|
While Chf was performing an unwind operation, one of the handlers being
|
|
unwinded has signaled another condition group. The superiors of the
|
|
signaling handler are invoked with Chf in this state, then the unwind
|
|
operation is resumed.
|
|
|
|
@end table
|
|
@end deftp
|
|
|
|
@node Handler actions, Default handler, Condition handling state, General condition handling
|
|
@section Handler actions
|
|
@cindex Handler actions
|
|
@deftp {Data Type} ChfAction
|
|
|
|
Enumerated type representing the set of mutually exclusive actions that a
|
|
condition handler can request to the condition handling facility. It can
|
|
have the following values:
|
|
|
|
@table @code
|
|
|
|
@item CHF_CONTINUE
|
|
Resume the application from the instruction immediately following the
|
|
@code{ChfSignal()} call that triggered the invocation of the condition handler.
|
|
This action is not allowed if the severity of the current condition is
|
|
@code{CHF_FATAL}, since this severity always requires global recovery
|
|
to take place. In this case the @code{CHF_CONTINUE} is automatically
|
|
changed to @code{CHF_RESIGNAL} when encountered.
|
|
|
|
@item CHF_RESIGNAL
|
|
Invoke the next handler in the handler stack with the same condition.
|
|
This action must be used when the current condition handler was not able
|
|
to recover the condition.
|
|
|
|
@item CHF_UNWIND
|
|
Unwind the application's stack and restore the @code{unwind_context}
|
|
associated with the condition handler, performing a non-local control
|
|
transfer. @xref{ChfPushHandler()}.
|
|
|
|
@c 2.1, cibrario, 18-May-2000
|
|
@c Added descruption of CHF_UNWIND_KEEP
|
|
@item CHF_UNWIND_KEEP
|
|
Unwind the application's stack and restore the @code{unwind_context}
|
|
associated with the condition handler, performing a non-local control
|
|
transfer. Unlike @code{CHF_UNWIND}, the current condition group
|
|
at the time of the unwind is @strong{not} destroyed,
|
|
and can still be accessed after the non-local control transfer has
|
|
taken place.
|
|
@end table
|
|
@end deftp
|
|
|
|
@node Default handler, , Handler actions, General condition handling
|
|
@section Default handler
|
|
@cindex Default handler
|
|
|
|
The default condition handler of Chf is automatically
|
|
pushed into the condition handler stack by the Chf initialization
|
|
functions. It performs the following functions:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
if called during an unwind, it returns immediately to the caller,
|
|
requesting the action @code{CHF_RESIGNAL}, else
|
|
|
|
@item
|
|
if the severity of the condition being signaled is greater than
|
|
@code{CHF_SUCCESS}, it prints the messages associated with the entire
|
|
condition group on stderr using the standard function
|
|
@code{ChfBuildMessage()} to build the messages.
|
|
@strong{Win32: } Since the standard error stream is not available,
|
|
the default handler does not print anything out.
|
|
|
|
@item
|
|
if the severity of the condition being signaled is less than
|
|
@code{CHF_FATAL}, it returns to the caller requesting the action
|
|
@code{CHF_CONTINUE}, else
|
|
|
|
@item
|
|
if the @code{CHF_FATAL} condition was @strong{not} signaled during an unwind
|
|
operation, it returns to the caller requesting the action
|
|
@code{CHF_UNWIND}, otherwise it requests the action @code{CHF_RESIGNAL}.
|
|
|
|
@end itemize
|
|
|
|
@c 2.1, cibrario, 18-May-2000
|
|
@c New chapter: Structured condition handling
|
|
@node Structured condition handling, Chf conditions, General condition handling, Top
|
|
@chapter Structured condition handling
|
|
@cindex Structured condition handling
|
|
|
|
Structured condition handling places the condition handler associated
|
|
with a block of code next to the block itself, instead of into a separate
|
|
procedure. Even if it is less flexible and powerful with respect to the
|
|
general handling method described before, it is often clearer and
|
|
simpler to implement. Chf supports both styles of condition handling;
|
|
the structured condition handling is layered above the general one.
|
|
|
|
@menu
|
|
* Syntax of structured condition handlers::
|
|
* Chf behavior during structured condition handling::
|
|
@end menu
|
|
|
|
@node Syntax of structured condition handlers, Chf behavior during structured condition handling, Structured condition handling, Structured condition handling
|
|
@section Syntax of structured condition handlers
|
|
@cindex Syntax of structured condition handlers
|
|
|
|
The syntax establishing a structured condition handler is as follows:
|
|
|
|
@example
|
|
ChfTry
|
|
@{
|
|
... body ...
|
|
@}
|
|
ChfCatch
|
|
@{
|
|
const ChfDescriptor *exc = ChfGetTopCondition();
|
|
... condition handler ...
|
|
@}
|
|
ChfEndTry;
|
|
@end example
|
|
|
|
The macros @code{ChfTry}, @code{ChfCatch} and @code{ChfEndTry}
|
|
expand as follows:
|
|
|
|
@example
|
|
<<
|
|
@{
|
|
sigjmp_buf _chf_sigjmp_buf;
|
|
if(sigsetjmp(_chf_sigjmp_buf, 1) == 0)
|
|
@{
|
|
ChfPushHandler(CHF_NULL_HANDLER, _chf_sigjmp_buf, CHF_NULL_POINTER);
|
|
>>
|
|
@{
|
|
... body ...
|
|
@}
|
|
<<
|
|
ChfPopHandler();
|
|
@}
|
|
else
|
|
@{
|
|
>>
|
|
@{
|
|
const ChfDescriptor *exc = ChfGetTopCondition();
|
|
... condition handler ...
|
|
@}
|
|
<<
|
|
ChfDiscard();
|
|
@}
|
|
@}
|
|
>>
|
|
@end example
|
|
|
|
Above, @code{<<} and @code{>>} mark the starting and ending point of
|
|
each macro expansion, respectively.
|
|
|
|
The @code{body} is either a statement or a block of statements (a block
|
|
is shown in the example) to be protected. If an exception with severity
|
|
equal to @code{CHF_FATAL} is signaled during the execution of
|
|
@code{body}, control is transferred to the @code{condition handler}
|
|
following @code{ChfCatch}.
|
|
|
|
The handler can then retrieve the condition group associated with the
|
|
exception using @code{ChfGetTopCondition()}, as shown in the example,
|
|
and must perform one of the following actions:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Handle the exception; when the condition handler completes, that is, its
|
|
last statement has been executed, the current condition group is
|
|
automatically discarded and control is transferred to the code that
|
|
follows @code{ChfEndTry}.
|
|
@item
|
|
Resignal the exception, possibly after adding one or more conditions to
|
|
it; in this case, the handler explicitly calls @code{ChfSignal()}.
|
|
In response, Chf continues to search for a handler that actually
|
|
handles the exception, in the @code{ChfTry}/@code{ChfCatch} blocks
|
|
enclosing the current one, in inner to outer order. The control
|
|
will never be returned to the resignaling handler.
|
|
@end itemize
|
|
|
|
Notice that it is not possible for the condition handler to resume
|
|
the thread of execution disrupted by the exception. Resuming is
|
|
possible only when the signaled condition has severity less than
|
|
@code{CHF_FATAL}: in this case the @code{condition handler} is
|
|
not invoked, the usual condition signaling sequence takes place
|
|
and the @code{CHF_CONTINUE} action requested by any general
|
|
condition handler is honored.
|
|
|
|
Thus, structured condition handling is further simplified because:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Conditions with severity less than @code{CHF_WARNING} are usually
|
|
automatically signaled immediately after generation and are not reported
|
|
to the caller; they are informational conditions only, and they must not
|
|
disrupt the normal control flow of the application. Accordingly, the
|
|
structured condition handler is @strong{not} invoked when a
|
|
success/informational condition is signaled in its @code{ChfTry} body.
|
|
@item
|
|
@code{CHF_WARNING} conditions generated by a module are usually not
|
|
signaled immediately after generation, but are reported to the
|
|
caller using some status reporting mechanism. When a warning
|
|
condition is generated by a module, it indicates that its execution
|
|
has been at least partially successful; this usually means that
|
|
the disruption of the control flow of the application can be kept to
|
|
a minimum and handled locally. Accordingly, the structured condition
|
|
handler is @strong{not} invoked when a warning condition
|
|
is signaled in its @code{ChfTry} body.
|
|
@item
|
|
@code{CHF_ERROR} conditions generated by a module indicate that the
|
|
module execution has been unsuccessful; they are usually reported to the
|
|
caller using some status reporting mechanisms. An error condition
|
|
indicates that a significant disruption of the control flow of the
|
|
application is required to recover, and that local handling is still
|
|
possible but could not suffice. Accordingly, the structured condition
|
|
handler is @strong{not} invoked when an error condition is signaled in
|
|
its @code{ChfTry} body. Notice also that if the @code{ChfTry} body is
|
|
not able to locally recover the condition, it can add a @code{CHF_FATAL}
|
|
condition to the condition group and signal the modified group, thus
|
|
triggering the invocation of the structured condition handler.
|
|
@item
|
|
@code{CHF_FATAL} conditions are usually signaled immediately after
|
|
generation and always require a global recovery action.
|
|
Accordingly, the structured condition handler is
|
|
invoked when a warning condition is signaled in its @code{ChfTry} body.
|
|
@end itemize
|
|
|
|
Notice also that control is transferred to the structured exception
|
|
handler by means of a @code{siglongjmp()} sequence. Therefore,
|
|
if the structured exception handler needs to access automatic
|
|
variables, they should be declared @code{volatile}.
|
|
|
|
If no handlers are able to handle an exception, the default Chf
|
|
condition handler is invoked last. @xref{Default handler}, for a more
|
|
detailed description of its operation.
|
|
|
|
If no exceptions are raised during the execution of @code{body},
|
|
the @code{condition handler} is skipped and execution continues
|
|
immediately after @code{ChfEndTry}.
|
|
|
|
@node Chf behavior during structured condition handling, , Syntax of structured condition handlers, Structured condition handling
|
|
@section Chf behavior during structured condition handling
|
|
@cindex Chf behavior during structured condition handling
|
|
|
|
When a condition is signaled and the special structured condition
|
|
handling helper is invoked, the following sequence of events occurs:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Chf transitions to state @code{CHF_SIGNALING} and starts
|
|
the handler calling sequence.
|
|
@item
|
|
If any handler invoked before the structured condition handling helper
|
|
requests either the @code{CHF_CONTINUE} or the @code{CHF_UNWIND}
|
|
action, that action is executed as usual.
|
|
@item
|
|
When invoked, the structured condition handling helper immediately
|
|
requests the action @code{CHF_UNWIND_KEEP}.
|
|
@item
|
|
Chf transitions to state @code{CHF_UNWINDING} and invokes all handlers
|
|
registered after the structured condition handling helper again. Such
|
|
handlers can then perform whatever final cleanup operations they need.
|
|
@item
|
|
Chf invokes the structured condition handling helper again; the helper
|
|
immediately returns without doing anything, since Chf is now in state
|
|
@code{CHF_UNWINDING}.
|
|
@item
|
|
Chf transitions to the @code{CHF_IDLE} state and performs a non-local
|
|
control transfer to the structured condition handler's unwind context;
|
|
this corresponds to the code that follows @code{ChfCatch}.
|
|
The current condition group is not removed from the condition stack.
|
|
@item
|
|
Since the current condition group has not been removed from the
|
|
condition stack, the code that follows @code{ChfCatch} can freely
|
|
access the condition group using @code{ChfGetTopCondition()}
|
|
and @code{ChfGetNextDescriptor()}.
|
|
@item
|
|
If any new condition is generated in this phase, it is merged with the
|
|
current condition group; the condition group can be re-signaled at will
|
|
by invoking @code{ChfSignal()}.
|
|
@item
|
|
Immediately after the code that follows @code{ChfCatch} completes,
|
|
@code{ChfDiscard()} is automatically invoked to remove the topmost
|
|
condition group from the stack.
|
|
@end itemize
|
|
|
|
If the structured condition handling helper is invoked when Chf is in
|
|
@code{CHF_SIGNAL_UNWINDING}, it immediately requests the
|
|
@code{CHF_RESIGNAL} action, because a further unwind request is neither
|
|
allowed nor useful in this case.
|
|
|
|
The structured condition handling helper makes no use of
|
|
@code{handler_context}.
|
|
|
|
In summary, the following structured condition handling macros
|
|
are currently available:
|
|
|
|
@menu
|
|
* ChfTry::
|
|
* ChfCatch::
|
|
* ChfEndTry::
|
|
@end menu
|
|
|
|
@node ChfTry, ChfCatch, Chf behavior during structured condition handling, Chf behavior during structured condition handling
|
|
@subsection ChfTry
|
|
@deftypefn Macro {} ChfTry {...}
|
|
|
|
This macro introduces a new structured condition handling body.
|
|
The body is either a statement or a block of statements to be
|
|
protected: if a @code{CHF_FATAL} exception is signaled during its
|
|
execution, control is transferred to the condition handling code
|
|
following @code{ChfCatch}.
|
|
|
|
@end deftypefn
|
|
|
|
@node ChfCatch, ChfEndTry, ChfTry, Chf behavior during structured condition handling
|
|
@subsection ChfCatch
|
|
@deftypefn Macro {} ChfCatch {...}
|
|
|
|
This macro must follow @code{ChfTry} and introduces a new structured
|
|
condition handler following it; the handler can be either a statement or
|
|
a block of statements. If a @code{CHF_FATAL} exception is signaled
|
|
during the execution of the body protected by @code{ChfTry}, control is
|
|
transferred to the condition handling code following @code{ChfCatch}.
|
|
|
|
@end deftypefn
|
|
|
|
@node ChfEndTry, , ChfCatch, Chf behavior during structured condition handling
|
|
@subsection ChfEndTry
|
|
@deftypefn Macro {} ChfEndTry
|
|
|
|
This macro marks the end of a body/condition handler pair.
|
|
|
|
@end deftypefn
|
|
|
|
|
|
@node Chf conditions, Message retrieval, Structured condition handling, Top
|
|
@chapter Chf conditions
|
|
@cindex Chf conditions
|
|
|
|
The Chf library can itself generate and signal the following conditions.
|
|
All conditions are fatal, i.e. require a global recovery action to take
|
|
place to be handled.
|
|
|
|
@deftypefn Macro {} CHF_F_COND_STACK_FULL
|
|
The user attempted to generate a condition while the condition stack was full;
|
|
this condition is generated anyway using a reserved stack entry.
|
|
No additional conditions can be generated until the handling of this condition
|
|
is completed, otherwise the application will be aborted.
|
|
@end deftypefn
|
|
|
|
@deftypefn Macro {} CHF_F_HDLR_STACK_FULL
|
|
The function @code{ChfPushHandler()} was called while the handler stack
|
|
was full; the new handler is not registered and this condition is signaled
|
|
using the old handler hierarchy.
|
|
@end deftypefn
|
|
|
|
@deftypefn Macro {} CHF_F_HDLR_STACK_EMPTY
|
|
A function requiring at least one condition handler to be active
|
|
found an empty handler stack.
|
|
@end deftypefn
|
|
|
|
@deftypefn Macro {} CHF_F_BAD_STATE
|
|
The current state of Chf was not appropriate to invoke a certain
|
|
Chf function. The invoked function does not do anything but
|
|
signaling this condition.
|
|
@end deftypefn
|
|
|
|
@deftypefn Macro {} CHF_F_INVALID_ACTION
|
|
During the current signaling sequence an handler returned an invalid
|
|
action code. A new condition group, containing only this condition, is
|
|
generated and immediately signaled. The first handler called to handle
|
|
the new condition group will be the handler registered immediately before
|
|
the faulting one.
|
|
@end deftypefn
|
|
|
|
@deftypefn Macro {} CHF_F_MALLOC
|
|
Many Chf functions dynamically allocate memory. This condition is generated
|
|
and signaled when a dynamic memory allocation attempt failed, and the library
|
|
was unable to recover in another way.
|
|
@end deftypefn
|
|
|
|
@deftypefn Macro {} CHF_F_NOT_AVAILABLE
|
|
The function is not available on the current platform. This condition
|
|
is returned by some Chf initialization functions instead of being
|
|
signaled, because it prevents the Chf subsystem to be initialized and,
|
|
therefore, to function properly.
|
|
@end deftypefn
|
|
|
|
@deftypefn Macro {} CHF_F_SETLOCALE
|
|
The @code{setlocale()} function failed during the initialization of the
|
|
message catalog-based message retrieval subsystem. This condition is returned
|
|
by the Chf initialization function instead of being signaled, because it
|
|
prevents the Chf subsystem to be initialized and, therefore, to function
|
|
properly.
|
|
@end deftypefn
|
|
|
|
@deftypefn Macro {} CHF_F_CATOPEN
|
|
The @code{catopen()} function failed during the initialization of the
|
|
message catalog-based message retrieval subsystem. This condition is returned
|
|
by the Chf initialization function instead of being signaled, because it
|
|
prevents the Chf subsystem to be initialized and, therefore, to function
|
|
properly.
|
|
@end deftypefn
|
|
|
|
|
|
@node Message retrieval, Multithreading support, Chf conditions, Top
|
|
@chapter Message retrieval
|
|
@cindex Message retrieval
|
|
The message retrieval subsystem is responsible to retrieve the message
|
|
fragments needed by the Chf library to generate the messages associated
|
|
with condition codes.
|
|
|
|
Basically, given a message set identifier (that usually has the same value
|
|
as the module identifier for which the condition is being generated) and
|
|
a message number (that usually has the same value as the condition code),
|
|
it must retrieve and return to the caller a suitable message associated
|
|
to it. It the message cannot be found, it must return a default message
|
|
pointer Chf provides.
|
|
|
|
Some module identifiers/message sets are used for special purposes.
|
|
@xref{Reserved module identifiers}.
|
|
|
|
@menu
|
|
* Retrieving a message::
|
|
* Reserved module identifiers::
|
|
* Defining a new message retrieval subsystem::
|
|
@end menu
|
|
|
|
@node Retrieving a message, Reserved module identifiers, Message retrieval, Message retrieval
|
|
@section Retrieving a message
|
|
The following functions directly interact with the message retrieval subsystem:
|
|
|
|
@menu
|
|
* ChfGetMessage()::
|
|
* ChfBuildMessage()::
|
|
@end menu
|
|
|
|
@node ChfGetMessage(), ChfBuildMessage(), Retrieving a message, Retrieving a message
|
|
@subsection ChfGetMessage()
|
|
@deftypefn Function {const char *} ChfGetMessage (const int module_id, const int condition_code, const char *default_message)
|
|
|
|
This function transparently uses the Chf message retrieval subsystem to
|
|
retrieve the message associated with the pair
|
|
(@code{module_id}, @code{condition_code}) and returns a pointer to it.
|
|
The function will return @code{default_message} instead, if it was not able
|
|
to retrieve the message. If @code{module_id==CHF_ERRNO_SET}, the function
|
|
will additionally invoke @code{strerror()}, if necessary, to retrieve the
|
|
message.
|
|
|
|
@strong{Win32:} Since @code{strerror()} is not supported, the additional
|
|
last-chance translation described above cannot be performed.
|
|
|
|
Notes:
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
The returned pointer points to per-thread static storage, which can be
|
|
overwritten by subsequent calls to this function.
|
|
|
|
@end itemize
|
|
@end deftypefn
|
|
|
|
|
|
@node ChfBuildMessage(), , ChfGetMessage(), Retrieving a message
|
|
@subsection ChfBuildMessage()
|
|
@deftypefn Function {char *} ChfBuildMessage (const ChfDescriptor *descriptor)
|
|
|
|
This function builds the message associated with the given condition
|
|
descriptor and returns a pointer to a string containing it.
|
|
|
|
The message has a standard format and provides the following information
|
|
items:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The application's name given to the Chf library during initialization, if
|
|
the condition is the topmost within a condition group; otherwise, the message
|
|
starts with an horizontal tab character.
|
|
@item
|
|
The name of the module that generated the condition.
|
|
@item
|
|
If available, the file name and line number of the source where the condition
|
|
was generated.
|
|
@item
|
|
The severity code of the message.
|
|
@item
|
|
The message associated with the condition code, including any ancillary
|
|
information provided during condition generation.
|
|
@end itemize
|
|
|
|
Notes:
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
This function will call @code{ChfAbort()} with abort code @code{CHF_ABORT_INIT}
|
|
if Chf hasn't been correctly initialized.
|
|
|
|
@item
|
|
The returned pointer points to per-thread static storage, which can be
|
|
overwritten by subsequent calls to this function.
|
|
|
|
@item
|
|
@strong{Win32:} to save space, the application's name and severity code
|
|
are not included in the message.
|
|
|
|
@end itemize
|
|
@end deftypefn
|
|
|
|
@node Reserved module identifiers, Defining a new message retrieval subsystem, Retrieving a message, Message retrieval
|
|
@section Reserved module identifiers
|
|
@cindex Reserved module identifiers
|
|
|
|
The following module identifiers are currently used by the Chf library;
|
|
all module identifiers with value less than 10 are reserved for future use.
|
|
|
|
@table @code
|
|
@item 1
|
|
This module identifier is used as a message set identifier to retrieve the
|
|
names of the other application's modules. In particular, to retrieve the
|
|
name of the application's module @code{m}, the message @code{m} of
|
|
message set @code{1} is retrieved.
|
|
|
|
@item 2
|
|
This module identifier is used to identify the conditions generated by
|
|
the Chf library itself.
|
|
|
|
@item 3
|
|
This module identifier is used as a message set identifier to retrieve the
|
|
messages associated with the @code{errno} error codes. If the retrieve is
|
|
unsuccessful, @code{strerror()} is used instead.
|
|
@end table
|
|
|
|
@strong{Win32:} In addition, the current implementation of the
|
|
message retrieval subsystem on Win32 imposes the following limits:
|
|
@code{0 <= condition_code <= 999}, @code{0 <= module_id <= 64}.
|
|
|
|
|
|
@c 2.1, cibrario, 18-May-2000
|
|
@c Completed section on defining a new mrs
|
|
@node Defining a new message retrieval subsystem, , Reserved module identifiers, Message retrieval
|
|
@section Defining a new message retrieval subsystem
|
|
@cindex Defining a new message retrieval subsystem
|
|
|
|
The Chf library has a generic interface towards the message retrieval
|
|
subsystem (MRS); therefore, any subsystem can be used, provided it follows
|
|
the guidelines described below:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
A copy of the @code{mrs_data} argument of @code{ChfInit()} is passed to
|
|
each MRS function when it is invoked. It can be used to hold a pointer
|
|
to a private MRS data structures.
|
|
@item
|
|
The @code{mrs_get} function has the following arguments:
|
|
@itemize @bullet
|
|
@item
|
|
A copy of the @code{mrs_data} argument of @code{ChfInit()}.
|
|
@item
|
|
An @code{int}, representing the module identifier of the condition message
|
|
template/fragment to be retrieved.
|
|
@item
|
|
An @code{int}, representing the condition code of the condition message
|
|
template/fragment to be retrieved.
|
|
@item
|
|
A @code{char *}, pointing to a default message template/fragment to
|
|
be returned if the message retrieval fails.
|
|
@end itemize
|
|
The function must attempt to retrieve the message template/fragment
|
|
associated with the pair (module identifier, condition code) and return
|
|
it to the caller; if the retrieval fails, the default message must be
|
|
returned instead.
|
|
@item
|
|
The @code{mrs_exit} function is invoked when Chf is about to exit.
|
|
It has as argument a copy of the @code{mrs_data} argument or
|
|
@code{ChfInit()} and must perform any cleanup operation the MRS
|
|
needs. It is guaranteed that no other MRS function will be called
|
|
after a successful invocation of @code{mrs_exit}.
|
|
@item
|
|
When multithreading support is enabled, the MRS must support multiple,
|
|
concurrent invocations made by different application's threads. The same
|
|
value of @code{mrs_data} is common to all threads and cannot be changed
|
|
after initialization.
|
|
@end itemize
|
|
|
|
@c 2.1, cibrario, 18-May-2000
|
|
@c New chapter on multithreading support; revised all other chapters to
|
|
@c take multithreading support into account, too.
|
|
@node Multithreading support, Other useful macro definitions, Message retrieval, Top
|
|
@chapter Multithreading support
|
|
@cindex Multithreading support
|
|
|
|
When compiled appropriately, the Chf library supports multithreading,
|
|
and maintains one Chf context per active thread. Multithreading support
|
|
is enabled when the cpp macro @code{_REENTRANT} is defined.
|
|
|
|
@strong{Win32:} Multitreading support is not provided yet.
|
|
|
|
When multithreading support is enabled, the following modifications
|
|
to the default Chf behavior come into effect:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@code{ChfInit()} no longer initializes the condition stack, the
|
|
condition handler stack and the message buffer immediately; instead, one
|
|
copy of these context elements will be allocated for each active thread
|
|
in the application, when it first invokes any other Chf function.
|
|
Also, per-thread Chf contexts are dynamically destroyed when the
|
|
owning thread terminates.
|
|
@item
|
|
Condition generation and both general and structured condition handling
|
|
work as before inside each application's thread. All threads share the
|
|
same values for @code{condition_stack_size}, @code{handler_stack_size}
|
|
and @code{exit_code}, but are otherwise fully independent with
|
|
respect to condition handling, because each of them has a private
|
|
Chf context.
|
|
@item
|
|
@code{ChfAbort()} no longer exits the whole application when
|
|
the @code{CHF_ABORT} Chf flag not set; instead, it exits the
|
|
invoking thread only.
|
|
@item
|
|
Almost all Chf functions can trigger the @code{CHF_ABORT_GET_CONTEXT}
|
|
and @code{CHF_ABORT_PTHREAD} aborts, if they fail to correctly
|
|
manage dynamic Chf context creation and/or @code{pthread} interactions.
|
|
@item
|
|
All Chf functions, except @code{ChfInit()} and @code{ChfExit()}
|
|
no longer check whether Chf has been correctly initialized or not:
|
|
that check would have been too time-consuming in a multithreaded environment.
|
|
As a consequence, invoking a Chf function when Chf has not been correctly
|
|
initialized has unpredictable effects instead of neatly aborting
|
|
the application with abort code @code{CHF_ABORT_INIT}.
|
|
@item
|
|
The performance of the Chf condition generation and signaling functions
|
|
is likely to decrease, because Chf must retrieve its per-thread context
|
|
dynamically instead of referring to a static storage area.
|
|
@end itemize
|
|
|
|
@node Other useful macro definitions, Other useful functions, Multithreading support, Top
|
|
@chapter Other useful macro definitions
|
|
@cindex Other useful macro definitions
|
|
|
|
@deftypefn Macro {} CHF_MAX_MESSAGE_LENGTH
|
|
Represents the maximum allowable length for condition messages.
|
|
@end deftypefn
|
|
|
|
@deftypefn Macro {} CHF_LIBRARY_ID
|
|
It is a string representing the Chf library identifier; the identifier
|
|
contains also the library release number.
|
|
@end deftypefn
|
|
|
|
@c 2.1, cibrario, 18-May-2000
|
|
@c New macros
|
|
@deftypefn Macro {} CHF_MAJOR_RELEASE_NUMBER
|
|
It is an integer representing the Chf library major release number.
|
|
@end deftypefn
|
|
|
|
@deftypefn Macro {} CHF_MINOR_RELEASE_NUMBER
|
|
It is an integer representing the Chf library minor release number.
|
|
@end deftypefn
|
|
|
|
@deftypefn Macro {} CHF_MODULE_NAMES_SET
|
|
Contains the integer identifier of the message set whose messages are used to
|
|
retrieve the names of the application's modules. It has the value 1.
|
|
@end deftypefn
|
|
|
|
@deftypefn Macro {} CHF_SET
|
|
Contains the integer identifier of the message set containing the condition
|
|
messages Chf uses internally. It has the value 2.
|
|
@end deftypefn
|
|
|
|
@deftypefn Macro {} CHF_ERRNO_SET
|
|
Contains the integer identifier of the message set containing the condition
|
|
messages for @code{errno} codes. It has the value 3.
|
|
@end deftypefn
|
|
|
|
@deftypefn Macro {} ChfChar
|
|
This macro is used to make portable declarations of character variables,
|
|
and is mapped into either @code{char} or @code{TCHAR} depending on the
|
|
platform.
|
|
@end deftypefn
|
|
|
|
@deftypefn Macro {} ChfText (x)
|
|
This macro is used to make portable declarations of character strings,
|
|
and is mapped into either @code{x} or @code{_T(x)} depending on the
|
|
platform.
|
|
@end deftypefn
|
|
|
|
@deftypefn Macro {} ChfSigjmp_buf
|
|
This macro is mapped into either @code{sigjmp_buf} or @code{jmp_buf},
|
|
depending on whether the platform supports @code{sigjmp_buf}
|
|
contexts or not.
|
|
@end deftypefn
|
|
|
|
@deftypefn Macro {} ChfSigsetjmp (x,y)
|
|
This macro is mapped into either @code{sigsetjmp()} or @code{setjmp()},
|
|
depending on whether the platform supports @code{sigjmp_buf}
|
|
contexts or not. In the latter case argument @code{x} is ignored.
|
|
@end deftypefn
|
|
|
|
@deftypefn Macro {} ChfSiglongjmp (x,y)
|
|
This macro is mapped into either @code{siglongjmp()} or @code{longjmp()},
|
|
depending on whether the platform supports @code{sigjmp_buf}
|
|
contexts or not.
|
|
@end deftypefn
|
|
|
|
@node Other useful functions, Changes since release 1, Other useful macro definitions, Top
|
|
@chapter Other useful functions
|
|
@cindex Other useful functions
|
|
|
|
@deftypefn Function void ChfDiscard (void)
|
|
This function discards the topmost condition group currently in the
|
|
condition stack, without signaling it. The function does nothing if
|
|
the condition stack is empty.
|
|
|
|
This function uses the function @code{ChfAbort()} to
|
|
abort the application if Chf has not been initialized correctly
|
|
(abort code @code{CHF_ABORT_INIT}).
|
|
@end deftypefn
|
|
|
|
@deftypefn Function {const ChfDescriptor *} ChfGetTopCondition (void)
|
|
This function returns to the caller a pointer to the topmost condition of
|
|
the current condition group. It generates and immediately signals the
|
|
condition @code{CHF_F_BAD_STATE} if the current condition group is empty.
|
|
|
|
This function can be useful to retrieve the complete description of a
|
|
condition for functions that, when an error occurs, generate a condition
|
|
and return to the caller a generic error indication, such as a distinguished
|
|
return value.
|
|
|
|
The same function can also be useful in a structured exception handler,
|
|
to retrieve the condition descriptor associated with the exception to
|
|
be handled.
|
|
|
|
Notes:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
During condition signaling, Chf creates a new, empty, condition group
|
|
immediately before starting the invocation sequence of the condition
|
|
handlers, as previously described. Therefore
|
|
@code{ChfGetTopCondition()}, when called from a condition handler, will return
|
|
a pointer to the top condition generated during the handling ONLY, if any, and
|
|
NOT to the top condition of the condition group being signaled. The
|
|
latter pointer is directly available, as an argument, to condition
|
|
handlers.
|
|
@item
|
|
When called from a structured exception handler, @code{ChfGetTopCondition()}
|
|
works as expected, that is, it returns a pointer to the top condition of
|
|
the condition group associated with the exception being handled.
|
|
@item
|
|
This function will call @code{ChfAbort()} with abort code @code{CHF_ABORT_INIT}
|
|
if Chf hasn't been correctly initialized.
|
|
@item
|
|
The returned pointer is no longer valid when any other Chf function
|
|
is called after @code{ChfGetTopCondition()}.
|
|
@end itemize
|
|
@end deftypefn
|
|
|
|
@c 2.1, cibrario, 18-May-2000
|
|
@c New chapter on changes since release 1
|
|
@node Changes since release 1, Changes since release 2.1, Other useful functions, Top
|
|
@chapter Changes since release 1
|
|
@cindex Changes since release 1
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Chf now supports structured condition handling.
|
|
@xref{Structured condition handling}.
|
|
@item
|
|
Chf now supports multithreaded applications; each thread has its own Chf
|
|
context. Multithreading support is conditionally enabled by linking a
|
|
multithreaded version of the Chf library.
|
|
@xref{Multithreading support}.
|
|
@item
|
|
Chf now supports the conditional save and restore of signal masks in unwind
|
|
contexts (@code{sigjmp_buf} contexts instead of @code{jmp_buf}).
|
|
@item
|
|
The method of passing unwind contexts as arguments is now consistent
|
|
with that used by @code{sigsetjmp()}; in particular, it is no longer
|
|
necessary to reference the contexts with @code{&}.
|
|
@item
|
|
Some more useful macro definitions have been added to @code{Chf.h}.
|
|
@xref{Other useful macro definitions}.
|
|
@end itemize
|
|
|
|
@c 2.2, cibrario, 25-Jan-2001
|
|
@c New chapter on changes since release 2.1
|
|
@node Changes since release 2.1, Function Index, Changes since release 1, Top
|
|
@chapter Changes since release 2.1
|
|
@cindex Changes since release 2.1
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Chf now offers limited support of Unicode-based Win32 platforms,
|
|
notably Windows CE.
|
|
@end itemize
|
|
|
|
@node Function Index, Data Type Index, Changes since release 2.1, Top
|
|
@unnumbered Function Index
|
|
@printindex fn
|
|
|
|
@node Data Type Index, Concept Index, Function Index, Top
|
|
@unnumbered Data Type Index
|
|
@printindex tp
|
|
|
|
@c @node Variable Index, Concept Index, Data Type Index, Top
|
|
@c @unnumbered Variable Index
|
|
@c @printindex vr
|
|
|
|
@node Concept Index, , Data Type Index, Top
|
|
@unnumbered Concept Index
|
|
@printindex cp
|
|
|
|
@contents
|
|
|
|
@bye
|