[v3,6/6] Rename python function thread_from_thread_handle to thread_from_handle

Message ID 20190320215155.0fbcee63@f29-4.lan
State Superseded
Headers show
Series
  • Add python method gdb.InferiorThread.handle
Related show

Commit Message

Kevin Buettner March 21, 2019, 4:51 a.m.
This renaming was done to stay consistent with the naming of the new
gdb.InferiorThread.handle method.  I had initially named it "thread_handle"
but Tom Tromey suggested just "handle".

The old name (thread_from_thread_handle) still works, but is marked as
deprecated in comments in the code as well as in the documentation.

I have some code which uses these functions.  I very much like the
brevity of the new names.

gdb/doc/ChangeLog:

	* python.texi (Inferiors In Python): Rename
	Inferior.thread_from_thread_handle to Inferior.thread_from_handle.
	Add note about the former being deprecated.

gdb/ChangeLog:

	* python/py-inferior.c (infpy_thread_from_thread_handle):
	Adjust comments to reflect renaming of thread_from_thread_handle
	to thread_from_handle.  Adjust keywords.  Fix type error message.
	(inferior_object_methods): Add thread_from_handle.  Retain
	thread_from_thread_handle, but mark it as deprecated.

testsuite/ChangeLog:

	* gdb.python/py-thrhandle.exp: Adjust tests to call
	thread_from_handle instead of thread_from_thread_handle.
---
 gdb/doc/python.texi                       | 10 +++++++---
 gdb/python/py-inferior.c                  | 12 +++++++++---
 gdb/testsuite/gdb.python/py-thrhandle.exp | 30 +++++++++++++++---------------
 3 files changed, 31 insertions(+), 21 deletions(-)

Comments

Eli Zaretskii March 21, 2019, 2:21 p.m. | #1
> Date: Wed, 20 Mar 2019 21:51:55 -0700

> From: Kevin Buettner <kevinb@redhat.com>

> Cc: Eli Zaretskii <eliz@gnu.org>

> 

> gdb/doc/ChangeLog:

> 

> 	* python.texi (Inferiors In Python): Rename

> 	Inferior.thread_from_thread_handle to Inferior.thread_from_handle.

> 	Add note about the former being deprecated.


This part is OK, with one comment:

> -@findex Inferior.thread_from_thread_handle


Please don't remove this index entry, it will be useful for someone
who sees code which uses the deprecated name and wants to know what
that is.

Thanks.
Kevin Buettner March 21, 2019, 5:09 p.m. | #2
On Thu, 21 Mar 2019 16:21:40 +0200
Eli Zaretskii <eliz@gnu.org> wrote:

> > Date: Wed, 20 Mar 2019 21:51:55 -0700

> > From: Kevin Buettner <kevinb@redhat.com>

> > Cc: Eli Zaretskii <eliz@gnu.org>

> > 

> > gdb/doc/ChangeLog:

> > 

> > 	* python.texi (Inferiors In Python): Rename

> > 	Inferior.thread_from_thread_handle to Inferior.thread_from_handle.

> > 	Add note about the former being deprecated.  

> 

> This part is OK, with one comment:

> 

> > -@findex Inferior.thread_from_thread_handle  

> 

> Please don't remove this index entry, it will be useful for someone

> who sees code which uses the deprecated name and wants to know what

> that is.


I was wondering about that when I made the change.  I've restored the
index entry in my local sources.  Here's what that part of it looks like
now:

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 2a5a5cde3d..ab191b620c 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -2906,11 +2906,16 @@ containing the address where the pattern was found, or @code{None} if
 the pattern could not be found.
 @end defun
 
+@findex Inferior.thread_from_handle
 @findex Inferior.thread_from_thread_handle
-@defun Inferior.thread_from_thread_handle (thread_handle)
-Return the thread object corresponding to @var{thread_handle}, a thread
+@defun Inferior.thread_from_handle (handle)
+Return the thread object corresponding to @var{handle}, a thread
 library specific data structure such as @code{pthread_t} for pthreads
 library implementations.
+
+The function @code{Inferior.thread_from_thread_handle} provides
+the same functionality, but use of @code{Inferior.thread_from_thread_handle}
+is deprecated.
 @end defun
 
 @node Events In Python
Eli Zaretskii March 21, 2019, 6:26 p.m. | #3
> Date: Thu, 21 Mar 2019 10:09:07 -0700

