[Git][ghc/ghc][master] Add RTS flag --read-tix-file (GHC Proposal 612)
Marge Bot (@marge-bot)
gitlab at gitlab.haskell.org
Tue Jun 18 22:48:35 UTC 2024
Marge Bot pushed to branch master at Glasgow Haskell Compiler / GHC
Commits:
13fdf788 by David Binder at 2024-06-18T18:48:02-04:00
Add RTS flag --read-tix-file (GHC Proposal 612)
This commit introduces the RTS flag `--read-tix-file=<yes|no>` which
controls whether a preexisting .tix file is read in at the beginning
of a program run. The default is currently `--read-tix-file=yes` but
will change to `--read-tix-file=no` in a future release of GHC. For
this reason, whenever a .tix file is read in a warning is emitted to
stderr. This warning can be silenced by explicitly passing the
`--read-tix-file=yes` option. Details can be found in the GHC proposal
cited below.
Users can query whether this flag has been used with the help of the
module `GHC.RTS.Flags`. A new field `readTixFile` was added to the
record `HpcFlags`.
These changes have been discussed and approved in
- GHC proposal 612: https://github.com/ghc-proposals/ghc-proposals/pull/612
- CLC proposal 276: https://github.com/haskell/core-libraries-committee/issues/276
- - - - -
12 changed files:
- docs/users_guide/9.12.1-notes.rst
- docs/users_guide/profiling.rst
- docs/users_guide/runtime_control.rst
- libraries/base/changelog.md
- libraries/ghc-internal/src/GHC/Internal/RTS/Flags.hsc
- rts/Hpc.c
- rts/RtsFlags.c
- rts/include/rts/Flags.h
- testsuite/tests/interface-stability/base-exports.stdout
- testsuite/tests/interface-stability/base-exports.stdout-javascript-unknown-ghcjs
- testsuite/tests/interface-stability/base-exports.stdout-mingw32
- testsuite/tests/interface-stability/base-exports.stdout-ws-32
Changes:
=====================================
docs/users_guide/9.12.1-notes.rst
=====================================
@@ -91,6 +91,11 @@ Runtime system
- Reduce fragmentation incurred by the nonmoving GC's segment allocator. In one application this reduced resident set size by 26%. See :ghc-ticket:`24150`.
+- The new runtime flag :rts-flag:`--read-tix-file=\<yes|no\>` allows to modify whether a preexisting .tix file is read in at the beginning of a program run.
+ The default is currently ``--read-tix-file=yes`` but will change to ``--read-tix-file=no`` in a future version of GHC.
+ For this reason, a warning is emitted if a .tix file is read in implicitly. You can silence this warning by explicitly passing ``--read-tix-file=yes``.
+ Details can be found in `GHC proposal 612 <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0612-fhpc-accumulation.md>`__.
+
``base`` library
~~~~~~~~~~~~~~~~
=====================================
docs/users_guide/profiling.rst
=====================================
@@ -1502,9 +1502,9 @@ Running the program generates a file with the ``.tix`` suffix, in this
case :file:`Recip.tix`, which contains the coverage data for this run of the
program. The program may be run multiple times (e.g. with different test
data), and the coverage data from the separate runs is accumulated in
-the ``.tix`` file. To reset the coverage data and start again, just
-remove the ``.tix`` file. You can control where the ``.tix`` file
-is generated using the environment variable :envvar:`HPCTIXFILE`.
+the ``.tix`` file. This behaviour can be controlled with the :rts-flag:`--read-tix-file=\<yes|no\>`
+You can control where the ``.tix`` file is generated using the
+environment variable :envvar:`HPCTIXFILE`.
.. envvar:: HPCTIXFILE
=====================================
docs/users_guide/runtime_control.rst
=====================================
@@ -1373,7 +1373,22 @@ and can be controlled by the following flags.
.. index::
single: RTS options, hpc
-.. rts-flag:: --write-tix-file
+.. rts-flag:: --read-tix-file=<yes|no>
+
+ :default: enabled
+ :since: 9.12
+
+ The RTS can be instructed to read a ``<program>.tix`` file during the startup
+ phase. The datastructures which accumulate the coverage information during
+ program execution are then initialized with the information from this file.
+ This option is useful for aggregating coverage information over multiple runs
+ of an executable.
+
+ The default for this flag is currently ``--read-tix-file=yes`` but will change
+ to ``-read-tix-file=no`` in a future version of GHC according to the accepted
+ `GHC proposal 612 <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0612-fhpc-accumulation.md>`__.
+
+.. rts-flag:: --write-tix-file=<yes|no>
:default: enabled
:since: 9.10
=====================================
libraries/base/changelog.md
=====================================
@@ -1,6 +1,7 @@
# Changelog for [`base` package](http://hackage.haskell.org/package/base)
## 4.21.0.0 *TBA*
+ * Add a `readTixFile` field to the `HpcFlags` record in `GHC.RTS.Flags` ([CLC proposal #276](https://github.com/haskell/core-libraries-committee/issues/276))
* Add the `MonadFix` instance for `(,) a`, similar to the one for `Writer a` ([CLC proposal #238](https://github.com/haskell/core-libraries-committee/issues/238))
* Improve `toInteger :: Word32 -> Integer` on 64-bit platforms ([CLC proposal #259](https://github.com/haskell/core-libraries-committee/issues/259))
* Make `flip` representation polymorphic ([CLC proposal #245](https://github.com/haskell/core-libraries-committee/issues/245))
=====================================
libraries/ghc-internal/src/GHC/Internal/RTS/Flags.hsc
=====================================
@@ -382,7 +382,11 @@ data ParFlags = ParFlags
--
-- @since base-4.20.0.0
data HpcFlags = HpcFlags
- { writeTixFile :: Bool
+ { readTixFile :: Bool
+ -- ^ Controls whether a @<program>.tix@ file is read at
+ -- the start of execution to initialize the RTS internal
+ -- HPC datastructures.
+ , writeTixFile :: Bool
-- ^ Controls whether the @<program>.tix@ file should be
-- written after the execution of the program.
}
@@ -498,6 +502,8 @@ getHpcFlags = do
let ptr = (#ptr RTS_FLAGS, HpcFlags) rtsFlagsPtr
HpcFlags
<$> (toBool <$>
+ (#{peek HPC_FLAGS, readTixFile} ptr :: IO CBool))
+ <*> (toBool <$>
(#{peek HPC_FLAGS, writeTixFile} ptr :: IO CBool))
getConcFlags :: IO ConcFlags
=====================================
rts/Hpc.c
=====================================
@@ -236,7 +236,14 @@ startupHpc(void)
sprintf(tixFilename, "%s.tix", prog_name);
}
- if (init_open(__rts_fopen(tixFilename,"r"))) {
+ if ((RtsFlags.HpcFlags.readTixFile == HPC_YES_IMPLICIT) && init_open(__rts_fopen(tixFilename,"r"))) {
+ fprintf(stderr,"Deprecation warning:\n"
+ "I am reading in the existing tix file, and will add hpc info from this run to the existing data in that file.\n"
+ "GHC 9.14 will cease looking for an existing tix file by default.\n"
+ "If you positively want to add hpc info to the current tix file, use the RTS option --read-tix-file=yes.\n"
+ "More information can be found in the accepted GHC proposal 612.\n");
+ readTix();
+ } else if ((RtsFlags.HpcFlags.readTixFile == HPC_YES_EXPLICIT) && init_open(__rts_fopen(tixFilename,"r"))) {
readTix();
}
}
=====================================
rts/RtsFlags.c
=====================================
@@ -297,6 +297,7 @@ void initRtsFlagsDefaults(void)
RtsFlags.TickyFlags.showTickyStats = false;
RtsFlags.TickyFlags.tickyFile = NULL;
#endif
+ RtsFlags.HpcFlags.readTixFile = HPC_YES_IMPLICIT;
RtsFlags.HpcFlags.writeTixFile = true;
}
@@ -565,6 +566,10 @@ usage_text[] = {
" HeapOverflow exception before the exception is thrown again, if",
" the program is still exceeding the heap limit.",
"",
+" --read-tix-file=<yes|no>",
+" Whether to initialize HPC datastructures from <program>.tix "
+" at the start of execution. (default: yes)",
+"",
" --write-tix-file=<yes|no>",
" Whether to write <program>.tix at the end of execution.",
" (default: yes)",
@@ -1068,6 +1073,16 @@ error = true;
RtsFlags.GcFlags.nonmovingDenseAllocatorCount = threshold;
}
}
+ else if (strequal("read-tix-file=yes",
+ &rts_argv[arg][2])) {
+ OPTION_UNSAFE;
+ RtsFlags.HpcFlags.readTixFile = HPC_YES_EXPLICIT;
+ }
+ else if (strequal("read-tix-file=no",
+ &rts_argv[arg][2])) {
+ OPTION_UNSAFE;
+ RtsFlags.HpcFlags.readTixFile = HPC_NO_EXPLICIT;
+ }
else if (strequal("write-tix-file=yes",
&rts_argv[arg][2])) {
OPTION_UNSAFE;
=====================================
rts/include/rts/Flags.h
=====================================
@@ -302,10 +302,26 @@ typedef struct _PAR_FLAGS {
bool setAffinity; /* force thread affinity with CPUs */
} PAR_FLAGS;
+/* Corresponds to the RTS flag `--read-tix-file=<yes|no>`.
+ * The accepted GHC proposal 612 introduced a one-release warning period
+ * during which we emit a warning if we read a .tix file and the flag
+ * isn't explicitly set. In order to distinguish between whether the flag
+ * was explicitly set or defaulted we need to use a tri-state variable.
+ */
+typedef enum _HPC_READ_FILE {
+ HPC_NO_EXPLICIT = 0, /* The user has specified --read-tix-file=no */
+ HPC_YES_IMPLICIT = 1, /* The user hasn't specified an option and we emit
+ * a warning when we read a tix file.
+ */
+ HPC_YES_EXPLICIT = 2 /* The user has specified --read-tix-file=yes */
+ } HPC_READ_FILE;
+
/* See Note [Synchronization of flags and base APIs] */
typedef struct _HPC_FLAGS {
bool writeTixFile; /* Whether the RTS should write a tix
file at the end of execution */
+ HPC_READ_FILE readTixFile; /* Whether the RTS should read a tix
+ file at the beginning of execution */
} HPC_FLAGS;
/* See Note [Synchronization of flags and base APIs] */
=====================================
testsuite/tests/interface-stability/base-exports.stdout
=====================================
@@ -9105,7 +9105,7 @@ module GHC.RTS.Flags where
type GiveGCStats :: *
data GiveGCStats = NoGCStats | CollectGCStats | OneLineGCStats | SummaryGCStats | VerboseGCStats
type HpcFlags :: *
- data HpcFlags = HpcFlags {writeTixFile :: GHC.Types.Bool}
+ data HpcFlags = HpcFlags {readTixFile :: GHC.Types.Bool, writeTixFile :: GHC.Types.Bool}
type IoManagerFlag :: *
data IoManagerFlag = IoManagerFlagAuto | IoManagerFlagSelect | IoManagerFlagMIO | IoManagerFlagWinIO | IoManagerFlagWin32Legacy
type IoSubSystem :: *
=====================================
testsuite/tests/interface-stability/base-exports.stdout-javascript-unknown-ghcjs
=====================================
@@ -12147,7 +12147,7 @@ module GHC.RTS.Flags where
type GiveGCStats :: *
data GiveGCStats = NoGCStats | CollectGCStats | OneLineGCStats | SummaryGCStats | VerboseGCStats
type HpcFlags :: *
- data HpcFlags = HpcFlags {writeTixFile :: GHC.Types.Bool}
+ data HpcFlags = HpcFlags {readTixFile :: GHC.Types.Bool, writeTixFile :: GHC.Types.Bool}
type IoManagerFlag :: *
data IoManagerFlag = IoManagerFlagAuto | IoManagerFlagSelect | IoManagerFlagMIO | IoManagerFlagWinIO | IoManagerFlagWin32Legacy
type IoSubSystem :: *
=====================================
testsuite/tests/interface-stability/base-exports.stdout-mingw32
=====================================
@@ -9329,7 +9329,7 @@ module GHC.RTS.Flags where
type GiveGCStats :: *
data GiveGCStats = NoGCStats | CollectGCStats | OneLineGCStats | SummaryGCStats | VerboseGCStats
type HpcFlags :: *
- data HpcFlags = HpcFlags {writeTixFile :: GHC.Types.Bool}
+ data HpcFlags = HpcFlags {readTixFile :: GHC.Types.Bool, writeTixFile :: GHC.Types.Bool}
type IoManagerFlag :: *
data IoManagerFlag = IoManagerFlagAuto | IoManagerFlagSelect | IoManagerFlagMIO | IoManagerFlagWinIO | IoManagerFlagWin32Legacy
type IoSubSystem :: *
=====================================
testsuite/tests/interface-stability/base-exports.stdout-ws-32
=====================================
@@ -9105,7 +9105,7 @@ module GHC.RTS.Flags where
type GiveGCStats :: *
data GiveGCStats = NoGCStats | CollectGCStats | OneLineGCStats | SummaryGCStats | VerboseGCStats
type HpcFlags :: *
- data HpcFlags = HpcFlags {writeTixFile :: GHC.Types.Bool}
+ data HpcFlags = HpcFlags {readTixFile :: GHC.Types.Bool, writeTixFile :: GHC.Types.Bool}
type IoManagerFlag :: *
data IoManagerFlag = IoManagerFlagAuto | IoManagerFlagSelect | IoManagerFlagMIO | IoManagerFlagWinIO | IoManagerFlagWin32Legacy
type IoSubSystem :: *
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/13fdf78861b18678087b70abc4c435facbc28e35
--
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/13fdf78861b18678087b70abc4c435facbc28e35
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/20240618/b2f12adb/attachment-0001.html>
More information about the ghc-commits
mailing list