rts: retainer: Move heap traversal declarations to new header

1 files changed, 120 insertions, 0 deletions

diff --git a/rts/TraverseHeap.h b/rts/TraverseHeap.h
new file mode 100644
index 0000000000..5a19697694
--- /dev/null
+++ b/rts/TraverseHeap.h
@@ -0,0 +1,120 @@
+/* -----------------------------------------------------------------------------
+ *
+ * (c) The GHC Team, 2019
+ * Author: Daniel Gröber
+ *
+ * Generalised profiling heap traversal.
+ *
+ * ---------------------------------------------------------------------------*/
+
+#pragma once
+
+#if defined(PROFILING)
+
+#include <rts/Types.h>
+#include "RetainerSet.h"
+
+#include "BeginPrivate.h"
+
+void resetStaticObjectForProfiling(StgClosure *static_objects);
+
+/* See Note [Profiling heap traversal visited bit]. */
+extern StgWord flip;
+
+#define isTravDataValid(c) \
+  ((((StgWord)(c)->header.prof.hp.trav.lsb & 1) ^ flip) == 0)
+
+typedef struct traverseState_ traverseState;
+
+typedef union stackData_ {
+     /**
+      * Most recent retainer for the corresponding closure on the stack.
+      */
+    retainer c_child_r;
+} stackData;
+
+typedef struct stackElement_ stackElement;
+
+typedef struct traverseState_ {
+/*
+  Invariants:
+
+    firstStack points to the first block group.
+
+    currentStack points to the block group currently being used.
+
+    currentStack->free == stackLimit.
+
+    stackTop points to the topmost byte in the stack of currentStack.
+
+    Unless the whole stack is empty, stackTop must point to the topmost
+    object (or byte) in the whole stack. Thus, it is only when the whole stack
+    is empty that stackTop == stackLimit (not during the execution of
+    pushStackElement() and popStackElement()).
+
+    stackBottom == currentStack->start.
+
+    stackLimit == currentStack->start + BLOCK_SIZE_W * currentStack->blocks.
+
+
+  Note:
+
+    When a current stack becomes empty, stackTop is set to point to
+    the topmost element on the previous block group so as to satisfy
+    the invariants described above.
+ */
+    bdescr *firstStack;
+    bdescr *currentStack;
+    stackElement *stackBottom, *stackTop, *stackLimit;
+
+/*
+  currentStackBoundary is used to mark the current stack chunk.
+  If stackTop == currentStackBoundary, it means that the current stack chunk
+  is empty. It is the responsibility of the user to keep currentStackBoundary
+  valid all the time if it is to be employed.
+ */
+    stackElement *currentStackBoundary;
+
+/*
+  stackSize records the current size of the stack.
+  maxStackSize records its high water mark.
+  Invariants:
+    stackSize <= maxStackSize
+  Note:
+    stackSize is just an estimate measure of the depth of the graph. The reason
+    is that some heap objects have only a single child and may not result
+    in a new element being pushed onto the stack. Therefore, at the end of
+    retainer profiling, maxStackSize is some value no greater
+    than the actual depth of the graph.
+ */
+    int stackSize, maxStackSize;
+} traverseState;
+
+/**
+ * Callback called when heap traversal visits a closure.
+ *
+ * Before this callback is called the profiling header of the visited closure
+ * 'c' is zero'd with 'setTravDataToZero' if this closure hasn't been visited in
+ * this run yet. See Note [Profiling heap traversal visited bit].
+ *
+ * Return 'true' when this is not the first visit to this element. The generic
+ * traversal code will then skip traversing the children.
+ */
+typedef bool (*visitClosure_cb) (
+    const StgClosure *c,
+    const StgClosure *cp,
+    const stackData data,
+    stackData *child_data);
+
+void traverseWorkStack(traverseState *ts, visitClosure_cb visit_cb);
+void traversePushClosure(traverseState *ts, StgClosure *c, StgClosure *cp, stackData data);
+void traverseMaybeInitClosureData(StgClosure *c);
+
+void initializeTraverseStack(traverseState *ts);
+void closeTraverseStack(traverseState *ts);
+
+W_ traverseWorkStackBlocks(traverseState *ts);
+
+#include "EndPrivate.h"
+
+#endif /* PROFILING */