Trait profiler_get_symbols::FileAndPathHelper [−][src]
pub trait FileAndPathHelper {
type F: FileContents;
fn get_candidate_paths_for_binary_or_pdb(
&self,
debug_name: &str,
breakpad_id: &str
) -> FileAndPathHelperResult<Vec<CandidatePathInfo>>;
fn open_file(
&self,
path: &Path
) -> Pin<Box<dyn OptionallySendFuture<Output = FileAndPathHelperResult<Self::F>>>>;
fn get_candidate_paths_for_pdb(
&self,
_debug_name: &str,
_breakpad_id: &str,
pdb_path_as_stored_in_binary: &CStr,
_binary_path: &Path
) -> FileAndPathHelperResult<Vec<PathBuf>> { ... }
}
Expand description
This is the trait that consumers need to implement so that they can call
the main entry points of this crate. This crate contains no direct file
access - all access to the file system is via this trait, and its associated
trait FileContents
.
Associated Types
type F: FileContents
Required methods
fn get_candidate_paths_for_binary_or_pdb(
&self,
debug_name: &str,
breakpad_id: &str
) -> FileAndPathHelperResult<Vec<CandidatePathInfo>>
fn get_candidate_paths_for_binary_or_pdb(
&self,
debug_name: &str,
breakpad_id: &str
) -> FileAndPathHelperResult<Vec<CandidatePathInfo>>
Given a “debug name” and a “breakpad ID”, return a list of file paths which may potentially have artifacts containing symbol data for the requested binary (executable or library).
The symbolication methods will try these paths one by one, calling
open_file
for each until it succeeds and finds a file whose contents
match the breakpad ID. Any remaining paths are discarded.
Arguments
debug_name
: On Windows, this is the filename of the associated PDB file of the executable / DLL, for example “firefox.pdb” or “xul.pdb”. On non-Windows, this is the filename of the binary, for example “firefox” or “XUL” or “libxul.so”.breakpad_id
: A string of 33 hex digits, serving as a hash of the contents of the binary / library. On Windows, this is 32 digits “signature” plus one digit of “pdbAge”. On non-Windows, this is the binary’s UUID (ELF id or mach-o UUID) plus a “0” digit at the end (replacing the pdbAge).
fn open_file(
&self,
path: &Path
) -> Pin<Box<dyn OptionallySendFuture<Output = FileAndPathHelperResult<Self::F>>>>
fn open_file(
&self,
path: &Path
) -> Pin<Box<dyn OptionallySendFuture<Output = FileAndPathHelperResult<Self::F>>>>
This method is the entry point for file access during symbolication.
The implementer needs to return an object which implements the FileContents
trait.
This method is asynchronous, but once it returns, the file data needs to be
available synchronously because the FileContents
methods are synchronous.
If there is no file at the requested path, an error should be returned (or in any
other error case).
Provided methods
fn get_candidate_paths_for_pdb(
&self,
_debug_name: &str,
_breakpad_id: &str,
pdb_path_as_stored_in_binary: &CStr,
_binary_path: &Path
) -> FileAndPathHelperResult<Vec<PathBuf>>
fn get_candidate_paths_for_pdb(
&self,
_debug_name: &str,
_breakpad_id: &str,
pdb_path_as_stored_in_binary: &CStr,
_binary_path: &Path
) -> FileAndPathHelperResult<Vec<PathBuf>>
This method can usually be ignored and does not need to be implemented; its default implementation is usually what you want.
This is called in the following case: Let’s say you’re trying to look up symbols
for “example.pdb”. The implementer of this trait might not know the location of
a suitable “example.pdb”, but they might know the location of a relevant “example.exe”.
They can return the path to the “example.exe” from get_candidate_paths_for_binary_or_pdb
.
Symbolication will look at the exe file, and find a PDB reference inside it, with an
absolute path to a PDB file. Then this method will be called, allowing the trait
implementer to add more PDB candidate paths based on the PDB path from the exe.
I’m actually not sure when that ability would ever be useful. Maybe this method should just be removed again.