Better document GC_generate_random_heap/valid_address API functions

Also, add an assertion to GC_print_backtrace and
GC_generate_random_backtrace that the caller should not hold the GC
lock.

* dbg_mlc.c [KEEP_BACK_PTRS] (GC_print_backtrace,
GC_generate_random_backtrace): Add assert that the GC lock is not held.
* include/gc/gc_backptr.h (GC_generate_random_heap_address): Reformat
comment.
* include/gc/gc_backptr.h (GC_generate_random_heap_address,
GC_generate_random_valid_address): Add comment that the caller should
hold the GC lock.

1 files changed, 2 insertions, 0 deletions

diff --git a/dbg_mlc.c b/dbg_mlc.c
index af34b486..bb5c5e66 100644
--- a/dbg_mlc.c
+++ b/dbg_mlc.c
@@ -208,6 +208,7 @@
     size_t offset;
     void *base;
 
+    GC_ASSERT(I_DONT_HOLD_LOCK());
     GC_print_heap_obj((ptr_t)GC_base(current));
 
     for (i = 0; ; ++i) {
@@ -250,6 +251,7 @@
     void *current;
     DCL_LOCK_STATE;
 
+    GC_ASSERT(I_DONT_HOLD_LOCK());
     if (GC_try_to_collect(GC_never_stop_func) == 0) {
       GC_err_printf("Cannot generate a backtrace: "
                     "garbage collection is disabled!\n");