[LLDB] Add draft docstrings for SBSaveCoreOptions #123132
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
@llvm/pr-subscribers-lldb Author: Jacob Lalonde (Jlalond) ChangesSBSaveCoreOptions has been around for awhile now, so I decided to draft up some Docstrings describing the functionality better. Some of my wording sounded a bit clunky due the optionality of each method call so I would greatly appreciate feedback. Includes the new method in #122541 so I will merge this as a follow up. Full diff: /~https://github.com/llvm/llvm-project/pull/123132.diff 1 Files Affected:
diff --git a/lldb/bindings/interface/SBSaveCoreOptionsDocstrings.i b/lldb/bindings/interface/SBSaveCoreOptionsDocstrings.i
index e69de29bb2d1d6..44e7b672bd2989 100644
--- a/lldb/bindings/interface/SBSaveCoreOptionsDocstrings.i
+++ b/lldb/bindings/interface/SBSaveCoreOptionsDocstrings.i
@@ -0,0 +1,72 @@
+%feature("docstring",
+"A container for options to use when saving a core file.
+
+SBSaveCoreOptions includes API's to specify the memory regions and threads to include
+when generating a core file. These options are not exclusive the existing SaveCoreStyle option.
+
+Full will save off all thread and memory regions, ignoring the memory regions and threads in
+the options object.
+
+Dirty pages will capture all threads and all rw- memory regions, in addition to the regions specified
+in the options object if they are not already captured.
+
+Stacks will capture all threads, but no memory regions unless specified.
+
+Custom defers entirely to the SBSaveCoreOptions object and will only save what is specified.
+
+Picking custom and specifying nothing will result in an error being returned.
+
+Note that currently ELF Core files are not supported.
+")
+
+%feature("docstring", "
+ Set the plugin name to save a Core file with. Only plugins registered with Plugin manager will be accepted
+ Examples are Minidump and Mach-O."
+) lldb::SBSaveCoreOptions::SetPluginName
+
+%feature("docstring", "
+ Get the specified plugin name, or None if the name is not set."
+) lldb::SBSaveCoreOptions::GetPluginName
+
+%feature("docstring", "
+ Set the lldb.SaveCoreStyle."
+) lldb::SBSaveCoreOptions::SetStyle
+
+%feature("docstring", "
+ Get the specified lldb.SaveCoreStyle, or eSaveCoreUnspecified if not set."
+) lldb::SBSaveCoreOptions::GetStyle
+
+%feature("docstring", "
+ Set the file path to save the Core file at."
+) lldb::SBSaveCoreOptions::SetOutputFile
+
+%feature("docstring", "
+ Get an SBFileSpec corresponding to the specified output path, or none if not set."
+) lldb::SBSaveCoreOptions::GetOutputFile
+
+%feature("docstring", "
+ Set the process to save, or unset a process by providing a default SBProcess.
+ Resetting will result in the reset of all process specific options, such as Threads to save."
+) lldb::SBSaveCoreOptions::SetProcess
+
+%feature("docstring", "
+ Add an SBThread to be saved, an error will be returned if an SBThread from a different process is specified.
+ The process is set either by the first SBThread added to the options container, or explicitly by the SetProcess call."
+) lldb::SBSaveCoreOptions::AddThread
+
+%feature("docstring", "
+ Remove an SBthread if present in the container, returns true if a matching thread was found and removed."
+) lldb::SBSaveCoreOptions::RemoveThread
+
+%feature("docstring", "
+ Add a memory region to save, an error will be returned in the region is invalid.
+ Ranges that overlap will be unioned into a single region."
+) lldb::SBSaveCoreOptions::AddMemoryRegionToSave
+
+%feature("docstring", "
+ Get an SBThreadCollection of all threads marked to be saved. This collection is not sorted according to insertion order."
+) lldb::SBSaveCoreOptions::GetThreadsToSave
+
+%feature("docstring", "
+ Unset all options."
+) lldb::SBSaveCoreOptions::Clear
|
| @@ -0,0 +1,72 @@ | |||
| %feature("docstring", | |||
| "A container for options to use when saving a core file. | |||
There was a problem hiding this comment.
Suggested change
| "A container for options to use when saving a core file. | |
| "A container to specify how to save a core file. |
| "A container for options to use when saving a core file. | ||
|
|
||
| SBSaveCoreOptions includes API's to specify the memory regions and threads to include | ||
| when generating a core file. These options are not exclusive the existing SaveCoreStyle option. |
There was a problem hiding this comment.
Suggested change
| when generating a core file. These options are not exclusive the existing SaveCoreStyle option. | |
| when generating a core file. It extends the existing SaveCoreStyle option. |
Comment on lines
7
to
8
| Full will save off all thread and memory regions, ignoring the memory regions and threads in | ||
| the options object. |
There was a problem hiding this comment.
Suggested change
| Full will save off all thread and memory regions, ignoring the memory regions and threads in | |
| the options object. | |
| eSaveCoreFull will save off all thread and memory regions, ignoring the memory regions and threads in | |
| the options object. |
Maybe make these bullet points to make it clear that you're iterating over the options, something like this:
* eSaveCoreFull: save off all thread and memory regions, ignoring the memory regions and threads specified in this option object.
There was a problem hiding this comment.
Sweet, I wanted to do a list but didn't realize if the docstrings supported markdown.
… a bullet point list
|
Hey @JDevlieghere, bump for this patch but also a follow up question. Do I need to manually add docstrings for the constructors for SBProgress, the webpage reflects the method but not the constructor(s). |
|
LLVM Buildbot has detected a new failure on builder Full details are available at: https://lab.llvm.org/buildbot/#/builders/181/builds/12112 Here is the relevant piece of the build log for the reference |
|
LLVM Buildbot has detected a new failure on builder Full details are available at: https://lab.llvm.org/buildbot/#/builders/162/builds/14562 Here is the relevant piece of the build log for the reference |
|
@Jlalond This seems to be breaking the LLDB build on multiple bots, can you take a look and revert if you need time to investigate?
|
|
@dyung Yeah, I'll revert and I'll figure it out tomorrow |
Jlalond
added a commit
that referenced
this pull request
Jan 22, 2025
github-actions bot
pushed a commit
to arm/arm-toolchain
that referenced
this pull request
Jan 22, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
SBSaveCoreOptions has been around for awhile now, so I decided to draft up some Docstrings describing the functionality better. Some of my wording sounded a bit clunky due the optionality of each method call so I would greatly appreciate feedback.
Includes the new method in #122541 so I will merge this as a follow up.