summaryrefslogtreecommitdiff
path: root/docs/users_guide/profiling.rst
Commit message (Collapse)AuthorAgeFilesLines
* Correct module name in `-fprof-callers` documentationMatthew Pickering2021-03-141-1/+1
|
* Add -finfo-table-map which maps info tables to source positionsMatthew Pickering2021-03-031-2/+3
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | This new flag embeds a lookup table from the address of an info table to information about that info table. The main interface for consulting the map is the `lookupIPE` C function > InfoProvEnt * lookupIPE(StgInfoTable *info) The `InfoProvEnt` has the following structure: > typedef struct InfoProv_{ > char * table_name; > char * closure_desc; > char * ty_desc; > char * label; > char * module; > char * srcloc; > } InfoProv; > > typedef struct InfoProvEnt_ { > StgInfoTable * info; > InfoProv prov; > struct InfoProvEnt_ *link; > } InfoProvEnt; The source positions are approximated in a similar way to the source positions for DWARF debugging information. They are only approximate but in our experience provide a good enough hint about where the problem might be. It is therefore recommended to use this flag in conjunction with `-g<n>` for more accurate locations. The lookup table is also emitted into the eventlog when it is available as it is intended to be used with the `-hi` profiling mode. Using this flag will significantly increase the size of the resulting object file but only by a factor of 2-3x in our experience.
* Profiling by info table mode (-hi)Matthew Pickering2021-03-031-0/+5
| | | | | | | | This profiling mode creates bands by the address of the info table for each closure. This provides a much more fine-grained profiling output than any of the other profiling modes. The `-hi` profiling mode does not require a profiling build.
* Profiling: Allow heap profiling to be controlled dynamically.Matthew Pickering2021-03-031-1/+9
| | | | | | | | | | This patch exposes three new functions in `GHC.Profiling` which allow heap profiling to be enabled and disabled dynamically. 1. startHeapProfTimer - Starts heap profiling with the given RTS options 2. stopHeapProfTimer - Stops heap profiling 3. requestHeapCensus - Perform a heap census on the next context switch, regardless of whether the timer is enabled or not.
* Remove the -xt heap profiling optionMatthew Pickering2021-02-271-17/+0
| | | | | | | It should be left to tooling to perform the filtering to remove these specific closure types from the profile if desired. Fixes #16795
* Documentation fixesKrzysztof Gogolewski2021-01-301-1/+1
| | | | | | | | | | | | | | | - Add missing :since: for NondecreasingIndentation and OverlappingInstances - Remove duplicated descriptions for Safe Haskell flags and UndecidableInstances. Instead, the sections contain a link. - compare-flags: Also check for options supported by ghci. This uncovered two more that are not documented. The flag -smp was removed. - Formatting fixes - Remove the warning about -XNoImplicitPrelude - it was written in 1996, the extension is no longer dangerous. - Fix misspelled :reverse: flags Fixes #18958.
* Deprecate -h flagMatthew Pickering2021-01-271-2/+3
| | | | | | | | | | It is confusing that it defaults to two different things depending on whether we are in the profiling way or not. Use -hc if you have a profiling build Use -hT if you have a normal build Fixes #19031
* rts: Post ticky entry counts to the eventlogBen Gamari2020-11-211-2/+18
| | | | | | | | We currently only post the entry counters, not the other global counters as in my experience the former are more useful. We use the heap profiler's census period to decide when to dump. Also spruces up the documentation surrounding ticky-ticky a bit.
* Introduce -fprof-callers flagBen Gamari2020-11-211-0/+32
| | | | | | | | This introducing a new compiler flag to provide a convenient way to introduce profiler cost-centers on all occurrences of the named identifier. Closes #18566.
* users-guide: A bit of clean-up in profiling flag documentationBen Gamari2020-11-211-43/+31
|
* Document profiling flags, warning flags, and no-pieRachel2020-10-071-0/+37
|
* Fix typos and formatting in user guideJan Hrček2020-06-161-1/+1
|
* Document restriction on SCC pragma syntaxKrzysztof Gogolewski2020-03-151-1/+1
| | | | | | | Currently, the names of cost centres must be quoted or be lowercase identifiers. Fixes #17916.
* Fix typos, via a Levenshtein-style correctorBrian Wignall2020-01-041-1/+1
|
* Meaning-preserving SCC annotations (#15730)Vladislav Zavialov2019-12-051-6/+18
| | | | | | | | | | | | | | | This patch implements GHC Proposal #176: https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0176-scc-parsing.rst Before the change: 1 / 2 / 2 = 0.25 1 / {-# SCC "name" #-} 2 / 2 = 1.0 After the change: 1 / 2 / 2 = 0.25 1 / {-# SCC "name" #-} 2 / 2 = parse error
* users-guide: Fix various warningsBen Gamari2019-10-081-1/+1
|
* docs: fixs -prof links in rts-flags sectionAdam Sandberg Eriksson2019-08-021-7/+6
|
* users-guide: Update Wiki URLs to point to GitLabTakenobu Tani2019-03-191-1/+1
| | | | | | | | | | The user's guide uses the `ghc-wiki` macro, and substitution rules are complicated. So I manually edited `.rst` files without sed. I changed `Commentary/Latedmd` only to a different page. It is more appropriate as an example. [ci skip]
* doc: behaviour of +RTS -h depends on profilingBen Price2019-01-161-0/+5
| | | | | | The rts option `-h` behaves as `-hT` when compiled without profiling, and `-hc` when compiled with profiling. Add a note to the user's guide highlighting this inconsistency.
* rts: Add heap breakdown type for -hTBen Gamari2017-09-051-0/+4
| | | | | | | | | | | | Test Plan: Build, program with `-eventlog`, try running with `+RTS -h` Reviewers: austin, erikd, simonmar Subscribers: rwbarton, thomie GHC Trac Issues: #14096 Differential Revision: https://phabricator.haskell.org/D3922
* eventlog: Clean up profiling heap breakdown typeBen Gamari2017-09-051-14/+15
| | | | | | | | | | Reviewers: austin, erikd, simonmar Subscribers: rwbarton, thomie GHC Trac Issues: #14096 Differential Revision: https://phabricator.haskell.org/D3923
* users_guide: Convert mkUserGuidePart generation to a Sphinx extensionPatrick Dougherty2017-08-181-1/+43
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | This removes all dependencies the users guide had on `mkUserGuidePart`. The generation of the flag reference table and the various pieces of the man page is now entirely contained within the Spinx extension `flags.py`. You can see the man page generation on the orphan page https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/ghc.html The extension works by collecting all of the meta-data attached to the `ghc-flag` directives and then formatting and displaying it at `flag-print` directives. There is a single printing directive that can be customized with two options, what format to display (table, list, or block of flags) and an optional category to limit the output to (verbosity, warnings, codegen, etc.). New display formats can be added by creating a function `generate_flag_xxx` (where `xxx` is a description of the format) which takes a list of flags and a category and returns a new `xxx`. Then just add a reference in the dispatch table `handlers`. That display can now be run by passing `:type: xxx` to the `flag-print` directive. `flags.py` contains two maps of settings that can be adjusted. The first is a canonical list of flag categories, and the second sets default categories for files. The only functionality that Sphinx could not replace was the `what_glasgow_exts_does.gen.rst` file. `mkUserGuidePart` actually just reads the list of flags from `compiler/main/DynFlags.hs` which Sphinx cannot do. As the flag is deprecated, I added the list as a static file which can be updated manually. Additionally, this patch updates every single documented flag with the data from `mkUserGuidePart` to generate the reference table. Fixes #11654 and, incidentally, #12155. Reviewers: austin, bgamari Subscribers: rwbarton, thomie GHC Trac Issues: #11654, #12155 Differential Revision: https://phabricator.haskell.org/D3839
* users-guide: Make it easier to reference haddocksBen Gamari2017-07-241-3/+3
| | | | | | | | | | | | | | Previously you had to painstakingly construct the URI to the haddock documentation. Now the Python bits have enough smarts to construct this themselves. Reviewers: austin, patrickdoc Reviewed By: patrickdoc Subscribers: rwbarton, thomie Differential Revision: https://phabricator.haskell.org/D3785
* users-guide: Eliminate some redundant index entriesBen Gamari2017-07-241-6/+0
|
* Fix more documentation wibblesBen Gamari2017-07-231-2/+9
| | | | Fixes #14020, #14016, #14015, #14019
* users-guide: Fix various wibblesBen Gamari2017-07-231-8/+11
|
* users-guide: Standardize and repair all flag referencesPatrick Dougherty2017-07-231-36/+53
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | This patch does three things: 1.) It simplifies the flag parsing code in `conf.py` to properly display flag definitions created by `.. (ghc|rts)-flag::`. Additionally, all flag references must include the associated arguments. Documentation has been added to `editing-guide.rst` to explain this. 2.) It normalizes all flag definitions to a similar format. Notably, all instances of `<>` have been replaced with `⟨⟩`. All references across the users guide have been updated to match. 3.) It fixes a couple issues with the flag reference table's generation code, which did not handle comma separated flags in the same cell and did not properly reference flags with arguments. Test Plan: `SPHINXOPTS = -n` to activate "nitpicky" mode, which reports all broken references. All remaining errors are references to flags without any documentation. Reviewers: austin, bgamari Reviewed By: bgamari Subscribers: rwbarton, thomie GHC Trac Issues: #13980 Differential Revision: https://phabricator.haskell.org/D3778
* [Docs] Prefer cost centreBartosz Nitka2017-05-081-3/+3
| | | | | | | | | | | | | | | | | | There may be some subtlety I'm not seeing with the usage of center vs centre. Otherwise this makes it more consistent in the docs. There's one instance in 8.0.2-notes.rst, but I'm not sure if we want to modify it retroactively. Test Plan: harbormaster? Reviewers: bgamari, austin Reviewed By: bgamari Subscribers: rwbarton, thomie, simonmar Differential Revision: https://phabricator.haskell.org/D3548
* Document hithertoo undocumented HPCTIXFILE option.Edward Z. Yang2017-03-241-3/+6
| | | | | | | | | | | | Test Plan: none Reviewers: bgamari, austin, dfeuer Reviewed By: bgamari, dfeuer Subscribers: dfeuer, rwbarton, thomie Differential Revision: https://phabricator.haskell.org/D3357
* rts: Allow profile output path to be specified on RTS command lineBen Gamari2017-02-281-1/+12
| | | | | | | | | | | | | | | | | | | | | | This introduces a RTS option, -po, which allows the user to override the stem used to form the output file names of the heap profile and cost center summary. It's a bit unclear to me whether this is really the interface we want. Alternatively we could just allow the user to specify the `.hp` and `.prof` file names separately. This would arguably be a bit more straightforward and would allow the user to name JSON output with an appropriate `.json` suffix if they so desired. However, this would come at the cost of taking more of the option space, which is a somewhat precious commodity. Test Plan: Validate, try using `-po` RTS option Reviewers: simonmar, austin, erikd Reviewed By: simonmar Subscribers: thomie Differential Revision: https://phabricator.haskell.org/D3182
* users-guide: Add documentation for JSON profile formatBen Gamari2017-02-261-2/+151
| | | | | | | | Reviewers: austin Subscribers: thomie Differential Revision: https://phabricator.haskell.org/D3184
* JSON profiler reportsBen Gamari2017-02-231-0/+5
| | | | | | | | | | | | | | | | | | | This introduces a JSON output format for cost-centre profiler reports. It's not clear whether this is really something we want to introduce given that we may also move to a more Haskell-driven output pipeline in the future, but I nevertheless found this helpful, so I thought I would put it up. Test Plan: Compile a program with `-prof -fprof-auto`; run with `+RTS -pj` Reviewers: austin, erikd, simonmar Reviewed By: simonmar Subscribers: duncan, maoe, thomie, simonmar Differential Revision: https://phabricator.haskell.org/D3132
* Bump the default allocation area size to 1MBSimon Marlow2016-08-311-1/+1
| | | | | | | | | | | | | | | | | | This is long overdue. Perhaps 1MB is a little on the skinny size, but this is based on * A lot of commodity dual-core desktop processors have 3MB L3 cache * We're traditionally quite frugal with memory by default Test Plan: validate Reviewers: erikd, bgamari, hvr, austin, rwbarton, ezyang Reviewed By: ezyang Subscribers: thomie Differential Revision: https://phabricator.haskell.org/D2496
* Support SCC pragmas in declaration contextÖmer Sinan Ağacan2016-07-201-2/+19
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Not having SCCs at the top level is becoming annoying real quick. For simplest cases, it's possible to do this transformation: f x y = ... => f = {-# SCC f #-} \x y -> ... However, it doesn't work when there's a `where` clause: f x y = <t is in scope> where t = ... => f = {-# SCC f #-} \x y -> <t is out of scope> where t = ... Or when we have a "equation style" definition: f (C1 ...) = ... f (C2 ...) = ... f (C3 ...) = ... ... (usual solution is to rename `f` to `f'` and define a new `f` with a `SCC`) This patch implements support for SCC annotations in declaration contexts. This is now a valid program: f x y = ... where g z = ... {-# SCC g #-} {-# SCC f #-} Test Plan: This passes slow validate (no new failures added). Reviewers: goldfire, mpickering, austin, bgamari, simonmar Reviewed By: bgamari, simonmar Subscribers: simonmar, thomie, mpickering Differential Revision: https://phabricator.haskell.org/D2407
* Log heap profiler samples to event logBen Gamari2016-07-161-4/+20
| | | | | | | | | | | | Test Plan: Try it Reviewers: hvr, simonmar, austin, erikd Subscribers: thomie Differential Revision: https://phabricator.haskell.org/D1722 GHC Trac Issues: #11094
* users-guide: WibblesBen Gamari2016-01-141-1/+1
|
* users_guide: Use semantic directive/role for command line optionsBen Gamari2016-01-091-210/+183
| | | | | | And GHCi commands. This makes cross-referencing much easier. Also normalize markup a bit and add some missing flags.
* Move user's guide to ReStructuredTextBen Gamari2015-10-031-0/+1390
View Lorry Controller Status