Re: [patch/rfc] s/return_to_top_level/throw_exception/

[Andrew Cagney <ac131313 at cygnus dot com>]

Attempt #2.

 > Hello,
 >
 > This renames return_to_top_level() to something that better reflects 
that functions true semenatics.  At one level it is syntatic, at another 
level it does kind of legitimize the call.
 >
 > You may also have noticed that I've managed to reduce the number of 
throw_exception() calls down to just those that don't directly relate to 
errors.
 >
 > Anyway, thoughts.
 >
 > enjoy,
 > Andrew
 >
 > PS: I'm still chugging through a build of all the targets.
 >

2002-02-03  Andrew Cagney  <ac131313@redhat.com>

	* defs.h (throw_exception): Rename return_to_top_level.  Update
	comments.
	* utils.c (error_stream, internal_verror, quit): Ditto.
	* top.c (throw_exception, catcher): Ditto.
	* sparclet-rom.c (sparclet_load): Ditto.
	* remote.c (interrupt_query, minitelnet): Ditto.
	* remote-sds.c (interrupt_query): Ditto.
	* remote-mips.c (mips_error, mips_kill): Ditto.
	* ocd.c (interrupt_query): Ditto.
	* monitor.c (monitor_interrupt_query): Ditto.
	* m3-nat.c (suspend_all_threads, thread_resume_command): Ditto.
	* target.h: Update comment.
	
	* m3-nat.c, ocd.c, sparclet-rom.c: Update copyright.
	
Index: defs.h
===================================================================
RCS file: /cvs/src/src/gdb/defs.h,v
retrieving revision 1.75
diff -u -r1.75 defs.h
--- defs.h	2002/02/02 03:42:58	1.75
+++ defs.h	2002/02/03 20:16:09
@@ -1082,7 +1082,7 @@
 
 extern NORETURN void nomem (long) ATTR_NORETURN;
 
-/* Reasons for calling return_to_top_level.  NOTE: all reason values
+/* Reasons for calling throw_exception().  NOTE: all reason values
    must be less than zero.  enum value 0 is reserved for internal use
    as the return value from an initial setjmp().  The function
    catch_exceptions() reserves values >= 0 as legal results from its
@@ -1105,25 +1105,20 @@
 typedef int return_mask;
 
 /* Throw an exception of type RETURN_REASON.  Will execute a LONG JUMP
-   to the inner most containing exception handler (established using
-   catch_exceptions() or the legacy catch_errors()).
+   to the inner most containing exception handler established using
+   catch_exceptions() (or the legacy catch_errors()).
 
-   Useful when a section of code that caught an exception finds it
-   needs to repropagate that exception up the call chain.
+   Code normally throws an exception using error() et.al.  For various
+   reaons, GDB also contains code that throws an exception directly.
+   For instance, the remote*.c targets contain CNTRL-C signal handlers
+   that propogate the QUIT event up the exception chain.  ``This could
+   be a good thing or a dangerous thing.'' -- the Existential Wombat.  */
 
-   The name return_to_top_level() dates back to a time when GDB had
-   only one exception handler installed at the top level.  This really
-   did return to the top level.  The name should probably be changed.
+extern NORETURN void throw_exception (enum return_reason) ATTR_NORETURN;
 