> From: Kevin Buettner <kevinb@redhat.com>

> Cc: Eli Zaretskii <eliz@gnu.org>

> 

> > > -@findex Inferior.thread_from_thread_handle  

> > 

> > Please don't remove this index entry, it will be useful for someone

> > who sees code which uses the deprecated name and wants to know what

> > that is.

> 

> I was wondering about that when I made the change.  I've restored the

> index entry in my local sources.  Here's what that part of it looks like

> now:


LGTM, thanks.

Patch

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 2a5a5cde3d..fd82cdeea0 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -2906,11 +2906,15 @@  containing the address where the pattern was found, or @code{None} if
 the pattern could not be found.
 @end defun
 
-@findex Inferior.thread_from_thread_handle
-@defun Inferior.thread_from_thread_handle (thread_handle)
-Return the thread object corresponding to @var{thread_handle}, a thread
+@findex Inferior.thread_from_handle
+@defun Inferior.thread_from_handle (handle)
+Return the thread object corresponding to @var{handle}, a thread
 library specific data structure such as @code{pthread_t} for pthreads
 library implementations.
+
+The function @code{Inferior.thread_from_thread_handle} provides
+the same functionality, but use of @code{Inferior.thread_from_thread_handle}
+is deprecated.
 @end defun
 
 @node Events In Python
diff --git a/gdb/python/py-inferior.c b/gdb/python/py-inferior.c
index 7129815b21..36c9a65049 100644
--- a/gdb/python/py-inferior.c
+++ b/gdb/python/py-inferior.c
@@ -759,7 +759,7 @@  infpy_is_valid (PyObject *self, PyObject *args)
   Py_RETURN_TRUE;
 }
 
-/* Implementation of gdb.Inferior.thread_from_thread_handle (self, handle)
+/* Implementation of gdb.Inferior.thread_from_handle (self, handle)
                         ->  gdb.InferiorThread.  */
 
 static PyObject *
@@ -767,7 +767,7 @@  infpy_thread_from_thread_handle (PyObject *self, PyObject *args, PyObject *kw)
 {
   PyObject *handle_obj;
   inferior_object *inf_obj = (inferior_object *) self;
-  static const char *keywords[] = { "thread_handle", NULL };
+  static const char *keywords[] = { "handle", NULL };
 
   INFPY_REQUIRE_VALID (inf_obj);
 
@@ -795,7 +795,7 @@  infpy_thread_from_thread_handle (PyObject *self, PyObject *args, PyObject *kw)
   else
     {
       PyErr_SetString (PyExc_TypeError,
-		       _("Argument 'handle_obj' must be a thread handle object."));
+		       _("Argument 'handle' must be a thread handle object."));
 
       return NULL;
     }
@@ -961,9 +961,15 @@  Write the given buffer object to the inferior's memory." },
     METH_VARARGS | METH_KEYWORDS,
     "search_memory (address, length, pattern) -> long\n\
 Return a long with the address of a match, or None." },
