[Git][ghc/ghc][wip/jsem] jsem: apply suggestions

[sheaf (@sheaf)]

sheaf pushed to branch wip/jsem at Glasgow Haskell Compiler / GHC


Commits:
5f5791f4 by sheaf at 2023-04-20T11:27:39+00:00
jsem: apply suggestions
- - - - -


4 changed files:

- compiler/GHC/Driver/MakeSem.hs
- compiler/GHC/Driver/Session.hs
- docs/users_guide/9.8.1-notes.rst
- docs/users_guide/using.rst


Changes:

=====================================
compiler/GHC/Driver/MakeSem.hs
=====================================
@@ -493,10 +493,8 @@ runJSemAbstractSem sem action = MC.mask \ unmask -> do
       MC.throwM e1
     Right x -> cleanup $> x
 
-{-
-Note [Architecture of the Job Server]
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+{- Note [Architecture of the Job Server]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 In `-jsem` mode, the amount of parallelism that GHC can use is controlled by a
 system semaphore. We take resources from the semaphore when we need them, and
 give them back if we don't have enough to do.
@@ -538,7 +536,6 @@ We only need to kill `acquireJob`, because `releaseJob` never blocks.
 
 Note [Eventlog Messages for jsem]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 It can be tricky to verify that the work is shared adequately across different
 processes. To help debug this, we output the values of `JobResource` to the
 eventlog whenever the global state changes. There are some scripts which can be used


=====================================
compiler/GHC/Driver/Session.hs
=====================================
@@ -787,9 +787,12 @@ class ContainsDynFlags t where
 -- | The type for the -jN argument, specifying that -j on its own represents
 -- using the number of machine processors.
 data ParMakeCount
-  = ParMakeThisMany Int     -- -j <n>
-  | ParMakeSemaphore FilePath --jsem <semaphore>
-  | ParMakeNumProcessors    -- -j
+  -- | Use this many processors (@-j<n>@ flag).
+  = ParMakeThisMany Int
+  -- | Use parallelism with as many processors as possible (@-j@ flag without an argument).
+  | ParMakeNumProcessors
+  -- | Use the specific semaphore @<sem>@ to control parallelism (@-jsem <sem>@ flag).
+  | ParMakeSemaphore FilePath
 
 -----------------------------------------------------------------------------
 -- Accessors from 'DynFlags'


=====================================
docs/users_guide/9.8.1-notes.rst
=====================================
@@ -35,9 +35,10 @@ Compiler
 - Fix a bug in TH causing excessive calls to ``setNumCapabilities`` when ``-j`` is greater than ``-N``.
   See GHC ticket #23049.
 
-- GHC Proposal `#540 https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0540-jsem.rst`_ has been implemented. This adds the `-jsem`:ghc-flag: which instructs GHC to act
-  as a jobserver client when passed. This enables multiple GHC processes running
-  at once to share the system resources with each other via the system semaphore.
+- GHC Proposal `#540 https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0540-jsem.rst`_ has been implemented.
+  This adds the `-jsem`:ghc-flag: flag, which instructs GHC to act as a jobserver client.
+  This enables multiple GHC processes running at once to share the system resources with each other via the system semaphore
+  specified as an argument to that flag.
 
 
 GHCi


=====================================
docs/users_guide/using.rst
=====================================
@@ -799,12 +799,11 @@ There are two kinds of participants in the GHC Jobserver protocol:
     :category: misc
 
     Perform compilation in parallel when possible, coordinating with other
-    processes through the semaphore ⟨sem⟩.
+    processes through the semaphore ⟨sem⟩ (specified as a string).
     Error if the semaphore doesn't exist.
 
-    Use of ``-jsem`` will override use of `-j[⟨n⟩]`:ghc-flag:.
-
-
+    Use of ``-jsem`` will override use of :ghc-flag:``-j[⟨n⟩]``,
+    and vice-versa.
 
 .. _multi-home-units:
 



View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/5f5791f48087131db2740f86e824f3485a2d03dd

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/5f5791f48087131db2740f86e824f3485a2d03dd
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/20230420/6889ae94/attachment-0001.html>