microsoft / microsoft/STL

`<stacktrace>`: document limits

Open
#2,779 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation
Dominant language
C++
Stars
11.1k
Forks
1.7k
Avg merge
4d 15h
Merged PRs (30d)
22

Description

<stacktrace> has the following limitations:

  • The stack capturing is done using CaptureStackBackTrace function. As a result:
    • The skip parameter in basic_stacktrace::current is limited to at most 0xFFFF'FFFF (the actual limit might be lower).
    • The max_depth parameter in basic_stacktrace::current is limited to 0xFFFF - see #2776.
    • Only non-inlined function addressees are captured. Inline stack frames and parameter values are not captured. (inline and __forceinline keywords do not imply the function is inlined, and the absence of these keywords does not imply that the function is not inlined).
    • It does not work under ARM64 for x64 binaries (returns empty traces)
  • The symbols resolution is done lazily, as intended by the Standard. It means that if stack trace contains pointers to a DLL that has already been unloaded, it may not resolve correctly.
  • The symbols resolution uses DbgEng from within the current process. Consequently:
    • The symbol resolution relies on .pdbs availability. As an alternative, export names are used. If neither is present, module names and offsets are used.
    • There are likely some issues with the concurrent use of DbgHelp and potentially with the concurrent use of DbgEng library.
    • If .exe and .pdb are moved to another folder name from the one where theyy were created during build, the .pdb will not get picked by default. Use /PDBALTPATH:%_PDB% to work around this limitation.
  • There's no control over various options for DbgEng
  • There's no control on whether network / Internet symbols are used. DbgEng uses _NT_SYMBOL_PATH as usual. (Set _NT_SYMBOL_PATH via _putenv, _wputenv or SetEnvironmentVariable prior to the first use of <stacktrace> to control locations of symbols)
  • Overall, the facility has limited usage in the case of fatal errors, where the state of process is corrupted. Usually, such errors cannot be handled in a reliable and meaningful way from the current process. Use error handling that relies on external process or service instead, such as Windows Error Reporting

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the documentation and the basic_stacktrace::current entry point; the issue does not name a documentation file or test. Incorporate the listed CaptureStackBackTrace, DbgEng, symbol-resolution, and fatal-error limitations, then verify that the published documentation covers each limitation accurately.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.