https://github.com/labath created
https://github.com/llvm/llvm-project/pull/94192
None
>From 8bb7817d913cd8843fe8c90dcd7c8b70a0366994 Mon Sep 17 00:00:00 2001
From: Pavel Labath <pa...@labath.sk>
Date: Mon, 3 Jun 2024 09:58:47 +0200
Subject: [PATCH] [lldb] Add documentation for the max_children argument
---
lldb/docs/use/variable.rst | 37 +++++++++++++++++++++++----------
lldb/include/lldb/API/SBValue.h | 14 +++++++++++++
2 files changed, 40 insertions(+), 11 deletions(-)
diff --git a/lldb/docs/use/variable.rst b/lldb/docs/use/variable.rst
index e9175b25336ba..22c2bee73fa59 100644
--- a/lldb/docs/use/variable.rst
+++ b/lldb/docs/use/variable.rst
@@ -930,20 +930,27 @@ be implemented by the Python class):
class SyntheticChildrenProvider:
def __init__(self, valobj, internal_dict):
- this call should initialize the Python object using valobj as the
variable to provide synthetic children for
- def num_children(self):
- this call should return the number of children that you want your
object to have
+ this call should initialize the Python object using valobj as the
+ variable to provide synthetic children for
+ def num_children(self, max_children):
+ this call should return the number of children that you want your
+ object to have[1]
def get_child_index(self,name):
- this call should return the index of the synthetic child whose name
is given as argument
+ this call should return the index of the synthetic child whose name is
+ given as argument
def get_child_at_index(self,index):
- this call should return a new LLDB SBValue object representing the
child at the index given as argument
+ this call should return a new LLDB SBValue object representing the
+ child at the index given as argument
def update(self):
- this call should be used to update the internal state of this Python
object whenever the state of the variables in LLDB changes.[1]
+ this call should be used to update the internal state of this Python
+ object whenever the state of the variables in LLDB changes.[2]
Also, this method is invoked before any other method in the interface.
def has_children(self):
- this call should return True if this object might have children, and
False if this object can be guaranteed not to have children.[2]
+ this call should return True if this object might have children, and
+ False if this object can be guaranteed not to have children.[3]
def get_value(self):
- this call can return an SBValue to be presented as the value of the
synthetic value under consideration.[3]
+ this call can return an SBValue to be presented as the value of the
+ synthetic value under consideration.[4]
As a warning, exceptions that are thrown by python formatters are caught
silently by LLDB and should be handled appropriately by the formatter itself.
@@ -951,7 +958,15 @@ Being more specific, in case of exceptions, LLDB might
assume that the given
object has no children or it might skip printing some children, as they are
printed one by one.
-[1] This method is optional. Also, a boolean value must be returned (since lldb
+[1] The `max_children` argument is optional (since lldb 3.8.0) and indicates
the
+maximum number of children that lldb is interested in (at this moment). If the
+computation of the number of children is expensive (for example, requires
+travesing a linked list to determine its size) your implementation may return
+`max_children` rather than the actual number. If the computation is cheap
(e.g., the
+number is stored as a field of the object), then you can always return the true
+number of children (that is, ignore the `max_children` argument).
+
+[2] This method is optional. Also, a boolean value must be returned (since lldb
3.1.0). If ``False`` is returned, then whenever the process reaches a new stop,
this method will be invoked again to generate an updated list of the children
for a given variable. Otherwise, if ``True`` is returned, then the value is
@@ -959,11 +974,11 @@ cached and this method won't be called again, effectively
freezing the state of
the value in subsequent stops. Beware that returning ``True`` incorrectly could
show misleading information to the user.
-[2] This method is optional (since lldb 3.2.0). While implementing it in terms
+[3] This method is optional (since lldb 3.2.0). While implementing it in terms
of num_children is acceptable, implementors are encouraged to look for
optimized coding alternatives whenever reasonable.
-[3] This method is optional (since lldb 3.5.2). The `SBValue` you return here
+[4] This method is optional (since lldb 3.5.2). The `SBValue` you return here
will most likely be a numeric type (int, float, ...) as its value bytes will be
used as-if they were the value of the root `SBValue` proper. As a shortcut for
this, you can inherit from lldb.SBSyntheticValueProvider, and just define
diff --git a/lldb/include/lldb/API/SBValue.h b/lldb/include/lldb/API/SBValue.h
index 8f4c4fd56dfb1..65920c76df7a8 100644
--- a/lldb/include/lldb/API/SBValue.h
+++ b/lldb/include/lldb/API/SBValue.h
@@ -281,8 +281,22 @@ class LLDB_API SBValue {
bool IsRuntimeSupportValue();
+ /// Return the number of children of this variable. Note that for some
+ /// variables this operation can be expensive. If possible, prefer calling
+ /// GetNumChildren(max) with the maximum number of children you are
interested
+ /// in.
uint32_t GetNumChildren();
+ /// Return the numer of children of this variable, with a hint that the
+ /// caller is interested in at most \a max children. Use this function to
+ /// avoid expensive child computations in some cases. For example, if you
know
+ /// you will only ever display 100 elements, calling GetNumChildren(100) can
+ /// avoid enumerating all the other children. If the returned value is
smaller
+ /// than \a max, then it represents the true number of children, otherwise it
+ /// indicates that their number is at least \a max. Do not assume the
returned
+ /// number will always be less than or equal to \a max, as the implementation
+ /// may choose to return a larger (but still smaller than the actual number
of
+ /// children) value.
uint32_t GetNumChildren(uint32_t max);
LLDB_DEPRECATED("SBValue::GetOpaqueType() is deprecated.")
_______________________________________________
lldb-commits mailing list
lldb-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
