gdb/python: introduce gdb.TargetConnection object type

This commit adds a new object type gdb.TargetConnection.  This new
type represents a connection within GDB (a connection as displayed by
'info connections').

There's three ways to find a gdb.TargetConnection, there's a new
'gdb.connections()' function, which returns a list of all currently
active connections.

Or you can read the new 'connection' property on the gdb.Inferior
object type, this contains the connection for that inferior (or None
if the inferior has no connection, for example, it is exited).

Finally, there's a new gdb.events.connection_removed event registry,
this emits a new gdb.ConnectionEvent whenever a connection is removed
from GDB (this can happen when all inferiors using a connection exit,
though this is not always the case, depending on the connection type).
The gdb.ConnectionEvent has a 'connection' property, which is the
gdb.TargetConnection being removed from GDB.

The gdb.TargetConnection has an 'is_valid()' method.  A connection
object becomes invalid when the underlying connection is removed from
GDB (as discussed above, this might be when all inferiors using a
connection exit, or it might be when the user explicitly replaces a
connection in GDB by issuing another 'target' command).

The gdb.TargetConnection has the following read-only properties:

  'num': The number for this connection,

  'type': e.g. 'native', 'remote', 'sim', etc

  'description': The longer description as seen in the 'info
                 connections' command output.

  'details': A string or None.  Extra details for the connection, for
             example, a remote connection's details might be
             'hostname:port'.

5 files changed, 211 insertions, 2 deletions

diff --git a/gdb/testsuite/gdb.multi/multi-target-info-inferiors.exp b/gdb/testsuite/gdb.multi/multi-target-info-inferiors.exp
index 3fd6b15..3f74a47 100644
--- a/gdb/testsuite/gdb.multi/multi-target-info-inferiors.exp
+++ b/gdb/testsuite/gdb.multi/multi-target-info-inferiors.exp
@@ -15,18 +15,27 @@
 
 # Test "info inferiors" and "info connections" with multiple targets.
 
+load_lib gdb-python.exp
+
 source $srcdir/$subdir/multi-target.exp.tcl
 
 if {![multi_target_prepare]} {
     return
 }
 
+# Cache the result of calling skip_python_tests into a local variable.
+set run_python_tests [expr ! [skip_python_tests]]
+
 # Test "info inferiors" and "info connections".  MULTI_PROCESS
 # indicates whether the multi-process feature of remote targets is
 # turned off or on.
 proc test_info_inferiors {multi_process} {
     setup "off"
 
+    if { $::run_python_tests } {
+	gdb_test_no_output "source ${::remote_python_file}" "load python file"
+    }
+
     gdb_test_no_output \
 	"set remote multiprocess-feature-packet $multi_process"
 
@@ -86,6 +95,18 @@ proc test_info_inferiors {multi_process} {
 		     "[connection_num 5 $inf]${ws}core${ws}Local core dump file${ws}" \
 		    ]
 
+	    if { $::run_python_tests } {
+		gdb_test "python info_connections()" \
+		    [multi_line \
+			 "Num${ws}What${ws}Description" \
+			 "[connection_num 1 $inf]${ws}native${ws}Native process" \
+			 "[connection_num 2 $inf]${ws}extended-remote localhost:$decimal${ws}Extended remote serial target in gdb-specific protocol" \
+			 "[connection_num 3 $inf]${ws}core${ws}Local core dump file" \
+			 "[connection_num 4 $inf]${ws}extended-remote localhost:$decimal${ws}Extended remote serial target in gdb-specific protocol" \
+			 "[connection_num 5 $inf]${ws}core${ws}Local core dump file" \
+			]
+	    }
+
 	    gdb_test "info inferiors" \
 		[multi_line \
 		     "Num${ws}Description${ws}Connection${ws}Executable${ws}" \
@@ -96,10 +117,27 @@ proc test_info_inferiors {multi_process} {
 		     "[inf_desc 5 $inf]4 \\(extended-remote localhost:$decimal\\)${ws}${binfile}${ws}" \
 		     "[inf_desc 6 $inf]5 \\(core\\)${ws}${binfile}${ws}" \
 		    ]
+
+	    if { $::run_python_tests } {
+		gdb_test "python info_inferiors()" \
+		    [multi_line \
+		     "Inferior 1, Connection #1: native" \
+		     "Inferior 2, Connection #2: extended-remote localhost:$decimal" \
+		     "Inferior 3, Connection #3: core" \
+		     "Inferior 4, Connection #1: native" \
+		     "Inferior 5, Connection #4: extended-remote localhost:$decimal" \
+		     "Inferior 6, Connection #5: core" \
+		    ]
+	    }
 	}
     }
 }
 
