FreeChainXenon/binutils-gdb
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

gdb/doc: add some notes on selecting suitable attribute names

Browse source 
In previous commits I've added Object.__dict__ support to gdb.Inferior
and gdb.InferiorThread, this is similar to the existing support for
gdb.Objfile and gdb.Progspace.

This commit extends the documentation to offer the user some guidance
on selecting good names for their custom attributes so they
can (hopefully) avoid conflicting with any future attributes that GDB
might add.

The rules I've proposed are:

  1. Don't start user attributes with a lower case letter, all the
  current GDB attributes start with a lower case letter, and I suspect
  all future attributes would also start with a lower case letter, and

  2. Don't start user attributes with a double underscore, this risks
  conflicting with Python built in attributes (e.g. __dict__) - though
  clearly the user would need to start and end with a double
  underscore, but it seemed easier just to say no double underscores.

I'm doing this as a separate commit as I've updated the docs for the
existing gdb.Objfile and gdb.Progspace so they all reference a single
paragraph on selecting attribute names.

Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Tom Tromey <tom@tromey.com>
This commit is contained in:
Andrew Burgess 2024-01-10 15:42:55 +00:00
parent 1d586eda5c
commit 53d0889088
1 changed files with 16 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
gdb/doc/python.texi
View file

@ -3671,6 +3671,13 @@ One may add arbitrary attributes to @code{gdb.Inferior} objects in the
usual Python way. This is useful if, for example, one needs to do
some extra record keeping associated with the inferior.
@anchor{choosing attribute names}
When selecting a name for a new attribute, avoid starting the new
attribute name with a lower case letter; future attributes added by
@value{GDBN} will start with a lower case letter. Additionally, avoid
starting attribute names with two underscore characters, as these
could clash with Python builtin attribute names.
In this contrived example we record the time when an inferior last
stopped:
@ -4188,6 +4195,9 @@ One may add arbitrary attributes to @code{gdb.InferiorThread} objects
in the usual Python way. This is useful if, for example, one needs to
do some extra record keeping associated with the thread.
@xref{choosing attribute names}, for guidance on selecting a suitable
name for new attributes.
In this contrived example we record the time when a thread last
stopped:
@ -5403,6 +5413,9 @@ in the usual Python way.
This is useful if, for example, one needs to do some extra record keeping
associated with the program space.
@xref{choosing attribute names}, for guidance on selecting a suitable
name for new attributes.
In this contrived example, we want to perform some processing when
an objfile with a certain symbol is loaded, but we only want to do
this once because it is expensive. To achieve this we record the results
@ -5563,6 +5576,9 @@ in the usual Python way.
This is useful if, for example, one needs to do some extra record keeping
associated with the objfile.
@xref{choosing attribute names}, for guidance on selecting a suitable
name for new attributes.
In this contrived example we record the time when @value{GDBN}
loaded the objfile.