Abstract over the way eventlogs are flushed

Currently eventlog data is always written to a file `progname.eventlog`.
This patch introduces the `flushEventLog` field in `RtsConfig` which
allows to customize the writing of eventlog data.

One possible scenario is the ongoing live-profile-monitor effort by
@NCrashed which slurps all eventlog data through `fluchEventLog`.

`flushEventLog` takes a buffer with eventlog data and its size and
returns `false` (0) in case eventlog data could not be procesed.

Reviewers: simonmar, austin, erikd, bgamari

Reviewed By: simonmar, bgamari

Subscribers: qnikst, thomie, NCrashed

Differential Revision: https://phabricator.haskell.org/D2934

2 files changed, 43 insertions, 4 deletions

diff --git a/docs/users_guide/8.2.1-notes.rst b/docs/users_guide/8.2.1-notes.rst
index d934418588..3b04975d87 100644
--- a/docs/users_guide/8.2.1-notes.rst
+++ b/docs/users_guide/8.2.1-notes.rst
@@ -240,6 +240,10 @@ Runtime system
   threads to all cores in systems which have multiple processor groups.
   (e.g. > 64 cores, see :ghc-ticket:`11054`)
 
+- Output of :ref:`Event log <rts-eventlog>` data can now be configured.
+  Enabling external tools to collect and analyze the event log data while the
+  application is still running.
+
 Build system
 ~~~~~~~~~~~~
 
diff --git a/docs/users_guide/runtime_control.rst b/docs/users_guide/runtime_control.rst
index 4bde81a9d8..3c606c92bf 100644
--- a/docs/users_guide/runtime_control.rst
+++ b/docs/users_guide/runtime_control.rst
@@ -177,6 +177,35 @@ e.g., on stack overflow. The hooks for these are as follows:
 
     The message printed if ``malloc`` fails.
 
+Furthermore GHC lets you specify the way event log data (:rts-flag:`-l`)
+is written through a custom `EventLogWriter`:
+
+``void initEventLogWriter(void)``
+    .. index::
+       single: initEventLogWriter
+
+    Initializes your `EventLogWriter`. This is optional.
+
+``bool writeEventLog(void *eventlog, size_t eventlog_size)``
+    .. index::
+       single: writeEventLog
+
+    Hands buffered event log data to your event log writer.
+    Required for a custom `EventLogWriter`.
+
+ ``void flushEventLog(void)``
+    .. index::
+       single: flushEventLog
+
+    Flush buffers (if any) of your custom `EventLogWriter`. This is
+    optional.
+
+ ``void stopEventLogWriter(void)``
+    .. index::
+       single: stopEventLogWriter
+
+    Called when event logging is about to stop. This is optional.
+
 .. _rts-options-misc:
 
 Miscellaneous RTS options
@@ -938,7 +967,7 @@ Tracing
    single: eventlog files
 
 When the program is linked with the :ghc-flag:`-eventlog` option
-(:ref:`options-linker`), runtime events can be logged in two ways:
+(:ref:`options-linker`), runtime events can be logged in several ways:
 
 -  In binary format to a file for later analysis by a variety of tools.
    One such tool is
@@ -946,13 +975,19 @@ When the program is linked with the :ghc-flag:`-eventlog` option
    which interprets the event log to produce a visual parallel execution
    profile of the program.
 
+-  In binary format to customized event log writer. This enables live
+   analysis of the events while the program is running.
+
 -  As text to standard output, for debugging purposes.
 
 .. rts-flag:: -l <flags>
 
-    Log events in binary format to the file :file:`{program}.eventlog`.
-    Without any ⟨flags⟩ specified, this logs a default set of events,
-    suitable for use with tools like ThreadScope.
+    Log events in binary format. Without any ⟨flags⟩ specified, this
+    logs a default set of events, suitable for use with tools like ThreadScope.
+
+    Per default the events are written to :file:`{program}.eventlog` though
+    the mechanism for writing event log data can be overriden with a custom
+    `EventLogWriter`.
 
     For some special use cases you may want more control over which
     events are included. The ⟨flags⟩ is a sequence of zero or more