[Git][ghc/ghc][wip/thunk-note] Apply 12 suggestion(s) to 1 file(s)

[Ben Gamari (@bgamari)]

Ben Gamari pushed to branch wip/thunk-note at Glasgow Haskell Compiler / GHC


Commits:
6567852f by sheaf at 2023-08-03T19:42:03+00:00
Apply 12 suggestion(s) to 1 file(s)
- - - - -


1 changed file:

- rts/Updates.h


Changes:

=====================================
rts/Updates.h
=====================================
@@ -75,7 +75,7 @@
  * `BLACKHOLE`, the thunk entry code will push an `stg_bh_upd_frame` to the
  * stack in this case (in contrast to the lazy strategy, as we will see later).
  *
- * After this `thnk` will look like,
+ * After this, `thnk` will look like,
  *
  *      thnk
  *     ┌───────────────────────┐
@@ -88,7 +88,7 @@
  *     │ payload[1] │ fv_1     │
  *     └────────────┴──────────┘
  *
- * Note that blackholing in this way does not guarantee mutual exclusion: Two
+ * Note that blackholing in this way does not guarantee mutual exclusion: two
  * threads may indeed race to enter `thnk`. This will result in both threads
  * performing evaluation and, in some cases, the blackhole being updated
  * multiple times.
@@ -105,16 +105,16 @@
  *
  * If the blackhole has not yet been updated then `tso_0` will:
  *
- *  1. set `thnk`'s `indirectee` field to point to the result of its
+ *  2A. set `thnk`'s `indirectee` field to point to the result of its
  *     evaluation, and
- *  2. set its info table to `BLACKHOLE_info`
+ *  2B. set its info table to `BLACKHOLE_info`
  *
- * N.B. You might notice that step (2) here appears to be redundant as we
+ * N.B. You might notice that step (2B) here appears to be redundant as we
  * already set the info table pointer to `EAGER_BLACKHOLE_info` above. However,
  * as we will see below, this may not be the case when lazy blackholing is in
  * use.
  *
- * After these updates we will have the following:
+ * After these updates, we will have the following:
  *
  *      thnk
  *     ┌───────────────────────┐
@@ -170,12 +170,12 @@
  * parallel program blackholing may induce considerable pressure on the
  * machine's memory subsystem.
  *
- * To mitigate this GHC by default uses a lazy blackholing strategy. Here we
+ * To mitigate this, GHC uses a lazy blackholing strategy by default. Here we
  * take advantage of the fact that redundant evaluation of a thunk is
- * acceptable and defer blackholing until the thread returns to the scheduler.
- * This is an optimisation as frequently we will finish evaluation *before*
+ * acceptable, and defer blackholing until the thread returns to the scheduler.
+ * This is an optimisation, because we will often finish evaluation *before*
  * yielding; in this case we avoid incurring the memory writes necessary to
- * blackhole the thunk (step (2)) and rather update the thunk straight to an
+ * blackhole the thunk (step (2)), and rather update the thunk straight to an
  * indirection.
  *
  * When entering a thunk compiled with lazy blackholing, we push an
@@ -187,8 +187,8 @@
  * the stack of the yielding thread looking for update frames; when such a
  * frame is encountered, it checks the info table of the updatee and:
  *
- *  - if it is `BLACKHOLE` then thunk has already been claimed for evaluation
- *    by another thread and the yielding thread is instead added to the
+ *  - if it is `BLACKHOLE`, then the thunk has already been claimed for evaluation
+ *    by another thread, and the yielding thread is instead added to the
  *    `BLACKHOLE`'s blocking queue (see Note [suspend duplicate work] in
  *    `ThreadPaused.c`).
  *
@@ -220,7 +220,7 @@
  * `msg_bh_0`. This message will be sent to the capability where the thread
  * owning the thunk resides (see `Messages.c:messageBlackHole`). This
  * capability will allocate a `BLOCKING_QUEUE` object `bq_0` recording the fact
- * that `tso_1` is waiting for the result of `thnk`'s evaluation and link it to
+ * that `tso_1` is waiting for the result of `thnk`'s evaluation, and link it to
  * `thnk` as follows:
  *
  *         thnk
@@ -256,7 +256,7 @@
  * TSO, which collects all blocking queue objects which are blocked on thunks
  * owned by the thread.
  *
- * In addition to this book-keeping, the `MSG_BLACKHOLE` message result in
+ * In addition to this book-keeping, the `MSG_BLACKHOLE` message results in
  * `tso_0` being promoted in its capability's run queue in the hope that
  * `tso_1` and other blocked threads may be unblocked more quickly.
  *



View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/6567852fb3e2c7b9e7138eb90a46915a213225f2

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/6567852fb3e2c7b9e7138eb90a46915a213225f2
You're receiving this email because of your account on gitlab.haskell.org.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-commits/attachments/20230803/8f0e9cc9/attachment-0001.html>