Skip to content

[LLDB] Add draft docstrings for SBSaveCoreOptions #123132

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jan 21, 2025
Merged

[LLDB] Add draft docstrings for SBSaveCoreOptions #123132

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
dbe6334
Add draft docstrings for SBSaveCoreOptions
Jlalond Jan 14, 2025
5d3745b
Rephrase some sentences, and convert the behavior for each style into…
Jlalond Jan 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 72 additions & 0 deletions lldb/bindings/interface/SBSaveCoreOptionsDocstrings.i
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
%feature("docstring",
"A container for options to use when saving a core file.
Copy link
Member

@JDevlieghere JDevlieghere Jan 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"A container for options to use when saving a core file.
"A container to specify how to save 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.
Copy link
Member

@JDevlieghere JDevlieghere Jan 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


Full will save off all thread and memory regions, ignoring the memory regions and threads in
the options object.
Copy link
Member

@JDevlieghere JDevlieghere Jan 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@Jlalond Jlalond Jan 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sweet, I wanted to do a list but didn't realize if the docstrings supported markdown.


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
Loading