2677 lines
91 KiB
Text
2677 lines
91 KiB
Text
head 2.2;
|
|
access;
|
|
symbols
|
|
V4_1_1_1:2.2
|
|
Rel_2_1:2.1;
|
|
locks; strict;
|
|
comment @# @;
|
|
|
|
|
|
2.2
|
|
date 2001.01.25.12.06.29; author cibrario; state Exp;
|
|
branches;
|
|
next 2.1;
|
|
|
|
2.1
|
|
date 2000.05.29.13.02.12; author cibrario; state Rel;
|
|
branches;
|
|
next 1.6;
|
|
|
|
1.6
|
|
date 98.06.10.09.13.42; author cibrario; state Exp;
|
|
branches;
|
|
next ;
|
|
|
|
|
|
desc
|
|
@@
|
|
|
|
|
|
2.2
|
|
log
|
|
@- Added partial Win32 support (Windows CE only).
|
|
- Fixed xref and other assorted bugs.
|
|
@
|
|
text
|
|
@\input texinfo @@c -*-texinfo-*-
|
|
|
|
@@c $Id: chf.texi,v 2.1 2000/05/29 13:02:12 cibrario Rel cibrario $
|
|
@@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:
|
|
|
|
@@table @@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 table
|
|
|
|
@@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:
|
|
|
|
@@table @@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 table
|
|
|
|
@@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
|
|
@
|
|
|
|
|
|
2.1
|
|
log
|
|
@Updated documentation for libChf release 2.1:
|
|
- Fixed many typos and spelling errors
|
|
- Updated documentation to explain multithreading support
|
|
- Documented new abort codes/messages related to multithreading support
|
|
- Expanded description of severity codes
|
|
- Documented new ChfAction code CHF_UNWIND_KEEP
|
|
- Changed data type jmp_buf -> sigjmp_buf; documented new parameter passing
|
|
policy for unwind contexts
|
|
- New chapter: Structured condition handling
|
|
- Finished documententing the message retrieval subsystem
|
|
- New macros in Chf.h: CHF_MAJOR_RELEASE_NUMBER and CHF_MINOR_RELEASE_NUMBER
|
|
- Documented changes since release 1
|
|
@
|
|
text
|
|
@d3 1
|
|
a3 1
|
|
@@c $Id: chf.texi,v 1.6 1998/06/10 09:13:42 cibrario Exp cibrario $
|
|
d6 1
|
|
a6 1
|
|
@@settitle Chf library (libChf r2.1) Documentation
|
|
d14 1
|
|
a14 1
|
|
This manual documents the Condition Handling Facility library (libChf r2.1).
|
|
d24 1
|
|
a24 1
|
|
@@subtitle (libChf r2.1)
|
|
d32 1
|
|
a32 1
|
|
applies to its release 2.1.
|
|
d47 1
|
|
d59 1
|
|
d122 1
|
|
d126 1
|
|
a126 1
|
|
signaling exceptional conditions. This method can used either in
|
|
d142 1
|
|
a142 1
|
|
It provides a unified method to log and print error messages, and to
|
|
d155 5
|
|
d161 33
|
|
d255 1
|
|
a255 1
|
|
@@code{Chf.h} and provide some basic definitions. @@xref{Library header}
|
|
d261 1
|
|
d298 4
|
|
d382 3
|
|
d402 3
|
|
d424 1
|
|
a424 1
|
|
@@node ChfStaticInit(), ChfExit(), ChfMsgcatInit(), Initialization and exit
|
|
d478 1
|
|
a478 1
|
|
@@item char *template
|
|
d485 58
|
|
a542 1
|
|
@@node ChfExit(), ChfAbort(), ChfStaticInit(), Initialization and exit
|
|
d560 1
|
|
a560 1
|
|
if CHF hasn't been initialized.
|
|
d564 2
|
|
a565 1
|
|
application designer to ensure that no other Chf functions will be
|
|
d584 3
|
|
d643 5
|
|
d665 1
|
|
a665 1
|
|
@@xref{Reserved module identifiers}
|
|
d680 3
|
|
d720 1
|
|
a720 1
|
|
This value represents the severity of the condition. @@xref{ChfSeverity}
|
|
d730 1
|
|
a730 1
|
|
retrieval subsystem, @@xref{Message retrieval}, using the current Chf
|
|
d741 1
|
|
a741 1
|
|
This function calls the CHF function @@code{ChfAbort()} if one of the following
|
|
d833 2
|
|
d871 1
|
|
a871 1
|
|
The state of Chf is changed to @@code{CHF_SIGNALLING} if it was @@code{CHF_IDLE},
|
|
d885 1
|
|
a885 1
|
|
When the Chf state is @@code{CHF_SIGNALLING}, any new condition group generated
|
|
d898 2
|
|
a899 1
|
|
handler requests either the action @@code{CHF_CONTINUE} or @@code{CHF_UNWIND}.
|
|
d993 5
|
|
d1065 1
|
|
a1065 1
|
|
Bad CHF state for requested operation. A new handler can be added to the
|
|
d1079 1
|
|
a1079 1
|
|
if CHF hasn't been initialized.
|
|
d1101 1
|
|
a1101 1
|
|
Bad CHF state for requested operation. Handlers can be removed from the
|
|
d1115 1
|
|
a1115 1
|
|
if CHF hasn't been initialized.
|
|
d1164 1
|
|
a1164 1
|
|
@@xref{ChfSeverity}
|
|
d1223 1
|
|
a1223 1
|
|
@@item CHF_SIGNALLING
|
|
d1259 1
|
|
a1259 1
|
|
@@code{ChfSignal()} that caused the invocation of the condition handler.
|
|
d1273 1
|
|
a1273 1
|
|
transfer. @@xref{ChfPushHandler()}
|
|
d1305 2
|
|
d1432 2
|
|
a1433 2
|
|
structured condition handler is @@strong{not} invoked when a warning
|
|
condition is signaled in its @@code{ChfTry} body.
|
|
d1457 1
|
|
a1457 1
|
|
@@code{CHF_FATAL} condition are usually signaled immediately after
|
|
d1485 1
|
|
a1485 1
|
|
Chf transitions to state @@code{CHF_SIGNALLING} and starts
|
|
d1514 1
|
|
a1514 1
|
|
current condition group; the condition group can be resignalled at will
|
|
d1565 1
|
|
a1565 1
|
|
@@deftypefn Macro {} ChfEndTry;
|
|
d1618 7
|
|
d1657 1
|
|
a1657 1
|
|
@@xref{Reserved module identifiers}
|
|
d1686 3
|
|
d1734 1
|
|
a1734 1
|
|
if CHF hasn't been correctly initialized.
|
|
d1740 4
|
|
d1771 5
|
|
d1790 1
|
|
a1790 1
|
|
to a private MRS data structured.
|
|
d1834 2
|
|
d1913 30
|
|
d1998 1
|
|
a1998 1
|
|
@@node Changes since release 1, Function Index, Other useful functions, Top
|
|
d2023 13
|
|
a2035 1
|
|
@@node Function Index, Data Type Index, Changes since release 1, Top
|
|
@
|
|
|
|
|
|
1.6
|
|
log
|
|
@*** empty log message ***
|
|
@
|
|
text
|
|
@d3 1
|
|
a3 1
|
|
@@c $Id$
|
|
d6 1
|
|
a6 1
|
|
@@settitle Chf library (libChf r1.6) Documentation
|
|
d14 1
|
|
a14 1
|
|
This manual documents the Condition Handling Facility library (libChf r1.6).
|
|
d17 1
|
|
a17 1
|
|
signalling exceptional conditions, establishing exception handlers, and
|
|
d24 1
|
|
a24 1
|
|
@@subtitle (libChf r1.6)
|
|
d32 1
|
|
a32 1
|
|
applies to its release 1.6.
|
|
d39 2
|
|
a40 1
|
|
* Condition handling::
|
|
d43 1
|
|
d46 1
|
|
d49 1
|
|
a49 1
|
|
* Concept Index:: @@c @@detailmenu
|
|
d65 1
|
|
a65 1
|
|
* Signalling a condition::
|
|
d74 1
|
|
a74 1
|
|
Signalling a condition
|
|
d92 11
|
|
d123 1
|
|
a123 1
|
|
signalling exceptional conditions. This method can used either in
|
|
d126 1
|
|
a126 1
|
|
occours in a procedure, and checking for these values after each procedure
|
|
d135 1
|
|
a135 1
|
|
an error occours, such as which source module detected it, its severity,
|
|
d165 1
|
|
a165 1
|
|
An informational state which exists when an exception occours, and encloses
|
|
d186 6
|
|
a191 1
|
|
from the handler stack is executed.
|
|
d210 2
|
|
a211 2
|
|
All initialization functions, when succesful, register a default condition
|
|
handler. @@xref{Default handler}
|
|
d232 1
|
|
a232 1
|
|
@@code{CHF_S_OK} if the initialization was succesful, or one of the other
|
|
d252 3
|
|
a254 3
|
|
@@code{exit(exit_code)} to abort the application when an unrecoverable
|
|
exception occours. This forces a core dump that may be useful for
|
|
debugging purposes.
|
|
d268 1
|
|
a268 1
|
|
Size of the condition stack. This value fixes the maximum number of
|
|
d270 2
|
|
a271 2
|
|
not been signalled yet. A condition that is begin signalled is
|
|
still pending until the signalling sequence completes.
|
|
d274 1
|
|
a274 1
|
|
Size of the handler stack. This value fixes the maximum number of
|
|
d278 3
|
|
d283 3
|
|
a285 2
|
|
This is the exit code the Chf library will use to exit the application
|
|
when an unrecoverable exception occours.
|
|
d294 1
|
|
a294 1
|
|
The Chf library has been succesfully initialized.
|
|
d306 1
|
|
a306 1
|
|
It's necessary to invoke succesfully @@code{ChfInit()}, either directly
|
|
d308 3
|
|
a310 1
|
|
any other Chf function; otherwise, they will fail and abort the application.
|
|
d315 2
|
|
a316 1
|
|
before.
|
|
d341 1
|
|
a341 1
|
|
The Chf library has been succesfully initialized.
|
|
d360 1
|
|
a360 1
|
|
It's necessary to invoke succesfully either @@code{ChfMsgcatInit()},
|
|
d362 1
|
|
a362 2
|
|
before using any other Chf function; otherwise, any other
|
|
function will fail and abort the application.
|
|
d388 1
|
|
a388 1
|
|
The Chf library has been succesfully initialized.
|
|
d400 1
|
|
a400 1
|
|
It's necessary to invoke succesfully either @@code{ChfStaticInit()},
|
|
d402 1
|
|
a402 2
|
|
before using any other Chf function; otherwise, any other
|
|
function will fail and abort the application.
|
|
d441 4
|
|
a444 2
|
|
except to the inizialization functions, will abort
|
|
the application using @@code{ChfAbort()} with abort code @@code{CHF_ABORT_INIT}.
|
|
a448 1
|
|
|
|
d453 4
|
|
d464 3
|
|
a466 2
|
|
This function prints the message associated with @@code{abort_code} and then
|
|
immediately aborts the application. The abort is performed either:
|
|
d472 2
|
|
a473 1
|
|
initialization.
|
|
d475 4
|
|
a478 2
|
|
using @@code{exit(exit_code)} if the above mentioned flag is clear.
|
|
The argument @@code{exit_code} is the value of the @@code{exit_code} argument
|
|
d501 1
|
|
a501 1
|
|
group. This should not occour if the default condition handler is active
|
|
d504 1
|
|
a504 1
|
|
A fatal condition was signalled while Chf was unwinding. This is not
|
|
d508 9
|
|
a516 1
|
|
CHF_F_COND_STACK_FULL (condition stack full) was being signalled.
|
|
d521 1
|
|
a521 2
|
|
the application when a @@code{CHF_FATAL} condition occours.
|
|
|
|
d552 1
|
|
a552 1
|
|
appication's modules in the same source file, so it is discouraged.
|
|
d562 1
|
|
a562 1
|
|
@@node Condition generation and signal, Condition handling, Initialization and exit, Top
|
|
d568 1
|
|
a568 1
|
|
* Signalling a condition::
|
|
d571 1
|
|
a571 1
|
|
@@node Generating a condition, Signalling a condition, Condition generation and signal, Condition generation and signal
|
|
d575 1
|
|
a575 1
|
|
When an unusual or noteworthy condition occours, the appliction may generate
|
|
d618 1
|
|
a618 1
|
|
handled and signalled.
|
|
d620 2
|
|
a621 2
|
|
This function calls the CHF function 'ChfAbort()' if one of the following
|
|
unrecoverable error condition occours:
|
|
d634 1
|
|
a634 1
|
|
@@code{CHF_F_COND_STACK_FULL} (condition stack full) was being signalled
|
|
d656 2
|
|
d666 4
|
|
a669 1
|
|
This condition represents the succesful completion of an application's action.
|
|
d672 5
|
|
a676 2
|
|
This condition conveys an information message to the application's user, but
|
|
it in no way represents an error indication.
|
|
d680 6
|
|
a685 3
|
|
potentially abnormal situation occoured, but the application's module
|
|
was able to complete succesfully the action that was requested to it,
|
|
perhaps incompletely.
|
|
d688 5
|
|
a692 3
|
|
An error occoured and the application's module was not able to complete its
|
|
work, but it may be possible to perform a local recovery and resume the
|
|
normal application's control flow.
|
|
d695 1
|
|
a695 1
|
|
A fatal error occoured, and a global recovery action is required, because
|
|
d699 1
|
|
a699 1
|
|
call.
|
|
d715 3
|
|
a717 3
|
|
@@node Signalling a condition, , Generating a condition, Condition generation and signal
|
|
@@section Signalling a condition
|
|
@@cindex Signalling a condition
|
|
d720 2
|
|
a721 2
|
|
previous section can be signalled using the following function, that starts
|
|
the condition signalling sequence.
|
|
d727 1
|
|
a727 1
|
|
@@node ChfSignal(), , Signalling a condition, Signalling a condition
|
|
d734 1
|
|
a734 1
|
|
requested by the condition handlers invoked during the signalling operation
|
|
d737 2
|
|
a738 2
|
|
otherwise either a non-local control transfer will occour (@@code{CHF_UNWIND})
|
|
or the application's process will be terminated.
|
|
d740 1
|
|
a740 1
|
|
During the signalling of a condition group the following actions are
|
|
d745 2
|
|
a746 2
|
|
First of all, a check is make to ensure that the Chf subsystem has been
|
|
correctly initialized. If not, the funcion @@code{ChfAbort} is called.
|
|
d763 2
|
|
a764 2
|
|
but not yet signalled when the current handler exits is merged
|
|
with the condition group currently being signalled, in order to allow
|
|
d774 1
|
|
a774 1
|
|
stack is exausted (all condition handlers have been called) or when an
|
|
d777 1
|
|
a777 1
|
|
the severity of the condition group is @@code{CHF_FATAL}; when this occours,
|
|
d783 1
|
|
a783 1
|
|
started the signalling activities.
|
|
d785 2
|
|
a786 1
|
|
If the action @@code{CHF_UNWIND} has been requested and it is allowed, i.e.
|
|
d790 1
|
|
a790 1
|
|
from the one registered last, this way they can perform any final cleanup
|
|
d792 12
|
|
a803 8
|
|
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{longjmp()}, using the @@code{unwind_context} associated with the handler
|
|
that requested the unwind as target. The @@code{ChfSignal()} invocation that
|
|
started the signalling activities will never return to the caller.
|
|
d805 2
|
|
a806 2
|
|
If no handlers were able to handle the condition, the application is
|
|
terminated with @@code{ChfAbort()}.
|
|
d810 1
|
|
a810 1
|
|
immediately signalled, containing the condition @@code{CHF_F_INVALID_ACTION}
|
|
d814 3
|
|
a816 1
|
|
@@node Condition handling, Chf conditions, Condition generation and signal, Top
|
|
d828 1
|
|
a828 1
|
|
@@node Condition handlers, Condition descriptors, Condition handling, Condition handling
|
|
d832 1
|
|
a832 1
|
|
The Chf library mantains a LIFO stack of active condition handlers. Each
|
|
d864 1
|
|
a864 1
|
|
is a pointer to the condition group that is being signalled.
|
|
d867 1
|
|
a867 1
|
|
repesents the current state of the condition handling facility.
|
|
d875 1
|
|
a875 1
|
|
without signalling them, with the purpose of better specify the current
|
|
d886 2
|
|
a887 2
|
|
condition group only. When the new signalling sequence is completed,
|
|
the old sequence will be resumed if sppropriate, i.e. if a superior
|
|
d898 1
|
|
a898 1
|
|
@@deftypefn Function void ChfPushHandler (ChfHandler new_handler, jmp_buf *unwind_context, ChfPointer handler_context)
|
|
d900 6
|
|
a905 3
|
|
This function pushes the new condition handler @@code{new_handler} with its
|
|
associated longjmp context, pointed by @@code{unwind_context}, into the handler
|
|
stack.
|
|
d918 3
|
|
a920 3
|
|
If, in the future, the handler will request the @@code{CHF_UNWIND} action,
|
|
the @@code{setjmp()} function invocation that established @@code{unwind_context}
|
|
will appear to return again.
|
|
d924 3
|
|
a926 2
|
|
@@code{CHF_UNWIND} action, the application will be silently terminated
|
|
calling @@code{ChfAbort()} with abort code @@code{CHF_ABORT_SILENT}.
|
|
d928 1
|
|
a928 1
|
|
If an error occours during the execution, the function generates
|
|
d964 1
|
|
a964 1
|
|
If an error occours during the execution, the function generates
|
|
d993 1
|
|
a993 1
|
|
@@node Condition descriptors, Condition handling state, Condition handlers, Condition handling
|
|
d1043 1
|
|
a1043 1
|
|
was generated. This piece of information is avaliable only if the
|
|
d1054 1
|
|
a1054 1
|
|
was generated. This piece of information is avaliable only if the
|
|
d1074 1
|
|
a1074 1
|
|
@@node Condition handling state, Handler actions, Condition descriptors, Condition handling
|
|
d1083 1
|
|
a1083 1
|
|
The Chf library has not been initializes, or the initialization has failed.
|
|
d1091 1
|
|
a1091 1
|
|
to conditions that have been generated but have not been signalled yet.
|
|
d1110 2
|
|
a1111 2
|
|
unwinded has signalled another condition group. The superiors of the
|
|
signalling handler are invoked with Chf in this state, then the unwind
|
|
d1117 1
|
|
a1117 1
|
|
@@node Handler actions, Default handler, Condition handling state, Condition handling
|
|
d1146 9
|
|
d1158 1
|
|
a1158 1
|
|
@@node Default handler, , Handler actions, Condition handling
|
|
d1163 1
|
|
a1163 1
|
|
pushed into the condition handler stack by the Chf initalization
|
|
d1172 1
|
|
a1172 1
|
|
if the severity of the condition being signalled is greater than
|
|
d1178 1
|
|
a1178 1
|
|
if the severity of the condition being signalled is less than
|
|
d1183 1
|
|
a1183 1
|
|
if the @@code{CHF_FATAL} condition was NOT signalled during an unwind
|
|
d1189 246
|
|
d1436 6
|
|
a1441 1
|
|
@@node Chf conditions, Message retrieval, Condition handling, Top
|
|
d1452 1
|
|
a1452 1
|
|
No additional condition can be generated until the handling of this condition
|
|
d1458 1
|
|
a1458 1
|
|
was full; the new handler is not registered and this condition is signalled
|
|
d1469 2
|
|
a1470 2
|
|
Chf function. The invoked function does not do anything and signals but
|
|
signalling this condition.
|
|
d1474 1
|
|
a1474 1
|
|
During the current signalling sequence an handler returned an invalid
|
|
d1476 1
|
|
a1476 1
|
|
generated and immediately signalled. The first handler called to handle
|
|
d1483 1
|
|
a1483 1
|
|
and signalled when a dynamic memory allocation attempt failed, and the library
|
|
d1490 1
|
|
a1490 1
|
|
by the Chf initialization function instead of being signalled, because it
|
|
d1498 1
|
|
a1498 1
|
|
by the Chf initialization function instead of being signalled, because it
|
|
d1504 1
|
|
a1504 1
|
|
@@node Message retrieval, Other useful macro definitions, Chf conditions, Top
|
|
d1511 1
|
|
a1511 1
|
|
Basically, given a message set identifier (that generally has the same value
|
|
d1513 1
|
|
a1513 1
|
|
a message number (that generally has the same value as the condition code),
|
|
d1540 1
|
|
a1540 1
|
|
This function transparently uses the Chf message retrieval subystem to
|
|
d1553 1
|
|
a1553 1
|
|
The returned pointer points to static storage, which can be
|
|
d1583 1
|
|
a1583 1
|
|
The message associated with the condition code, comprising any ancillary
|
|
d1596 1
|
|
a1596 1
|
|
The returned pointer points to static storage, which can be
|
|
d1623 1
|
|
a1623 1
|
|
unsuccesful, @@code{strerror()} is used instead.
|
|
d1626 2
|
|
d1630 1
|
|
d1633 39
|
|
a1671 2
|
|
subsystem; therefore, any subsystem can be used, provided it follows
|
|
the guidelines described below.
|
|
d1673 10
|
|
a1682 1
|
|
This section of the documentation is still TBD (libChf r1.6)
|
|
d1684 38
|
|
d1723 1
|
|
a1723 1
|
|
@@node Other useful macro definitions, Other useful functions, Message retrieval, Top
|
|
d1732 1
|
|
a1732 1
|
|
It is a string repesenting the Chf library identifier; the identifier
|
|
d1736 10
|
|
d1761 1
|
|
a1761 1
|
|
@@node Other useful functions, Function Index, Other useful macro definitions, Top
|
|
d1767 1
|
|
a1767 1
|
|
condition stack, without signalling it. The function does nothing if
|
|
d1781 1
|
|
a1781 1
|
|
condition for functions that, when an error occours, generate a condition
|
|
d1785 4
|
|
d1793 1
|
|
a1793 1
|
|
During condition signalling, Chf creates a new, empty, condition group
|
|
d1798 1
|
|
a1798 1
|
|
NOT to the top condition of the condition group being signalled. The
|
|
d1802 4
|
|
d1814 28
|
|
a1841 1
|
|
@@node Function Index, Data Type Index, Other useful functions, Top
|
|
@
|