From 02543d5ef9bd7a910fc9fece895780583ab9635a Mon Sep 17 00:00:00 2001
From: Ben Gamari <ben@smart-cactus.org>
Date: Thu, 23 Apr 2020 23:20:48 -0400
Subject: [PATCH] users guide: Add documentation for non-moving GC events
---
docs/users_guide/eventlog-formats.rst | 79 +++++++++++++++++++++++++++
1 file changed, 79 insertions(+)
diff --git a/docs/users_guide/eventlog-formats.rst b/docs/users_guide/eventlog-formats.rst
index f50285890a6e..f21d45fb6b01 100644
--- a/docs/users_guide/eventlog-formats.rst
+++ b/docs/users_guide/eventlog-formats.rst
@@ -676,3 +676,82 @@ A variable-length packet encoding a profile sample.
TODO
+.. _nonmoving-gc-events:
+
+Non-moving GC event output
+--------------------------
+
+These events mark various stages of the
+:rts-flag:`non-moving collection <--nonmoving-gc>` lifecycle. These are enabled
+with the ``+RTS -lg`` event-set.
+
+.. event-type:: CONC_MARK_BEGIN
+
+ :tag: 200
+ :length: fixed
+
+ Marks the beginning of marking by the concurrent collector.
+
+.. event-type:: CONC_MARK_END
+
+ :tag: 201
+ :length: fixed
+
+ Marks the end of marking by the concurrent collector.
+
+.. event-type:: CONC_SYNC_BEGIN
+
+ :tag: 202
+ :length: fixed
+
+ Marks the beginning of the concurrent garbage collector's
+ post-mark synchronization phase.
+
+.. event-type:: CONC_SYNC_END
+
+ :tag: 203
+ :length: fixed
+
+ Marks the end of the concurrent garbage collector's
+ post-mark synchronization phase.
+
+.. event-type:: CONC_SWEEP_BEGIN
+
+ :tag: 204
+ :length: fixed
+
+ Marks the beginning of the concurrent garbage collector's
+ sweep phase.
+
+.. event-type:: CONC_SWEEP_END
+
+ :tag: 205
+ :length: fixed
+
+ Marks the end of the concurrent garbage collector's
+ sweep phase.
+
+.. event-type:: CONC_UPD_REM_SET_FLUSH
+
+ :tag: 206
+ :length: fixed
+
+ Marks a capability flushing its local update remembered set
+ accumulator.
+
+Non-moving heap census
+~~~~~~~~~~~~~~~~~~~~~~
+
+The non-moving heap census events (enabled with the ``+RTS -ln`` event-set) are
+intended to provide insight into fragmentation of the non-moving heap.
+
+.. event-type:: NONMOVING_HEAP_CENSUS
+
+ :tag: 207
+ :length: fixed
+ :field Word8: base-2 logarithm of *blk_sz*.
+ :field Word32: number of active segments.
+ :field Word32: number of filled segments.
+ :field Word32: number of live blocks.
+
+ Describes the occupancy of the *blk_sz* sub-heap.
--
GitLab