This patch to libbacktrace expands the comment for
backtrace_create_state to make clear that it should be called only
once. There is no backtrace_free_state function. While it would be
nice to have such a function, it's hard to write completely accurately
as libbacktrace doesn't currently track all memory allocations.
Committed to mainline.
Ian
2018-10-05 Ian Lance Taylor <i...@golang.org>
PR libbacktrace/87529
* backtrace.h: Document that backtrace_create_state should be
called only once.
Index: backtrace.h
===================================================================
--- backtrace.h (revision 264813)
+++ backtrace.h (working copy)
@@ -92,7 +92,13 @@ typedef void (*backtrace_error_callback)
use appropriate atomic operations. If THREADED is zero the state
may only be accessed by one thread at a time. This returns a state
pointer on success, NULL on error. If an error occurs, this will
- call the ERROR_CALLBACK routine. */
+ call the ERROR_CALLBACK routine.
+
+ Calling this function allocates resources that can not be freed.
+ There is no backtrace_free_state function. The state is used to
+ cache information that is expensive to recompute. Programs are
+ expected to call this function at most once and to save the return
+ value for all later calls to backtrace functions. */
extern struct backtrace_state *backtrace_create_state (
const char *filename, int threaded,
