doc: replace legacy names by their new counterparts

This commit is contained in:
Marius Gerbershagen 2020-02-22 19:11:41 +01:00
parent f18cbde8e7
commit 4faac4dcb8
4 changed files with 19 additions and 18 deletions

View file

@ -94,7 +94,7 @@ The approach in ECL is more lightweight: we install our own signal handler and u
Systems that embed ECL may wish to deactivate completely these signal handlers. This is done using the boot options, @code{ECL_OPT_TRAP_SIGFPE}, @code{ECL_OPT_TRAP_SIGSEGV}, @code{ECL_OPT_TRAP_SIGBUS}, @code{ECL_OPT_TRAP_INTERRUPT_SIGNAL}.
Systems that embed ECL and want to allow handling of synchronous signals should take care to also trap the associated lisp conditions that may arise. This is automatically taken care of by functions such as @coderef{si_safe_eval}, and in all other cases it can be solved by enclosing the unsafe code in a @coderef{CL_CATCH_ALL} frame.
Systems that embed ECL and want to allow handling of synchronous signals should take care to also trap the associated lisp conditions that may arise. This is automatically taken care of by functions such as @coderef{si_safe_eval}, and in all other cases it can be solved by enclosing the unsafe code in a @coderef{ECL_CATCH_ALL} frame.
@node Signals and Interrupts - Considerations when embedding ECL

View file

@ -171,11 +171,11 @@ can be implemented using a C macro which is provided by ECL
@example
@verbatim
cl_env_ptr env = ecl_process_env();
CL_UNWIND_PROTECT_BEGIN(env) {
ECL_UNWIND_PROTECT_BEGIN(env) {
/* protected code goes here */
} CL_UNWIND_PROTECT_EXIT {
} ECL_UNWIND_PROTECT_EXIT {
/* exit code goes here */
} CL_UNWIND_PROTECT_END;
} ECL_UNWIND_PROTECT_END;
@end verbatim
@end example

View file

@ -11,26 +11,26 @@
@node Embedding ECL - Embedding Reference
@subsection Embedding Reference
@cppdef CL_CATCH_ALL
@defmac CL_CATCH_ALL
@cppdef ECL_CATCH_ALL
@defmac ECL_CATCH_ALL
Create a protected region.
@paragraph C Macro
@example
@verbatim
cl_env_ptr env = ecl_process_env();
CL_CATCH_ALL_BEGIN(env) {
ECL_CATCH_ALL_BEGIN(env) {
/*
* Code that is protected. Uncaught lisp conditions, THROW,
* signals such as SIGSEGV and SIGBUS may cause jump to
* this region.
*/
} CL_CATCH_ALL_IF_CAUGHT {
} ECL_CATCH_ALL_IF_CAUGHT {
/*
* If the exception, lisp condition or other control transfer
* is caught, this code is executed.
*/
} CL_CATCH_ALL_END
} ECL_CATCH_ALL_END
/*
* In all cases we exit here.
*/
@ -49,34 +49,34 @@ This is a set of three macros that create an @code{unwind-protect} region that p
(return nil)))
@end lisp
As explained in @coderef{CL_UNWIND_PROTECT}, it is normally advisable to set up an unwind-protect frame to avoid the embedded lisp code to perform arbitrary transfers of control.
As explained in @coderef{ECL_UNWIND_PROTECT}, it is normally advisable to set up an unwind-protect frame to avoid the embedded lisp code to perform arbitrary transfers of control.
@seealso{CL_UNWIND_PROTECT}
@seealso{ECL_UNWIND_PROTECT}
@end defmac
@cppdef CL_UNWIND_PROTECT
@defmac CL_UNWIND_PROTECT
@cppdef ECL_UNWIND_PROTECT
@defmac ECL_UNWIND_PROTECT
Create a protected region.
@paragraph C Macro
@example
@verbatim
cl_env_ptr env = ecl_process_env();
CL_UNWIND_PROTECT_BEGIN(env) {
ECL_UNWIND_PROTECT_BEGIN(env) {
/*
* Code that is protected. Uncaught lisp conditions, THROW,
* signals such as SIGSEGV and SIGBUS may cause jump to
* this region.
*/
} CL_UNWIND_PROTECT_EXIT {
} ECL_UNWIND_PROTECT_EXIT {
/*
* If the exception, lisp condition or other control transfer
* is caught, this code is executed. After this code, the
* process will jump to the original destination of the
* THROW, GOTO or other control statement that was interrupted.
*/
} CL_UNWIND_PROTECT_END
} ECL_UNWIND_PROTECT_END
/*
* We only exit here if NO nonlocal jump was interrupted.
*/
@ -87,12 +87,12 @@ CL_UNWIND_PROTECT_BEGIN(env) {
When embedding ECL it is normally advisable to set up an @code{unwind-protect} frame to avoid the embedded lisp code to perform arbitrary transfers of control. Furthermore, the unwind protect form will be used in at least in the following occasions:
@itemize
@item In a normal program exit, caused by @coderef{ext:quit}, ECL unwinds up to the outermost frame, which may be an @coderef{CL_CATCH_ALL} or @coderef{CL_UNWIND_PROTECT} macro.
@item In a normal program exit, caused by @coderef{ext:quit}, ECL unwinds up to the outermost frame, which may be an @coderef{ECL_CATCH_ALL} or @coderef{ECL_UNWIND_PROTECT} macro.
@end itemize
Besides this, normal mechanisms for exit, such as @coderef{ext:quit}, and uncaught exceptions, such as serious signals (@xref{Signals and Interrupts - Synchronous signals}), are best handled using @code{unwind-protect} blocks.
@seealso CL_CATCH_ALL
@seealso ECL_CATCH_ALL
@end defmac
@cppdef cl_boot

View file

@ -146,6 +146,7 @@
#define CL_CATCH_BEGIN ECL_CATCH_BEGIN
#define CL_CATCH_END ECL_CATCH_END
#define CL_CATCH_ALL_BEGIN ECL_CATCH_ALL_BEGIN
#define CL_CATCH_ALL_IF_CAUGHT ECL_CATCH_ALL_IF_CAUGHT
#define CL_CATCH_ALL_END ECL_CATCH_ALL_END
#define bds_bd ecl_bds_frame