From b19042216f611d36cd7bfa95d30eae8823fead24 Mon Sep 17 00:00:00 2001 From: Ivan Maidanski Date: Mon, 25 Mar 2019 16:51:37 +0300 Subject: Fix incorrect markup formatting in documentation * doc/gcdescr.md (Mark phase): Terminate list at a proper sentence. * doc/leak.md: Likewise. * doc/scale.md (Performance): Fix markup table format. --- doc/gcdescr.md | 15 ++++++++------- doc/leak.md | 55 ++++++++++++++++++++++++++++++------------------------- doc/scale.md | 7 ++++--- 3 files changed, 42 insertions(+), 35 deletions(-) (limited to 'doc') diff --git a/doc/gcdescr.md b/doc/gcdescr.md index c5d07751..a08a805a 100644 --- a/doc/gcdescr.md +++ b/doc/gcdescr.md @@ -208,13 +208,14 @@ progression of mark states for a stop-the-world collection is: 3. `MS_ROOTS_PUSHED` asserting that once the mark stack is empty, all reachable objects are marked. Once in this state, we work only on emptying the mark stack. Once this is completed, the state changes to - 4. `MS_NONE` indicating that reachable objects are marked. The core mark - routine `GC_mark_from`, is called repeatedly by several of the sub-phases - when the mark stack starts to fill up. It is also called repeatedly - in `MS_ROOTS_PUSHED` state to empty the mark stack. The routine is designed - to only perform a limited amount of marking at each call, so that it can - also be used by the incremental collector. It is fairly carefully tuned, - since it usually consumes a large majority of the garbage collection time. + 4. `MS_NONE` indicating that reachable objects are marked. + +The core mark routine `GC_mark_from`, is called repeatedly by several of the +sub-phases when the mark stack starts to fill up. It is also called repeatedly +in `MS_ROOTS_PUSHED` state to empty the mark stack. The routine is designed +to only perform a limited amount of marking at each call, so that it can +also be used by the incremental collector. It is fairly carefully tuned, +since it usually consumes a large majority of the garbage collection time. The fact that it performs only a small amount of work per call also allows it to be used as the core routine of the parallel marker. In that case it is diff --git a/doc/leak.md b/doc/leak.md index 41becd39..76456aa5 100644 --- a/doc/leak.md +++ b/doc/leak.md @@ -35,13 +35,15 @@ To use the collector as a leak detector, follow the following steps: the garbage collector. 3. Arrange to call `GC_gcollect` at appropriate points to check for leaks. (For sufficiently long running programs, this will happen implicitly, but - probably not with sufficient frequency.) The second step can usually - be accomplished with the `-DREDIRECT_MALLOC=GC_malloc` option when the - collector is built, or by defining `malloc`, `calloc`, `realloc` and `free` - to call the corresponding garbage collector functions. But this, by itself, - will not yield very informative diagnostics, since the collector does not - keep track of information about how objects were allocated. The error - reports will include only object addresses. + probably not with sufficient frequency.) + +The second step can usually be accomplished with the +`-DREDIRECT_MALLOC=GC_malloc` option when the collector is built, or by +defining `malloc`, `calloc`, `realloc` and `free` to call the corresponding +garbage collector functions. But this, by itself, will not yield very +informative diagnostics, since the collector does not keep track of +information about how objects were allocated. The error reports will include +only object addresses. For more precise error reports, as much of the program as possible should use the all uppercase variants of these functions, after defining `GC_DEBUG`, and @@ -135,25 +137,28 @@ detection mode on a program a.out under Linux/X86 as follows: debug information. This will improve the quality of the leak reports. With this approach, it is no longer necessary to call `GC_` routines explicitly, though that can also improve the quality of the leak reports. - 4. Build the collector and install it in directory _foo_ as follows: - * `configure --prefix=_foo_ --enable-gc-debug --enable-redirect-malloc --disable-threads` - * `make` - * `make install` - - With a very recent collector on Linux, it may sometimes be safe to omit - the `--disable-threads`. But the combination of thread support and - `malloc` replacement is not yet rock solid. - 5. Set environment variables as follows: - * `LD_PRELOAD=`_foo_`/lib/libgc.so` - * `GC_FIND_LEAK` - - You may also want to set `GC_PRINT_STATS` (to confirm that the collector - is running) and/or `GC_LOOP_ON_ABORT` (to facilitate debugging from - another window if something goes wrong). + 4. Build the collector and install it in directory _foo_ as follows (it may + be safe to omit the `--disable-threads` option on Linux, but the combination + of thread support and `malloc` replacement is not yet rock solid): + + - `configure --prefix=_foo_ --enable-gc-debug --enable-redirect-malloc --disable-threads` + - `make` + - `make install` + + 5. Set environment variables as follows (the last two are optional, just to + confirm the collector is running, and to facilitate debugging from another + console window if something goes wrong, respectively): + + - `LD_PRELOAD=_foo_/lib/libgc.so` + - `GC_FIND_LEAK` + - `GC_PRINT_STATS` + - `GC_LOOP_ON_ABORT` + 6. Simply run `a.out` as you normally would. Note that if you run anything else (e.g. your editor) with those environment variables set, it will also be leak tested. This may or may not be useful and/or embarrassing. It can generate mountains of leak reports if the application was not designed - to avoid leaks, e.g. because it's always short-lived. This has not yet - been thoroughly tested on large applications, but it's known to do the right - thing on at least some small ones. + to avoid leaks, e.g. because it's always short-lived. + +This has not yet been thoroughly tested on large applications, but it's known +to do the right thing on at least some small ones. diff --git a/doc/scale.md b/doc/scale.md index 75fb635b..b32c1ab4 100644 --- a/doc/scale.md +++ b/doc/scale.md @@ -142,9 +142,10 @@ These measurements do not use incremental collection, nor was prefetching enabled in the marker. We used the C version of the benchmark. All measurements are in elapsed seconds on an unloaded machine. -Number of threads| 1 marker thread (secs.) | 2 marker threads (secs.) ----|---|--- -1 client| 10.45| 7.85 | 2 clients| 19.95| 12.3 +Number of client threads| 1 marker thread (secs.)| 2 marker threads (secs.) +---|------|----- + 1| 10.45| 7.85 + 2| 19.95| 12.3 The execution time for the single threaded case is slightly worse than with simple locking. However, even the single-threaded benchmark runs faster than -- cgit v1.2.1