+  /* thread_from_thread_handle is deprecated.  */
   { "thread_from_thread_handle", (PyCFunction) infpy_thread_from_thread_handle,
     METH_VARARGS | METH_KEYWORDS,
     "thread_from_thread_handle (handle) -> gdb.InferiorThread.\n\
+Return thread object corresponding to thread handle.\n\
+This method is deprecated - use thread_from_handle instead." },
+  { "thread_from_handle", (PyCFunction) infpy_thread_from_thread_handle,
+    METH_VARARGS | METH_KEYWORDS,
+    "thread_from_handle (handle) -> gdb.InferiorThread.\n\
 Return thread object corresponding to thread handle." },
   { "architecture", (PyCFunction) infpy_architecture, METH_NOARGS,
     "architecture () -> gdb.Architecture\n\
diff --git a/gdb/testsuite/gdb.python/py-thrhandle.exp b/gdb/testsuite/gdb.python/py-thrhandle.exp
index 57b97faa18..19c690be14 100644
--- a/gdb/testsuite/gdb.python/py-thrhandle.exp
+++ b/gdb/testsuite/gdb.python/py-thrhandle.exp
@@ -16,7 +16,7 @@ 
 # Please email any bugs, comments, and/or additions to this file to:
 # bug-gdb@gnu.org
 
-# This file verifies that methods Inferior.thread_from_thread_handle
+# This file verifies that methods Inferior.thread_from_handle
 # and InferiorThread.handle work as expected.
 
 load_lib gdb-python.exp
@@ -67,44 +67,44 @@  gdb_test "info threads"  \
 	{.*[\r\n]+\* +([0-9]+) +Thread[^\r\n]* do_something \(n=\1\) at.*}
 
 # Check for expected results when passing a valid thread handle to
-# thread_from_thread_handle().
+# thread_from_handle().
 
-gdb_test "python print(gdb.selected_inferior().thread_from_thread_handle(gdb.parse_and_eval('thrs\[0\]')).num)" \
+gdb_test "python print(gdb.selected_inferior().thread_from_handle(gdb.parse_and_eval('thrs\[0\]')).num)" \
 	"1" "print thread id for thrs\[0\]"
 
-gdb_test "python print(gdb.selected_inferior().thread_from_thread_handle(gdb.parse_and_eval('thrs\[1\]')).num)" \
+gdb_test "python print(gdb.selected_inferior().thread_from_handle(gdb.parse_and_eval('thrs\[1\]')).num)" \
 	"2" "print thread id for thrs\[1\]"
 
-gdb_test "python print(gdb.selected_inferior().thread_from_thread_handle(gdb.parse_and_eval('thrs\[2\]')).num)" \
+gdb_test "python print(gdb.selected_inferior().thread_from_handle(gdb.parse_and_eval('thrs\[2\]')).num)" \
 	"3" "print thread id for thrs\[2\]"
 
 # Objects which are of the correct size, but which are bogus thread
 # handles should return None.  For the first test (using thrs[3]), we
 # use 0.  For the second (thrs[4]), we use an unlikely bit pattern.
 
-gdb_test "python print(gdb.selected_inferior().thread_from_thread_handle(gdb.parse_and_eval('thrs\[3\]')))" \
+gdb_test "python print(gdb.selected_inferior().thread_from_handle(gdb.parse_and_eval('thrs\[3\]')))" \
 	"None" "print thread for bogus handle thrs\[3\]"
 
-gdb_test "python print(gdb.selected_inferior().thread_from_thread_handle(gdb.parse_and_eval('thrs\[4\]')))" \
+gdb_test "python print(gdb.selected_inferior().thread_from_handle(gdb.parse_and_eval('thrs\[4\]')))" \
 	"None" "print thread for bogus handle thrs\[4\]"
 
 # We should see an exception when passing an object of the wrong type.
 
-gdb_test "python print(gdb.selected_inferior().thread_from_thread_handle(gdb.lookup_symbol('main')))" \
-         ".*TypeError: Argument 'handle_obj' must be a thread handle object.*" \
-	 "TypeError when passing a symbol object to thread_from_thread_handle"
+gdb_test "python print(gdb.selected_inferior().thread_from_handle(gdb.lookup_symbol('main')))" \
+         ".*TypeError: Argument 'handle' must be a thread handle object.*" \
+	 "TypeError when passing a symbol object to thread_from_handle"
 
 # We should see an exception when passing too large of an object.
 
-gdb_test "python print(gdb.selected_inferior().thread_from_thread_handle(gdb.parse_and_eval('thrs')))" \
+gdb_test "python print(gdb.selected_inferior().thread_from_handle(gdb.parse_and_eval('thrs')))" \
          ".*Thread handle size mismatch.*" \
-	 "Pass overly large object to thread_from_thread_handle"
+	 "Pass overly large object to thread_from_handle"
 
 # We should see an exception when passing too small of an object.
 
-gdb_test "python print(gdb.selected_inferior().thread_from_thread_handle(gdb.parse_and_eval('\"S\"')))" \
+gdb_test "python print(gdb.selected_inferior().thread_from_handle(gdb.parse_and_eval('\"S\"')))" \
          ".*Thread handle size mismatch.*" \
-	 "Pass too small of an object to thread_from_thread_handle"
+	 "Pass too small of an object to thread_from_handle"
 
 # Test the thread_handle method
 
@@ -121,7 +121,7 @@  foreach thrN {0 1 2} {
 	    1
 
 	gdb_py_test_silent_cmd \
-	    "python hand_bytes = inf.thread_from_thread_handle(hand).handle()" \
+	    "python hand_bytes = inf.thread_from_handle(hand).handle()" \
 	    "fetch thread handle from thread" \
 	    1