[4/4] Documentation for python method InferiorThread.thread_handle

  gdb/doc/ChangeLog:

    	* python.texi (Threads In Python): Add description for method
    	InferiorThread.thread_handle.
---
 gdb/doc/python.texi | 8 ++++++++
 1 file changed, 8 insertions(+)
  

> Date: Sat, 15 Sep 2018 22:18:47 -0700
> From: Kevin Buettner <kevinb@redhat.com>
> 
> +@defun InferiorThread.thread_handle (type)
> +Return the thread object's handle.  Since handles are generally opaque
> +objects, the type @var{type} is used to ensure that the correct amount

The phrase "type TYPE is used ..." is awkward.  I suggest to use just
"@var{type", as the name speaks for itself.

Actually, since we want to avoid passive tense, I'd rephrase

  Since various thread handles have different sizes, a Python program
  should supply a suitable @var{type} argument, to ensure @value{GDBN}
  allocates the correct amount of memory for the handle.  E.g., for
  thread handles associated with the @code{pthreads} library, you
  should use @code{gdb.lookup_type('pthread_t')} for @var{type}.

Thanks.
  

>>>>> "Kevin" == Kevin Buettner <kevinb@redhat.com> writes:

Kevin> +@defun InferiorThread.thread_handle (type)
Kevin> +Return the thread object's handle.  Since handles are generally opaque
Kevin> +objects, the type @var{type} is used to ensure that the correct amount
Kevin> +of space is allocated for the returned handle value.  When using handles
Kevin> +associated with the pthreads library, the value passed for @var{type}
Kevin> +should be the result of invoking @code{gdb.lookup_type('pthread_t')}.
Kevin> +@end defun

This API requires the Python programmer to know the type of the
inferior's thread ID.  However, it seems to me that the target also
knows it, or should know it, and so there should be no reason to pass in
the type.

But if a handle is supposed to be opaque, why have a type at all?  It
could just be a bunch of bytes, or even just some completely opaque
object...  but if a completely opaque object would do, why not use the
InferiorThread itself?

I think the code patches all look good.  I didn't even have any nits.
However, exposing some API to Python is more of a commitment and so I'd
like to understand this area and come to an agreement about how it
should work before anything here goes in.

thanks,
Tom
  

On Tue, 18 Sep 2018 05:16:01 -0600
Tom Tromey <tom@tromey.com> wrote:

> >>>>> "Kevin" == Kevin Buettner <kevinb@redhat.com> writes:  
> 
> Kevin> +@defun InferiorThread.thread_handle (type)
> Kevin> +Return the thread object's handle.  Since handles are generally opaque
> Kevin> +objects, the type @var{type} is used to ensure that the correct amount
> Kevin> +of space is allocated for the returned handle value.  When using handles
> Kevin> +associated with the pthreads library, the value passed for @var{type}
> Kevin> +should be the result of invoking @code{gdb.lookup_type('pthread_t')}.
> Kevin> +@end defun  
> 
> This API requires the Python programmer to know the type of the
> inferior's thread ID.  However, it seems to me that the target also
> knows it, or should know it, and so there should be no reason to pass in
> the type.
> 
> But if a handle is supposed to be opaque, why have a type at all?  It
> could just be a bunch of bytes, or even just some completely opaque
> object...  but if a completely opaque object would do, why not use the
> InferiorThread itself?

As discussed in my other reply, I (unfortunately) require the handle to
not be opaque.  I made an error when I wrote the documentation patch.

With regard to passing the type, when debugging a remote target, GDB
won't know the handle type, though it does know the size.  If I were
truly able to work with an opaque object, I wouldn't need the type.
It may still be the case that I don't need it; I'm still pondering this.

I'll eventually post an updated doc patch (and updates to the rest
of the patch series if needed) which will describe the actual state
of affairs with regard to opacity.

> I think the code patches all look good.  I didn't even have any nits.
> However, exposing some API to Python is more of a commitment and so I'd
> like to understand this area and come to an agreement about how it
> should work before anything here goes in.

I've tried to provide the necessary background here:

https://sourceware.org/ml/gdb-patches/2018-09/msg00719.html

Kevin