+if { $run_python_tests } {
+    set remote_python_file [gdb_remote_download host \
+				${srcdir}/${subdir}/${testfile}.py]
+}
+
 # Test "info inferiors" and "info connections" commands.
 with_test_prefix "info-inferiors" {
     foreach_with_prefix multi_process {"on" "off"} {
diff --git a/gdb/testsuite/gdb.multi/multi-target-info-inferiors.py b/gdb/testsuite/gdb.multi/multi-target-info-inferiors.py
new file mode 100644
index 0000000..78c82f2
--- /dev/null
+++ b/gdb/testsuite/gdb.multi/multi-target-info-inferiors.py
@@ -0,0 +1,64 @@
+# Copyright (C) 2021 Free Software Foundation, Inc.
+
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import gdb
+
+# Take a gdb.TargetConnection and return the connection number.
+def conn_num(c):
+    return c.num
+
+# Takes a gdb.TargetConnection and return a string that is either the
+# type, or the type and details (if the details are not None).
+def make_target_connection_string(c):
+    if c.details is None:
+        return c.type
+    else:
+        return "%s %s" % (c.type, c.details)
+
+# A Python implementation of 'info connections'.  Produce output that
+# is identical to the output of 'info connections' so we can check
+# that aspects of gdb.TargetConnection work correctly.
+def info_connections():
+    all_connections = sorted(gdb.connections(), key=conn_num)
+    current_conn = gdb.selected_inferior().connection
+    what_width = 0
+    for c in all_connections:
+        s = make_target_connection_string(c)
+        if len(s) > what_width:
+            what_width = len(s)
+
+    fmt = "  Num  %%-%ds  Description" % what_width
+    print(fmt % "What")
+    fmt = "%%s%%-3d  %%-%ds  %%s" % what_width
+    for c in all_connections:
+        if c == current_conn:
+            prefix = "* "
+        else:
+            prefix = "  "
+
+        print(fmt % (prefix, c.num, make_target_connection_string(c),
+                     c.description))
+
+def inf_num(i):
+    return i.num
+
+# Print information about each inferior, and the connection it is
+# using.
+def info_inferiors():
+    all_inferiors = sorted(gdb.inferiors(), key=inf_num)
+    for i in gdb.inferiors():
+        print("Inferior %d, Connection #%d: %s" %
+              (i.num, i.connection_num,
+               make_target_connection_string(i.connection)))
diff --git a/gdb/testsuite/gdb.python/py-connection.c b/gdb/testsuite/gdb.python/py-connection.c
new file mode 100644
index 0000000..4b32e70
--- /dev/null
+++ b/gdb/testsuite/gdb.python/py-connection.c
@@ -0,0 +1,22 @@
+/* This testcase is part of GDB, the GNU debugger.
+
+   Copyright 2021 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or modify
+   it under the terms of the GNU General Public License as published by
+   the Free Software Foundation; either version 3 of the License, or
+   (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program.  If not, see  <http://www.gnu.org/licenses/>.  */
+
+int
+main (void)
+{
+  return 0;
+}
diff --git a/gdb/testsuite/gdb.python/py-connection.exp b/gdb/testsuite/gdb.python/py-connection.exp
new file mode 100644
index 0000000..b805b05
--- /dev/null
+++ b/gdb/testsuite/gdb.python/py-connection.exp
@@ -0,0 +1,69 @@
+# Copyright (C) 2021 Free Software Foundation, Inc.
+
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+# This file is for testing the gdb.TargetConnection API.  This API is
+# already tested in gdb.multi/multi-target-info-inferiors.exp and
+# gdb.python/py-inferior.exp, this file just covers some edge cases
+# that are not tested in other places.
+
+load_lib gdb-python.exp
+
+standard_testfile
+
+if { [prepare_for_testing "failed to prepare" ${testfile} ${srcfile}] } {
+    return -1
+}
+
+# Skip all tests if Python scripting is not enabled.
+if { [skip_python_tests] } { continue }
+
+if ![runto_main] then {
+    return 0
+}
+
+# Create a gdb.TargetConnection object and check it is initially
+# valid.
+gdb_test_no_output "python conn = gdb.selected_inferior().connection"
+gdb_test "python print(conn)" \
+    "<gdb.TargetConnection num=1, what=\"\[^\"\]+\">" \
+    "print gdb.TargetConnection while it is still valid"
+gdb_test "python print(conn.is_valid())" "True" "is_valid returns True"
+
+# Get the connection again, and ensure we get the exact same object.
+gdb_test_no_output "python conn2 = gdb.selected_inferior().connection"
+gdb_test "python print('Same object: %s' % (conn is conn2))" "True"
+
+# Now invalidate the connection, and ensure that the is_valid method
+# starts to return False.
+gdb_test "info connections" "\r\n\\* 1 .*" \
+    "info connections while the connection is still around"
+gdb_test "disconnect" "" "kill the inferior" \
+    "A program is being debugged already\\.  Kill it\\? .*y or n. $" "y"
+gdb_test "info connections" "No connections\\." \
+    "info connections now all the connections have gone"
+gdb_test "python print(conn)" "<gdb.TargetConnection \\(invalid\\)>" \
+    "print gdb.TargetConnection now its invalid"
+gdb_test "python print(conn.is_valid())" "False" "is_valid returns False"
+
+# Now check that accessing properties of the invalid connection cases
+# an error.
+gdb_test "python print(conn.num)" \
+    "RuntimeError: Connection no longer exists\\.\r\n.*"
+gdb_test "python print(conn.type)" \
+    "RuntimeError: Connection no longer exists\\.\r\n.*"
+gdb_test "python print(conn.description)" \
+    "RuntimeError: Connection no longer exists\\.\r\n.*"
+gdb_test "python print(conn.details)" \
+    "RuntimeError: Connection no longer exists\\.\r\n.*"
diff --git a/gdb/testsuite/gdb.python/py-inferior.exp b/gdb/testsuite/gdb.python/py-inferior.exp
index 894b90a..d5d284a 100644
--- a/gdb/testsuite/gdb.python/py-inferior.exp
+++ b/gdb/testsuite/gdb.python/py-inferior.exp
@@ -51,6 +51,8 @@ gdb_py_test_silent_cmd "python i0 = inferiors\[0\]" "get first inferior" 0
 gdb_test "python print ('result = %s' % (i0 == inferiors\[0\]))" " = True" "test equality comparison (true)"
 gdb_test "python print ('result = %s' % i0.num)" " = \[0-9\]+" "test Inferior.num"
 gdb_test "python print ('result = %s' % i0.connection_num)" " = \[0-9\]+" "test Inferior.connection_num"
+gdb_test "python print ('result = %s' % (i0.connection_num == i0.connection.num))" " = True" \
+    "Inferior.connection_num equals Inferior.connection.num"
 gdb_test "python print ('result = %s' % i0.pid)" " = \[0-9\]+" "test Inferior.pid"
 gdb_test "python print ('result = %s' % i0.was_attached)" " = False" "test Inferior.was_attached"
 gdb_test "python print (i0.threads ())" "\\(<gdb.InferiorThread object at 0x\[\[:xdigit:\]\]+>,\\)" "test Inferior.threads"
@@ -264,6 +266,8 @@ with_test_prefix "is_valid" {
 	"RuntimeError: Inferior no longer exists.*"
     gdb_test "python print (inf_list\[1\].connection_num)" \
 	"RuntimeError: Inferior no longer exists.*"
+    gdb_test "python print (inf_list\[1\].connection)" \
+	"RuntimeError: Inferior no longer exists.*"
     gdb_test "python print (inf_list\[1\].pid)" \
 	"RuntimeError: Inferior no longer exists.*"
     gdb_test "python print (inf_list\[1\].was_attached)" \
@@ -281,7 +285,9 @@ with_test_prefix "selected_inferior" {
     gdb_test "inferior 1" ".*" "switch to first inferior"
     gdb_test "py print (gdb.selected_inferior().num)" "1" "first inferior selected"
     gdb_test "py print (gdb.selected_inferior().connection_num)" "1" \
-	"first inferior's connection"
+	"first inferior's connection number"
+    gdb_test "py print (gdb.selected_inferior().connection.num)" "1" \
+	"first inferior's connection number, though connection object"
     # Figure out if inf 1 has a native target.
     set inf_1_is_native [gdb_is_target_native]
 
@@ -289,6 +295,8 @@ with_test_prefix "selected_inferior" {
     gdb_test "inferior 3" ".*" "switch to third inferior"
     gdb_test "py print (gdb.selected_inferior().num)" "3" "third inferior selected"
     gdb_test "py print (gdb.selected_inferior().connection_num)" "None" \
+	"third inferior's None connection number"
+    gdb_test "py print (gdb.selected_inferior().connection)" "None" \
 	"third inferior's None connection"
     gdb_test "target native" "Done.  Use the \"run\" command to start a process." \
 	"target for the third inferior"
@@ -302,7 +310,15 @@ with_test_prefix "selected_inferior" {
     }
     gdb_test "py print (gdb.selected_inferior().connection_num)" \
 	"$expected_connection_num" \
-	"third inferior's native connection"
+	"third inferior's native connection number"
+    gdb_test "py print (gdb.selected_inferior().connection.num)" \
+	"$expected_connection_num" \
+	"third inferior's native connection number, though connection object"
+
+    # Test printing of gdb.TargetConnection object.
+    gdb_test "py print (gdb.selected_inferior().connection)" \
+	"<gdb.TargetConnection num=${expected_connection_num}, what=\"\[^\"\]+\">" \
+	"print a connection object"
 
     gdb_test "inferior 1" ".*" "switch back to first inferior"
     gdb_test_no_output "remove-inferiors 3" "remove second inferior"