re PR libbacktrace/87529 (libbacktrace API forces users to have memory leaks)

	PR libbacktrace/87529
	* backtrace.h: Document that backtrace_create_state should be
	called only once.

From-SVN: r264871

diff --git a/libbacktrace/ChangeLog b/libbacktrace/ChangeLog
index ea43f14..75745aa 100644 (file)
--- a/libbacktrace/ChangeLog
+++ b/libbacktrace/ChangeLog
@@ -1,3 +1,9 @@
+2018-10-05  Ian Lance Taylor  <iant@golang.org>
+
+       PR libbacktrace/87529
+       * backtrace.h: Document that backtrace_create_state should be
+       called only once.
+
 2018-08-05 Iain Buclaw  <ibuclaw@gdcproject.org>
 
        * configure.ac: Move define of HAVE_ZLIB into check for -lz.

diff --git a/libbacktrace/backtrace.h b/libbacktrace/backtrace.h
index f07fa6c..83439ff 100644 (file)
--- a/libbacktrace/backtrace.h
+++ b/libbacktrace/backtrace.h
@@ -92,7 +92,13 @@ typedef void (*backtrace_error_callback) (void *data, const char *msg,
    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,