From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 9151 invoked by alias); 14 Dec 2008 20:55:36 -0000 Received: (qmail 9140 invoked by uid 22791); 14 Dec 2008 20:55:35 -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; Sun, 14 Dec 2008 20:55:00 +0000 Received: from wpaz1.hot.corp.google.com (wpaz1.hot.corp.google.com [172.24.198.65]) by smtp-out.google.com with ESMTP id mBEKswPq009850 for ; Sun, 14 Dec 2008 12:54:58 -0800 Received: from rv-out-0506.google.com (rvfb25.prod.google.com [10.140.179.25]) by wpaz1.hot.corp.google.com with ESMTP id mBEKsuaW023648 for ; Sun, 14 Dec 2008 12:54:56 -0800 Received: by rv-out-0506.google.com with SMTP id b25so2411382rvf.43 for ; Sun, 14 Dec 2008 12:54:56 -0800 (PST) MIME-Version: 1.0 Received: by 10.140.161.11 with SMTP id j11mr3267833rve.247.1229288095960; Sun, 14 Dec 2008 12:54:55 -0800 (PST) In-Reply-To: <20081204212015.DDD081C7A10@localhost> References: <20081204212015.DDD081C7A10@localhost> Date: Sun, 14 Dec 2008 20:55:00 -0000 Message-ID: Subject: Re: [RFA] comment cleanup in exceptions.[ch] From: Doug Evans To: gdb-patches@sourceware.org Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit 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/msg00264.txt.bz2 Ping. On Thu, Dec 4, 2008 at 1:20 PM, Doug Evans 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 > > * 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); >