This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: [RFA] comment cleanup in exceptions.[ch]
- From: Doug Evans <dje at google dot com>
- To: gdb-patches at sourceware dot org
- Date: Sun, 14 Dec 2008 12:54:55 -0800
- Subject: Re: [RFA] comment cleanup in exceptions.[ch]
- References: <20081204212015.DDD081C7A10@localhost>
Ping.
On Thu, Dec 4, 2008 at 1:20 PM, Doug Evans <dje@google.com> wrote:
> Hi.
>
> While looking into using catch_errors/exceptions for something
> I ran into some confusing/outdated comments.
> I don't know all the details of catch_exceptions to be comfortable
> that the result still doesn't have problems, but it is better
> than before.
>
> The high order bit here is that I copied the lead paragraph for
> catch_exceptions from exceptions.h to exceptions.c and added
> a reference back to exceptions.h (it seemed like some text more
> than just "see exceptions.h" was useful in exceptions.c),
> plus I moved the usage text of MASK to exceptions.h.
>
> I also removed an outdated FIXME regarding utils.c/top.c.
> Given that exceptions.[ch] exists I think this FIXME can go.
>
> Ok to check in?
>
> 2008-12-04 Doug Evans <dje@google.com>
>
> * exceptions.h: Clean up some comments on catch_exceptions usage.
> * exceptions.c: Ditto. Plus mark catch_errors as superseded by
> catch_exceptions.
>
> Index: exceptions.c
> ===================================================================
> RCS file: /cvs/src/src/gdb/exceptions.c,v
> retrieving revision 1.30
> diff -u -p -r1.30 exceptions.c
> --- exceptions.c 8 Sep 2008 21:46:21 -0000 1.30
> +++ exceptions.c 4 Dec 2008 21:12:21 -0000
> @@ -417,25 +417,21 @@ throw_error (enum errors error, const ch
> 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 ch
> 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
> return val;
> }
>
> +/* This function is superseded by catch_exceptions(). */
> +
> int
> catch_errors (catch_errors_ftype *func, void *func_args, char *errstring,
> return_mask mask)
> Index: exceptions.h
> ===================================================================
> RCS file: /cvs/src/src/gdb/exceptions.h,v
> retrieving revision 1.22
> diff -u -p -r1.22 exceptions.h
> --- exceptions.h 1 Jan 2008 22:53:09 -0000 1.22
> +++ exceptions.h 4 Dec 2008 21:12:21 -0000
> @@ -177,7 +177,7 @@ extern NORETURN void deprecated_throw_re
> 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.
>
> @@ -191,10 +191,19 @@ extern NORETURN void deprecated_throw_re
> 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(). */
>
> @@ -225,7 +234,7 @@ extern struct gdb_exception catch_except
> 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);
>