Implementation of Trac #5364. Mostly boilerplate, reading FILE fields is missing.
- Get some feedback on missing parts. (FILE fields)
- Get some feedback on module name.
- Get some feedback on other things.
- Get code reviewed.
- Make sure test suite is passing. (I haven't run it myself)
Overall, pretty good, but please look over the concerns below.
@simonmar may also want to review, but let's go for another round first.
Please add a Note about all of this! In particular, now, any time someone updates the RTS to accept new flags, they also need to reflect those changes inside of base, so we don't forget things. I cannot think of a way to test for this easily, so we should have a big warning with a Note.
I would suggest adding the bulk of the note at the top of the file (in the format of typical GHC Notes) and then referencing it with a comment for every struct, e.g. on this line add a comment saying -- See Note [Synchronization of flags and base APIs] or something.
Pedantry: align this vertically, please.
|1 ↗||(On Diff #774)|
This module should have documentation, with a basic overview of the information you can retrieve using it.
|1 ↗||(On Diff #774)|
I don't know if we should use up this namespace entirely with this module.
We actually have some foreign imports from the RTS elsewhere. Perhaps it would be best to consolidate these under a GHC.RTS.* namespace, and then re-export them appropriately (rather than having the glue everywhere), with a top level module. For example:
- GHC.RTS -- top level re-exports lower-hierarchy modules. - GHC.RTS.Flags -- this module verbatim - GHC.RTS.Mem -- exports `performGC`; re-exported by `System.Mem` - GHC.RTS.Stats -- re-exported by `GHC.Stats`
This is just a half baked idea, but I think it would be nicer, perhaps.
|43 ↗||(On Diff #774)|
Like I said in the comment below this: use standard Haddock syntax:
-- | @'Time'@ is defined by GHC as @'StgWord64'@ in @stg/Types.h@
|46 ↗||(On Diff #774)|
Use standard Haddock code formatting with source hyperlinks, e.g.
-- | @'Nat'@ is defined by GHC in @rts/Types.h@.
This will give proper text formatting for all backends and appropriately hyperlink things.
|71 ↗||(On Diff #774)|
Docs. You don't need to describe every field if you don't want to, but that would be nice. :)
|99 ↗||(On Diff #774)|
Ditto for this, and the following Flags.
|147 ↗||(On Diff #774)|
Can we put this 0 behind a #define? Why is there no COST_CENTRES_NONE defined in Flags.h?
|3 ↗||(On Diff #1521)|
Same as austin's previous comments: docs, and I'd feel better putting this in GHC.RTS.Flags
|43 ↗||(On Diff #1521)|
Same as austin's previous comment.
|71 ↗||(On Diff #1521)|
At the very least, a link to the user manual flags documentation!
|199 ↗||(On Diff #1521)|
Why not just 'String'?
I tried to add some module-level documentation, however I think we don't have a documentation that describes all RTS flags. As far as I can see they're partially documented in https://www.haskell.org/ghc/docs/latest/html/users_guide/runtime-control.html , in +RTS --help and in includes/rts/Flags.h. Am I missing something?