[PATCH] [gdb/python] Document quit_force uses

[Tom de Vries <tdevries@suse.de>]

The Python extension has two functions that convert exceptions from the GDB
domain to the Python domain and vice versa: gdbpy_convert_exception and
gdbpy_handle_exception.

Each function has an exception though, where it calls quit_force:
- for gdbpy_convert_exception, when handling gdb_exception_forced_quit, and
- for gdbpy_handle_exception, when handling SystemExit.

I think it's a good idea to document these exceptions in more detail, and
since AFAICT the reasoning is the same, I've added the same comment in both
places.
---
 gdb/python/py-utils.c | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/gdb/python/py-utils.c b/gdb/python/py-utils.c
index a831b96eb38..1c68b206601 100644
--- a/gdb/python/py-utils.c
+++ b/gdb/python/py-utils.c
@@ -221,7 +221,14 @@ gdbpy_convert_exception (const struct gdb_exception &exception)
   if (exception.reason == RETURN_QUIT)
     exc_class = PyExc_KeyboardInterrupt;
   else if (exception.reason == RETURN_FORCED_QUIT)
-    quit_force (NULL, 0);
+    {
+      /* Ideally we'd like to propagate the exception to top-level, where
+	 we'll call quit_force.  Propagating the exception would ensure that
+	 appropriate cleanups are run.
+	 OTOH, there is the risk that the exception will be swallowed.
+	 For now, don't take this risk and immediately call quit_force.  */
+      quit_force (NULL, 0);
+    }
   else if (exception.error == MEMORY_ERROR)
     exc_class = gdbpy_gdb_memory_error;
   else
@@ -485,6 +492,11 @@ gdbpy_handle_exception ()
 	  exit_arg = 1;
 	}
 
+      /* Ideally we'd like to propagate the exception to top-level, where
+	 we'll call quit_force.  Propagating the exception would ensure that
+	 appropriate cleanups are run.
+	 OTOH, there is the risk that the exception will be swallowed.
+	 For now, don't take this risk and immediately call quit_force.  */
       quit_force (&exit_arg, 0);
     }
   else if (! fetched_error.type_matches (gdbpy_gdberror_exc)

base-commit: 8e6c4f526a68b796b7bd71d53e4dc459ac56c3ef
-- 
2.51.0