Document lazy computation for pretty-printer "children" method
Commit Message
I found out recently that some users didn't know that the Python
pretty-printers "children" method should compute its result lazily.
This has been a good idea since the earliest days, but wasn't
mentioned in the docs. This patch adds some text to this effect.
gdb/doc/ChangeLog
2019-05-10 Tom Tromey <tromey@adacore.com>
* python.texi (Pretty Printing API): Mention lazy computation for
"children".
---
gdb/doc/ChangeLog | 5 +++++
gdb/doc/python.texi | 6 ++++++
2 files changed, 11 insertions(+)
Comments
> From: Tom Tromey <tromey@adacore.com>
> Cc: Tom Tromey <tromey@adacore.com>
> Date: Fri, 10 May 2019 08:33:23 -0600
>
> I found out recently that some users didn't know that the Python
> pretty-printers "children" method should compute its result lazily.
> This has been a good idea since the earliest days, but wasn't
> mentioned in the docs. This patch adds some text to this effect.
>
> gdb/doc/ChangeLog
> 2019-05-10 Tom Tromey <tromey@adacore.com>
>
> * python.texi (Pretty Printing API): Mention lazy computation for
> "children".
Thanks, this is fine.
@@ -1371,6 +1371,12 @@ object which is convertible to a @value{GDBN} value.
This method is optional. If it does not exist, @value{GDBN} will act
as though the value has no children.
+For efficiency, the @code{children} method should lazily compute its
+results. This will let @value{GDBN} read as few elements as
+necessary, for example when various print settings (@pxref{Print
+Settings}) or @code{-var-list-children} (@pxref{GDB/MI Variable
+Objects}) limit the number of elements to be displayed.
+
Children may be hidden from display based on the value of @samp{set
print max-depth} (@pxref{Print Settings}).
@end defun