mirror of
https://github.com/nim-lang/Nim.git
synced 2026-01-04 04:02:41 +00:00
417b90a7e5
- add additional parameters parsing (other implementations will just
ignore them). E.g. if in RST we have:
.. code:: nim
:test: "nim c $1"
...
then in Markdown that will be:
```nim test="nim c $1"
...
```
- implement Markdown interpretation of additional indentation which is
less than 4 spaces (>=4 spaces is a code block but it's not
implemented yet). RST interpretes it as quoted block, for Markdown it's
just normal paragraphs.
- add separate `md2html` and `md2tex` commands. This is to separate
Markdown behavior in cases when it diverges w.r.t. RST significantly —
most conspicously like in the case of additional indentation above, and
also currently the contradicting inline rule of Markdown is also turned
on only in `md2html` and `md2tex`. **Rationale:** mixing Markdown and
RST arbitrarily is a way to nowhere, we need to provide a way to fix the
particular behavior. Note that still all commands have **both** Markdown
and RST features **enabled**. In this PR `*.nim` files can be processed
only in Markdown mode, while `md2html` is for `*.md` files and
`rst2html` for `*.rst` files.
- rename `*.rst` files to `.*md` as our current default behavior is
already Markdown-ish
- convert code blocks in `docgen.rst` to Markdown style as an example.
Other code blocks will be converted in the follow-up PRs
- fix indentation inside Markdown code blocks — additional indentation
is preserved there
- allow more than 3 backticks open/close blocks (tildas \~ are still not
allowed to avoid conflict with RST adornment headings) see also
https://github.com/nim-lang/RFCs/issues/355
- better error messages
- (other) fix a bug that admonitions cannot be used in sandbox mode; fix
annoying warning on line 2711
208 lines
5.1 KiB
Markdown
208 lines
5.1 KiB
Markdown
===================================================
|
|
Embedded Stack Trace Profiler (ESTP) User Guide
|
|
===================================================
|
|
|
|
.. default-role:: code
|
|
.. include:: rstcommon.rst
|
|
|
|
:Author: Andreas Rumpf
|
|
:Version: |nimversion|
|
|
|
|
|
|
Nim comes with a platform independent profiler -
|
|
the Embedded Stack Trace Profiler (ESTP). The profiler
|
|
is *embedded* into your executable. To activate the profiler you need to do:
|
|
|
|
* compile your program with the `--profiler:on --stackTrace:on`:option: command
|
|
line options
|
|
* import the `nimprof` module
|
|
* run your program as usual.
|
|
|
|
You can in fact look at `nimprof`'s source code to see how to implement
|
|
your own profiler.
|
|
|
|
The setting `--profiler:on`:option: defines the conditional symbol `profiler`.
|
|
You can use `when compileOption("profiler")` to make the switch seamless.
|
|
If `profiler`:option: is `off`:option:, your program runs normally.
|
|
Otherwise your program is profiled.
|
|
|
|
```nim
|
|
when compileOption("profiler"):
|
|
import nimprof
|
|
```
|
|
|
|
After your program has finished the profiler will create a
|
|
file ``profile_results.txt`` containing the profiling results.
|
|
|
|
Since the profiler works by examining stack traces, it's essential that
|
|
the option `--stackTrace:on`:option: is active! Unfortunately this means that a
|
|
profiling build is much slower than a release build.
|
|
|
|
|
|
Memory profiler
|
|
===============
|
|
|
|
You can also use ESTP as a memory profiler to see which stack traces allocate
|
|
the most memory and thus create the most GC pressure. It may also help to
|
|
find memory leaks. To activate the memory profiler you need to do:
|
|
|
|
* compile your program with the
|
|
`--profiler:off --stackTrace:on -d:memProfiler`:option:
|
|
command line options. Yes it's `--profiler:off`:option:.
|
|
* import the `nimprof` module
|
|
* run your program as usual.
|
|
|
|
Define the symbol `ignoreAllocationSize` so that only the number of
|
|
allocations is counted and the sizes of the memory allocations do not matter.
|
|
|
|
|
|
Example results file
|
|
====================
|
|
|
|
The results file lists stack traces ordered by significance.
|
|
|
|
The following example file has been generated by profiling the Nim compiler
|
|
itself: It shows that in total 5.4% of the runtime has been spent
|
|
in `crcFromRope` or its children.
|
|
|
|
In general the stack traces show you immediately where the problem is because
|
|
the trace acts like an explanation; in traditional profilers you can only find
|
|
expensive leaf functions easily but the *reason* why they are invoked
|
|
often remains mysterious.
|
|
|
|
::
|
|
total executions of each stack trace:
|
|
Entry: 0/3391 Calls: 84/4160 = 2.0% [sum: 84; 84/4160 = 2.0%]
|
|
newCrcFromRopeAux
|
|
crcFromRope
|
|
writeRopeIfNotEqual
|
|
shouldRecompile
|
|
writeModule
|
|
myClose
|
|
closePasses
|
|
processModule
|
|
CompileModule
|
|
CompileProject
|
|
CommandCompileToC
|
|
MainCommand
|
|
HandleCmdLine
|
|
nim
|
|
Entry: 1/3391 Calls: 46/4160 = 1.1% [sum: 130; 130/4160 = 3.1%]
|
|
updateCrc32
|
|
newCrcFromRopeAux
|
|
crcFromRope
|
|
writeRopeIfNotEqual
|
|
shouldRecompile
|
|
writeModule
|
|
myClose
|
|
closePasses
|
|
processModule
|
|
CompileModule
|
|
CompileProject
|
|
CommandCompileToC
|
|
MainCommand
|
|
HandleCmdLine
|
|
nim
|
|
Entry: 2/3391 Calls: 41/4160 = 0.99% [sum: 171; 171/4160 = 4.1%]
|
|
updateCrc32
|
|
updateCrc32
|
|
newCrcFromRopeAux
|
|
crcFromRope
|
|
writeRopeIfNotEqual
|
|
shouldRecompile
|
|
writeModule
|
|
myClose
|
|
closePasses
|
|
processModule
|
|
CompileModule
|
|
CompileProject
|
|
CommandCompileToC
|
|
MainCommand
|
|
HandleCmdLine
|
|
nim
|
|
Entry: 3/3391 Calls: 41/4160 = 0.99% [sum: 212; 212/4160 = 5.1%]
|
|
crcFromFile
|
|
writeRopeIfNotEqual
|
|
shouldRecompile
|
|
writeModule
|
|
myClose
|
|
closePasses
|
|
processModule
|
|
CompileModule
|
|
CompileProject
|
|
CommandCompileToC
|
|
MainCommand
|
|
HandleCmdLine
|
|
nim
|
|
Entry: 4/3391 Calls: 41/4160 = 0.99% [sum: 253; 253/4160 = 6.1%]
|
|
updateCrc32
|
|
crcFromFile
|
|
writeRopeIfNotEqual
|
|
shouldRecompile
|
|
writeModule
|
|
myClose
|
|
closePasses
|
|
processModule
|
|
CompileModule
|
|
CompileProject
|
|
CommandCompileToC
|
|
MainCommand
|
|
HandleCmdLine
|
|
nim
|
|
Entry: 5/3391 Calls: 32/4160 = 0.77% [sum: 285; 285/4160 = 6.9%]
|
|
pop
|
|
newCrcFromRopeAux
|
|
crcFromRope
|
|
writeRopeIfNotEqual
|
|
shouldRecompile
|
|
writeModule
|
|
myClose
|
|
closePasses
|
|
processModule
|
|
CompileModule
|
|
CompileProject
|
|
CommandCompileToC
|
|
MainCommand
|
|
HandleCmdLine
|
|
nim
|
|
Entry: 6/3391 Calls: 17/4160 = 0.41% [sum: 302; 302/4160 = 7.3%]
|
|
doOperation
|
|
forAllChildrenAux
|
|
pop
|
|
newCrcFromRopeAux
|
|
crcFromRope
|
|
writeRopeIfNotEqual
|
|
shouldRecompile
|
|
writeModule
|
|
myClose
|
|
closePasses
|
|
processModule
|
|
CompileModule
|
|
CompileProject
|
|
CommandCompileToC
|
|
MainCommand
|
|
HandleCmdLine
|
|
...
|
|
nim
|
|
Entry: 7/3391 Calls: 14/4160 = 0.34% [sum: 316; 316/4160 = 7.6%]
|
|
Contains
|
|
isAccessible
|
|
interiorAllocatedPtr
|
|
gcMark
|
|
markStackAndRegisters
|
|
collectCTBody
|
|
collectCT
|
|
rawNewObj
|
|
newObj
|
|
newNode
|
|
copyTree
|
|
matchesAux
|
|
matches
|
|
resolveOverloads
|
|
semOverloadedCall
|
|
semOverloadedCallAnalyseEffects
|
|
...
|
|
CommandCompileToC
|
|
MainCommand
|
|
HandleCmdLine
|