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
5.1 KiB
=================================================== 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
nimprofmodule - 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.
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
nimprofmodule - 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