-   NOTE: Some sections of code are using error_begin() in conjunction
-   with return_to_top_level() to throw the initial exception.  That
-   code should, instead, use either error() or error_string().  */
-
-extern NORETURN void return_to_top_level (enum return_reason) ATTR_NORETURN;
-
 /* Call FUNC(UIOUT, FUNC_ARGS) but wrapped within an exception
    handler.  If an exception (enum return_reason) is thrown using
-   return_to_top_level() than all cleanups installed since
+   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
Index: m3-nat.c
===================================================================
RCS file: /cvs/src/src/gdb/m3-nat.c,v
retrieving revision 1.14
diff -u -r1.14 m3-nat.c
--- m3-nat.c	2001/06/06 16:31:32	1.14
+++ m3-nat.c	2002/02/03 20:16:18
@@ -1,8 +1,8 @@
 /* Interface GDB to Mach 3.0 operating systems.
    (Most) Mach 3.0 related routines live in this file.
 
-   Copyright 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001
-   Free Software Foundation, Inc.
+   Copyright 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001,
+   2002 Free Software Foundation, Inc.
 
    This file is part of GDB.
 
@@ -2939,7 +2939,7 @@
     {
       warning ("Could not suspend inferior threads.");
       m3_kill_inferior ();
-      return_to_top_level (RETURN_ERROR);
+      throw_exception (RETURN_ERROR);
     }
 
   for (index = 0; index < thread_count; index++)
@@ -3108,7 +3108,7 @@
     {
       if (current_thread)
 	current_thread = saved_thread;
-      return_to_top_level (RETURN_ERROR);
+      throw_exception (RETURN_ERROR);
     }
 
   ret = thread_info (current_thread,
Index: monitor.c
===================================================================
RCS file: /cvs/src/src/gdb/monitor.c,v
retrieving revision 1.31
diff -u -r1.31 monitor.c
--- monitor.c	2002/01/19 03:32:36	1.31
+++ monitor.c	2002/02/03 20:16:24
@@ -1036,7 +1036,7 @@
 Give up (and stop debugging it)? "))
     {
       target_mourn_inferior ();
-      return_to_top_level (RETURN_QUIT);
+      throw_exception (RETURN_QUIT);
     }
 
   target_terminal_inferior ();
Index: ocd.c
===================================================================
RCS file: /cvs/src/src/gdb/ocd.c,v
retrieving revision 1.18
diff -u -r1.18 ocd.c
--- ocd.c	2001/07/15 20:34:13	1.18
+++ ocd.c	2002/02/03 20:16:28
@@ -1,7 +1,8 @@
 /* Target communications support for Macraigor Systems' On-Chip Debugging
-   Copyright 1996, 1997, 1998, 1999, 2000, 2001
-   Free Software Foundation, Inc.
 
+   Copyright 1996, 1997, 1998, 1999, 2000, 2001, 2002 Free Software
+   Foundation, Inc.
+
    This file is part of GDB.
 
    This program is free software; you can redistribute it and/or modify
@@ -446,7 +447,7 @@
 Give up (and stop debugging it)? "))
     {
       target_mourn_inferior ();
-      return_to_top_level (RETURN_QUIT);
+      throw_exception (RETURN_QUIT);
     }
 
   target_terminal_inferior ();
Index: remote-mips.c
===================================================================
RCS file: /cvs/src/src/gdb/remote-mips.c,v
retrieving revision 1.25
diff -u -r1.25 remote-mips.c
--- remote-mips.c	2002/01/19 03:32:37	1.25
+++ remote-mips.c	2002/02/03 20:16:37
@@ -497,7 +497,7 @@
   printf_unfiltered ("Ending remote MIPS debugging.\n");
   target_mourn_inferior ();
 
-  return_to_top_level (RETURN_ERROR);
+  throw_exception (RETURN_ERROR);
 }
 
 /* putc_readable - print a character, displaying non-printable chars in
@@ -2186,7 +2186,7 @@
 	  printf_unfiltered ("Ending remote MIPS debugging.\n");
 	  target_mourn_inferior ();
 
-	  return_to_top_level (RETURN_QUIT);
+	  throw_exception (RETURN_QUIT);
 	}
 
       target_terminal_inferior ();
Index: remote-sds.c
===================================================================
RCS file: /cvs/src/src/gdb/remote-sds.c,v
retrieving revision 1.19
diff -u -r1.19 remote-sds.c
--- remote-sds.c	2002/01/19 03:32:39	1.19
+++ remote-sds.c	2002/02/03 20:16:40
@@ -405,7 +405,7 @@
 Give up (and stop debugging it)? "))
     {
       target_mourn_inferior ();
-      return_to_top_level (RETURN_QUIT);
+      throw_exception (RETURN_QUIT);
     }
 
   target_terminal_inferior ();
Index: remote.c
===================================================================
RCS file: /cvs/src/src/gdb/remote.c,v
retrieving revision 1.74
diff -u -r1.74 remote.c
--- remote.c	2002/01/19 03:32:40	1.74
+++ remote.c	2002/02/03 20:16:53
@@ -2877,7 +2877,7 @@
 Give up (and stop debugging it)? "))
     {
       target_mourn_inferior ();
-      return_to_top_level (RETURN_QUIT);
+      throw_exception (RETURN_QUIT);
     }
 
   target_terminal_inferior ();
@@ -5717,7 +5717,7 @@
 	      if (query ("Interrupt GDB? "))
 		{
 		  printf_filtered ("Interrupted by user.\n");
-		  return_to_top_level (RETURN_QUIT);
+		  throw_exception (RETURN_QUIT);
 		}
 	      quit_count = 0;
 	    }
Index: sparclet-rom.c
===================================================================
RCS file: /cvs/src/src/gdb/sparclet-rom.c,v
retrieving revision 1.8
diff -u -r1.8 sparclet-rom.c
--- sparclet-rom.c	2001/07/15 20:34:14	1.8
+++ sparclet-rom.c	2002/02/03 20:16:54
@@ -1,7 +1,8 @@
 /* Remote target glue for the SPARC Sparclet ROM monitor.
-   Copyright 1995, 1996, 1997, 1998, 1999, 2000, 2001
-   Free Software Foundation, Inc.
 
+   Copyright 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002 Free
+   Software Foundation, Inc.
+
    This file is part of GDB.
 
    This program is free software; you can redistribute it and/or modify
@@ -204,7 +205,7 @@
   pop_target ();
   push_remote_target (monitor_get_dev_name (), 1);
 
-  return_to_top_level (RETURN_QUIT);
+  throw_exception (RETURN_QUIT);
 }
 
 /* Define the monitor command strings. Since these are passed directly
Index: target.h
===================================================================
RCS file: /cvs/src/src/gdb/target.h,v
retrieving revision 1.22
diff -u -r1.22 target.h
--- target.h	2002/01/09 00:36:57	1.22
+++ target.h	2002/02/03 20:16:59
@@ -438,10 +438,10 @@
     (*current_target.to_resume) (ptid, step, siggnal);			\
   } while (0)
 
-/* Wait for process pid to do something.  PTID = -1 to wait for any pid
-   to do something.  Return pid of child, or -1 in case of error;
+/* Wait for process pid to do something.  PTID = -1 to wait for any
+   pid to do something.  Return pid of child, or -1 in case of error;
    store status through argument pointer STATUS.  Note that it is
-   *not* OK to return_to_top_level out of target_wait without popping
+   _NOT_ OK to throw_exception() out of target_wait() without popping
    the debugging target from the stack; GDB isn't prepared to get back
    to the prompt with a debugging target but without the frame cache,
    stop_pc, etc., set up.  */
