From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 20622 invoked by alias); 4 Dec 2008 21:20:57 -0000 Received: (qmail 20609 invoked by uid 22791); 4 Dec 2008 21:20:56 -0000 X-Spam-Check-By: sourceware.org Received: from smtp-out.google.com (HELO smtp-out.google.com) (216.239.45.13) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Thu, 04 Dec 2008 21:20:18 +0000 Received: from zps76.corp.google.com (zps76.corp.google.com [172.25.146.76]) by smtp-out.google.com with ESMTP id mB4LKHcS020249 for ; Thu, 4 Dec 2008 13:20:17 -0800 Received: from localhost (ruffy.corp.google.com [172.18.118.116]) by zps76.corp.google.com with ESMTP id mB4LKFXC019856 for ; Thu, 4 Dec 2008 13:20:16 -0800 Received: by localhost (Postfix, from userid 67641) id DDD081C7A10; Thu, 4 Dec 2008 13:20:15 -0800 (PST) To: gdb-patches@sourceware.org Subject: [RFA] comment cleanup in exceptions.[ch] Message-Id: <20081204212015.DDD081C7A10@localhost> Date: Thu, 04 Dec 2008 21:20:00 -0000 From: dje@google.com (Doug Evans) X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2008-12/txt/msg00075.txt.bz2 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 * 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);