| Title: | Portable Native and Joint Stack Traces |
| Version: | 0.1.2 |
| Date: | 2025-04-30 |
| Description: | Obtain the native stack trace and fuse it with R's stack trace for easier debugging of R packages with native code. |
| License: | GPL-3 |
| URL: | https://r-prof.github.io/winch/, https://github.com/r-prof/winch |
| BugReports: | https://github.com/r-prof/winch/issues |
| Imports: | lifecycle, procmaps (≥ 0.0.2) |
| Suggests: | DBI, knitr, magrittr, purrr, rlang (≥ 0.4.8), rmarkdown, RSQLite, testthat (≥ 3.0.0), vctrs |
| VignetteBuilder: | knitr |
| Encoding: | UTF-8 |
| Biarch: | yes |
| RoxygenNote: | 7.3.2.9000 |
| Config/testthat/edition: | 3 |
| NeedsCompilation: | yes |
| Packaged: | 2025-04-30 20:45:00 UTC; kirill |
| Author: | Kirill Müller 
[aut, cre],
R Consortium [fnd],
Ian Lance Taylor [aut] (Bundled libbacktrace library),
Free Software Foundation [cph] (Bundled libbacktrace library) |
| Maintainer: | Kirill Müller <kirill@cynkra.com> |
| Repository: | CRAN |
| Date/Publication: | 2025-05-01 13:40:03 UTC |
winch: Portable Native and Joint Stack Traces
Description
Obtain the native stack trace and fuse it with R's stack trace for easier debugging of R packages with native code.
Author(s)
Maintainer: Kirill Müller kirill@cynkra.com (ORCID)
Authors:
Ian Lance Taylor (Bundled libbacktrace library)
Other contributors:
R Consortium [funder]
Free Software Foundation (Bundled libbacktrace library) [copyright holder]
See Also
Useful links:
Report bugs at https://github.com/r-prof/winch/issues
Enrich an rlang traceback with details on native calls
Description
![[Deprecated]](./figures/lifecycle-deprecated.svg)
This function should be reimplemented in rlang, to avoid a soft dependency between rlang's traceback format and this package.
Usage
winch_add_trace_back(trace = rlang::trace_back(bottom = parent.frame()))
Arguments
trace |
An rlang traceback as returned by |
Are native tracebacks available?
Description
Returns TRUE if winch_trace_back() is supported on this platform.
Usage
winch_available()
Value
A scalar logical.
Examples
winch_available()
Call an R function from native code
Description
Primarily intended for testing.
Usage
winch_call(fun, env = parent.frame())
Arguments
fun |
A function callable without arguments. |
env |
The environment in which to evaluate the function call. |
Value
The return value of fun().
See Also
Examples
foo <- function() {
winch_call(bar)
}
bar <- function() {
writeLines("Hi!")
}
foo()
Set library to collect symbols for native stack traces
Description
On Windows, function names in native stack traces can be obtained for only one library at a time. Call this function to set the library for which to obtain symbols.
Usage
winch_init_library(path = NULL, force = FALSE)
Arguments
path |
Path to the DLL. |
force |
Reinitialize even if the path to the DLL is unchanged from the last call. |
Value
This function is called for its side effects.
See Also
Examples
winch_init_library(getLoadedDLLs()[["rlang"]][["path"]])
Raise an error from native code
Description
Primarily intended for testing.
Usage
winch_stop(message)
Arguments
message |
The error message. |
Value
This function throws an error and does not return.
See Also
Examples
try(winch_stop("Test"))
Native stack trace
Description
This function returns the native stack trace as a data frame. Each native stack frame corresponds to one row in the returned data frame. Deep function calls come first, the last row corresponds to the running process's entry point.
Usage
winch_trace_back()
Details
On Windows, call winch_init_library() to return function names
for a specific package.
Value
A data frame with the columns:
-
func: function name -
ip: instruction pointer -
pathname: path to shared library -
is_libr: a logical,TRUEif this entry is from R's shared library, determined viaprocmaps::path_is_libr()on thepathnamecomponent
See Also
sys.calls() for the R equivalent.
Examples
winch_trace_back()
foo <- function() {
winch_call(bar)
}
bar <- function() {
winch_trace_back()
}
foo()