Index: top.c
===================================================================
RCS file: /cvs/src/src/gdb/top.c,v
retrieving revision 1.54
diff -u -r1.54 top.c
--- top.c	2002/02/02 00:56:34	1.54
+++ top.c	2002/02/03 20:17:06
@@ -196,7 +196,7 @@
 int (*ui_loop_hook) (int);
 
 /* Called instead of command_loop at top level.  Can be invoked via
-   return_to_top_level.  */
+   throw_exception().  */
 
 void (*command_loop_hook) (void);
 
@@ -298,13 +298,13 @@
 #define SIGLONGJMP(buf,val)	longjmp((buf), (val))
 #endif
 
-/* Where to go for return_to_top_level.  */
+/* Where to go for throw_exception().  */
 static SIGJMP_BUF *catch_return;
 
 /* Return for reason REASON to the nearest containing catch_errors().  */
 
 NORETURN void
-return_to_top_level (enum return_reason reason)
+throw_exception (enum return_reason reason)
 {
   quit_flag = 0;
   immediate_quit = 0;
@@ -340,7 +340,7 @@
 
 /* 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 return_to_top_level() or zero 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.
 
@@ -458,7 +458,7 @@
   /* The caller didn't request that the event be caught, relay the
      event to the next containing catch_errors(). */
 
-  return_to_top_level (caught);
+  throw_exception (caught);
 }
 
 int
Index: utils.c
===================================================================
RCS file: /cvs/src/src/gdb/utils.c,v
retrieving revision 1.60
diff -u -r1.60 utils.c
--- utils.c	2002/02/02 15:39:33	1.60
+++ utils.c	2002/02/03 20:17:10
@@ -641,7 +641,7 @@
   ui_file_put (stream, do_write, gdb_stderr);
   fprintf_filtered (gdb_stderr, "\n");
 
-  return_to_top_level (RETURN_ERROR);
+  throw_exception (RETURN_ERROR);
 }
 
 /* Get the last error message issued by gdb */
@@ -724,7 +724,7 @@
     }
 
   dejavu = 0;
-  return_to_top_level (RETURN_ERROR);
+  throw_exception (RETURN_ERROR);
 }
 
 NORETURN void
@@ -846,7 +846,7 @@
     fprintf_unfiltered (gdb_stderr,
 	       "Quit (expect signal SIGINT when the program is resumed)\n");
 #endif
-  return_to_top_level (RETURN_QUIT);
+  throw_exception (RETURN_QUIT);
 }
 
 /* Control C comes here */