This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: [python][patch] Inferior and Thread information support.
- From: Eli Zaretskii <eliz at gnu dot org>
- To: Phil Muldoon <pmuldoon at redhat dot com>
- Cc: gdb-patches at sourceware dot org
- Date: Mon, 24 May 2010 21:04:30 +0300
- Subject: Re: [python][patch] Inferior and Thread information support.
- References: <4BFA6E82.3070704@redhat.com>
- Reply-to: Eli Zaretskii <eliz at gnu dot org>
> Date: Mon, 24 May 2010 13:18:10 +0100
> From: Phil Muldoon <pmuldoon@redhat.com>
>
> This patch adds Python support to inferiors and threads.
Thanks. A few comments about the documentation parts:
> +@node Inferiors In Python
> +@subsubsection Inferiors In Python
It is usually a good idea to have a @cindex entry at the beginning of
a section whose name is identical to the section name (except all
lower-case).
> +Programs which are being run under @value{GDBN} are called inferiors
> +(@pxref{Inferiors and Programs}). Python scripts can access
> +information about and manipulate inferiors controlled by @value{GDBN}
> +via objects of the @code{gdb.Inferior} class.
This should probable have a @findex entry for gdb.Inferior.
> +@defmethod Inferior threads
> +This method returns a tuple holding all the threads which are valid
> +when it is called. If there are no valid threads, the method will
> +return an empty list.
Are "list" and "tuple" synonyms in Python? If not, perhaps this needs
a slight rewording.
> +@defmethod Inferior read_memory @var{address} @var{length}
I don't think you need @var around the arguments of this method (or
any other methods in the patch). You only need @var if an argument
includes characters treated specially by Texinfo.
> +Write the contents of @var{buffer} (a Python object which supports the
> +buffer protocol, i.e., a string, an array or the object returned from
> +@code{gdb.read_memory}) to the inferior, starting at @var{address}.
I wonder whether a buffer object warrants a separate short description
which is not in parens in the middle of describing a method.
> +@defmethod Inferior search_memory @var{address} @var{length} @var{pattern} @r{[}@var{size}@r{]} @r{[}@var{max_count}@r{]}
> +Search a region of the inferior memory starting at @var{address} with the
> +given @var{length}. @var{pattern} can be a string, a byte array, a buffer
> +object, a number, a @code{gdb.Value} object (@pxref{Values From Inferior})
> +or a list or tuple with elements in any combination of those types.
The semantics of tuple or list as PATTERN is not explained here.
> If @var{size} is
> +zero or not specified, it is taken from the value's type in the current
> +language.
What does this mean if PATTERN is a tuple or a list?
> This is useful when one wants to specify the search pattern as
> +a mixture of types.
Is "mixture of types" intended to cover the list/tuple case? If so, I
suggest to use identical words, to minimize the chance of confusing
the reader with terminology that is never explained.
> +@node Threads In Python
> +@subsubsection Threads In Python
See the comment above regarding a @cindex entry here.
> +Python scripts can access information about, and manipulate inferior threads
> +controlled by @value{GDBN}, via objects of the @code{gdb.InferiorThread} class.
And @findex here regarding gdb.InferiorThread.
> +@defivar InferiorThread num
> +ID of the thread, as assigned by GDB.
^^^
@value{GDBN}.
Okay with those changes.
In addition, I think we need a NEWS entry for these features.
Thanks.