From 787274f0421a2aafcf88122c379eceaf5888d8b5 Mon Sep 17 00:00:00 2001 From: Doug Evans Date: Fri, 13 Mar 2009 17:26:59 +0000 Subject: [PATCH] * exceptions.h: Clean up some comments on catch_exceptions usage. * exceptions.c: Ditto. Plus mark catch_errors as superseded by catch_exceptions. --- gdb/ChangeLog | 6 ++++++ gdb/exceptions.c | 32 +++++++++++++------------------- gdb/exceptions.h | 15 ++++++++++++--- 3 files changed, 31 insertions(+), 22 deletions(-) diff --git a/gdb/ChangeLog b/gdb/ChangeLog index c699359..3e592a3 100644 --- a/gdb/ChangeLog +++ b/gdb/ChangeLog @@ -1,3 +1,9 @@ +2009-03-13 Doug Evans + + * exceptions.h: Clean up some comments on catch_exceptions usage. + * exceptions.c: Ditto. Plus mark catch_errors as superseded by + catch_exceptions. + 2009-02-17 Joel Brobecker The following patch helps getting rid of a warning inside solib-som.c. diff --git a/gdb/exceptions.c b/gdb/exceptions.c index 4383ad3..3cee40d 100644 --- a/gdb/exceptions.c +++ b/gdb/exceptions.c @@ -417,25 +417,21 @@ throw_error (enum errors error, const char *fmt, ...) va_end (args); } -/* Call FUNC() with args FUNC_UIOUT and FUNC_ARGS, catching any - errors. Set FUNC_CAUGHT to an ``enum return_reason'' if the - function is aborted (using throw_exception() or zero if the - function returns normally. Set FUNC_VAL to the value returned by - the function or 0 if the function was aborted. +/* Call FUNC(UIOUT, FUNC_ARGS) but wrapped within an exception + handler. If an exception (enum return_reason) is thrown using + throw_exception() than all cleanups installed since + catch_exceptions() was entered are invoked, the (-ve) exception + value is then returned by catch_exceptions. If FUNC() returns + normally (with a positive or zero return value) then that value is + returned by catch_exceptions(). It is an internal_error() for + FUNC() to return a negative value. + + See exceptions.h for further usage details. Must not be called with immediate_quit in effect (bad things might happen, say we got a signal in the middle of a memcpy to quit_return). This is an OK restriction; with very few exceptions immediate_quit can - be replaced by judicious use of QUIT. - - MASK specifies what to catch; it is normally set to - RETURN_MASK_ALL, if for no other reason than that the code which - calls catch_errors might not be set up to deal with a quit which - isn't caught. But if the code can deal with it, it generally - should be RETURN_MASK_ERROR, unless for some reason it is more - useful to abort only the portion of the operation inside the - catch_errors. Note that quit should return to the command line - fairly quickly, even if some further processing is being done. */ + be replaced by judicious use of QUIT. */ /* MAYBE: cagney/1999-11-05: catch_errors() in conjunction with error() et.al. could maintain a set of flags that indicate the the @@ -445,10 +441,6 @@ throw_error (enum errors error, const char *fmt, ...) code also randomly used a SET_TOP_LEVEL macro that directly initialize the longjmp buffers. */ -/* MAYBE: cagney/1999-11-05: Should the catch_errors and cleanups code - be consolidated into a single file instead of being distributed - between utils.c and top.c? */ - int catch_exceptions (struct ui_out *uiout, catch_exceptions_ftype *func, @@ -505,6 +497,8 @@ catch_exceptions_with_msg (struct ui_out *uiout, return val; } +/* This function is superseded by catch_exceptions(). */ + int catch_errors (catch_errors_ftype *func, void *func_args, char *errstring, return_mask mask) diff --git a/gdb/exceptions.h b/gdb/exceptions.h index d6ed87a..d2102c3 100644 --- a/gdb/exceptions.h +++ b/gdb/exceptions.h @@ -180,7 +180,7 @@ extern NORETURN void deprecated_throw_reason (enum return_reason reason) ATTR_NO throw_exception() than all cleanups installed since catch_exceptions() was entered are invoked, the (-ve) exception value is then returned by catch_exceptions. If FUNC() returns - normally (with a postive or zero return value) then that value is + normally (with a positive or zero return value) then that value is returned by catch_exceptions(). It is an internal_error() for FUNC() to return a negative value. @@ -194,10 +194,19 @@ extern NORETURN void deprecated_throw_reason (enum return_reason reason) ATTR_NO copy of the gdb error message. This is used when a silent error is issued and the caller wants to manually issue the error message. + MASK specifies what to catch; it is normally set to + RETURN_MASK_ALL, if for no other reason than that the code which + calls catch_errors might not be set up to deal with a quit which + isn't caught. But if the code can deal with it, it generally + should be RETURN_MASK_ERROR, unless for some reason it is more + useful to abort only the portion of the operation inside the + catch_errors. Note that quit should return to the command line + fairly quickly, even if some further processing is being done. + FIXME; cagney/2001-08-13: The need to override the global UIOUT builder variable should just go away. - This function superseeds catch_errors(). + This function supersedes catch_errors(). This function uses SETJMP() and LONGJUMP(). */ @@ -228,7 +237,7 @@ extern struct gdb_exception catch_exception (struct ui_out *uiout, indication of the exact exception that it caught - quit_flag might help. - This function is superseeded by catch_exceptions(). */ + This function is superseded by catch_exceptions(). */ typedef int (catch_errors_ftype) (void *); extern int catch_errors (catch_errors_ftype *, void *, char *, return_mask); -- 2.7.4