Trait profiler_get_symbols::FileAndPathHelper

pub trait FileAndPathHelper<'h> {
    type F: FileContents;
    type OpenFileFuture: OptionallySendFuture<Output = FileAndPathHelperResult<Self::F>> + 'h;

    fn get_candidate_paths_for_binary_or_pdb(
        &self,
        debug_name: &str,
        debug_id: &DebugId
    ) -> FileAndPathHelperResult<Vec<CandidatePathInfo>>;
    fn open_file(&'h self, location: &FileLocation) -> Self::OpenFileFuture;

    fn get_candidate_paths_for_pdb(
        &self,
        _debug_name: &str,
        _debug_id: &DebugId,
        pdb_path_as_stored_in_binary: &CStr,
        _binary_file_location: &FileLocation
    ) -> FileAndPathHelperResult<Vec<FileLocation>> { ... }
}

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.

Required Associated Types

type F: FileContents

type OpenFileFuture: OptionallySendFuture<Output = FileAndPathHelperResult<Self::F>> + 'h

Required Methods

fn get_candidate_paths_for_binary_or_pdb(
    &self,
    debug_name: &str,
    debug_id: &DebugId
) -> 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(&'h self, location: &FileLocation) -> Self::OpenFileFuture

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,
    _debug_id: &DebugId,
    pdb_path_as_stored_in_binary: &CStr,
    _binary_file_location: &FileLocation
) -> FileAndPathHelperResult<Vec<FileLocation>>

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.

Implementors