winch
Winch provides stack traces for call chains that cross between R and C function calls. This is a useful tool for developers of R packages where a substantial portion of the code is C or C++.
Installation
Install the released version of winch from CRAN with:
Install the development version from GitHub with:
Example
Below is an example where an R function calls into C which calls back into R. Note the second-to-last entry in the trace:
rlang::entrace()
checks if winch is installed, and adds a native backtrace. As this cannot be easily demonstrated in a knitr document, the output is copied from this GitHub Actions run.
Error: Must subset elements with a valid subscript vector.
✖ Subscript has the wrong type `function`.
ℹ It must be logical, numeric, or character.
Backtrace:
█
1. └─vctrs::vec_as_location(quote, 2)
2. └─`/vctrs.so`::vctrs_as_location()
3. └─`/vctrs.so`::vec_as_location_opts()
How does it work?
winch uses a very simple heuristic. R’s traceback (and also profiling) infrastructure introduces the notion of a “context”. Every call to an R function opens a new context and closes it when execution of the function ends. Unfortunately, no new context is established for native code called with .Call()
or .External()
. Establishing contexts expends precious run time, so this may be the reason for the omission.
To work around this limitation, the source code of all R functions along the call chain is scanned for instances of .Call
and .External
. The native call stack (obtained via libunwind or libbacktrace) is scanned for chunks of code outside of libR.so
(R’s main library) – these are assumed to correspond to .Call()
or .External()
. The native traces are embedded as artificial calls into the R stack trace.
Limitations
- The matching will not be perfect, but it may still lead to faster discovery of the cause of an error.
- On Windows winch only works on x64, and there the traces can be obtained only for one shared library at a time. See
winch_init_library()
for details.
Code of Conduct
Please note that the winch project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.