jyapayne/Nim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

RST backtick refactor (all *.rst except manual.rst and rst_examples.rst) (#17258)

Browse source 
Co-authored-by: quantimnot <quantimnot@users.noreply.github.com>
This commit is contained in:
quantimnot 2021-03-18 23:37:55 -04:00 • committed by GitHub
commit 83ae70cb54
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
30 changed files with 1402 additions and 1350 deletions
Download patch file Download diff file Expand all files Collapse all files

92
doc/gc.rst
View file

@ -1,3 +1,5 @@
.. default-role:: code
=======================
Nim's Memory Management
=======================
@ -27,37 +29,37 @@ and how the memory management strategies other than garbage collectors work.
Multi-paradigm Memory Management Strategies
===========================================
To choose the memory management strategy use the ``--gc:`` switch.
To choose the memory management strategy use the `--gc:` switch.
- ``--gc:refc``. This is the default GC. It's a
- `--gc:refc`. This is the default GC. It's a
deferred reference counting based garbage collector
with a simple Mark&Sweep backup GC in order to collect cycles. Heaps are thread-local.
- ``--gc:markAndSweep``. Simple Mark-And-Sweep based garbage collector. Heaps are thread-local.
- ``--gc:boehm``. Boehm based garbage collector, it offers a shared heap.
- ``--gc:go``. Go's garbage collector, useful for interoperability with Go. Offers a shared heap.
- ``--gc:arc``. Plain reference counting with
- `--gc:markAndSweep`. Simple Mark-And-Sweep based garbage collector. Heaps are thread-local.
- `--gc:boehm`. Boehm based garbage collector, it offers a shared heap.
- `--gc:go`. Go's garbage collector, useful for interoperability with Go. Offers a shared heap.
- `--gc:arc`. Plain reference counting with
`move semantic optimizations <destructors.html#move-semantics>`_, offers a shared heap.
It offers deterministic performance for `hard realtime`:idx: systems. Reference cycles
cause memory leaks, beware.
- ``--gc:orc``. Same as ``--gc:arc`` but adds a cycle collector based on "trial deletion".
- `--gc:orc`. Same as `--gc:arc` but adds a cycle collector based on "trial deletion".
Unfortunately, that makes its performance profile hard to reason about so it is less
useful for hard real-time systems.
- ``--gc:none``. No memory management strategy nor a garbage collector. Allocated memory is
simply never freed. You should use ``--gc:arc`` instead.
- `--gc:none`. No memory management strategy nor a garbage collector. Allocated memory is
simply never freed. You should use `--gc:arc` instead.
================== ======== ================= ============== ===================
Memory Management Heap Reference Cycles Stop-The-World Command line switch
================== ======== ================= ============== ===================
RefC Local Cycle Collector No ``--gc:refc``
Mark & Sweep Local Cycle Collector No ``--gc:markAndSweep``
ARC Shared Leak No ``--gc:arc``
ORC Shared Cycle Collector No ``--gc:orc``
Boehm Shared Cycle Collector Yes ``--gc:boehm``
Go Shared Cycle Collector Yes ``--gc:go``
None Manual Manual Manual ``--gc:none``
RefC Local Cycle Collector No `--gc:refc`
Mark & Sweep Local Cycle Collector No `--gc:markAndSweep`
ARC Shared Leak No `--gc:arc`
ORC Shared Cycle Collector No `--gc:orc`
Boehm Shared Cycle Collector Yes `--gc:boehm`
Go Shared Cycle Collector Yes `--gc:go`
None Manual Manual Manual `--gc:none`
================== ======== ================= ============== ===================
JavaScript's garbage collector is used for the `JavaScript and NodeJS
@ -73,14 +75,14 @@ Cycle collector
---------------
The cycle collector can be en-/disabled independently from the other parts of
the garbage collector with ``GC_enableMarkAndSweep`` and ``GC_disableMarkAndSweep``.
the garbage collector with `GC_enableMarkAndSweep` and `GC_disableMarkAndSweep`.
Soft real-time support
----------------------
To enable real-time support, the symbol `useRealtimeGC`:idx: needs to be
defined via ``--define:useRealtimeGC`` (you can put this into your config
defined via `--define:useRealtimeGC` (you can put this into your config
file as well).
With this switch the garbage collector supports the following operations:
@ -88,29 +90,29 @@ With this switch the garbage collector supports the following operations:
proc GC_setMaxPause*(maxPauseInUs: int)
proc GC_step*(us: int, strongAdvice = false, stackSize = -1)
The unit of the parameters ``maxPauseInUs`` and ``us`` is microseconds.
The unit of the parameters `maxPauseInUs` and `us` is microseconds.
These two procs are the two modus operandi of the real-time garbage collector:
(1) GC_SetMaxPause Mode
You can call ``GC_SetMaxPause`` at program startup and then each triggered
garbage collector run tries to not take longer than ``maxPause`` time. However, it is
You can call `GC_SetMaxPause` at program startup and then each triggered
garbage collector run tries to not take longer than `maxPause` time. However, it is
possible (and common) that the work is nevertheless not evenly distributed
as each call to ``new`` can trigger the garbage collector and thus take ``maxPause``
as each call to `new` can trigger the garbage collector and thus take `maxPause`
time.
(2) GC_step Mode
This allows the garbage collector to perform some work for up to ``us`` time.
This allows the garbage collector to perform some work for up to `us` time.
This is useful to call in the main loop to ensure the garbage collector can do its work.
To bind all garbage collector activity to a ``GC_step`` call,
deactivate the garbage collector with ``GC_disable`` at program startup.
If ``strongAdvice`` is set to ``true``,
To bind all garbage collector activity to a `GC_step` call,
deactivate the garbage collector with `GC_disable` at program startup.
If `strongAdvice` is set to `true`,
then the garbage collector will be forced to perform the collection cycle.
Otherwise, the garbage collector may decide not to do anything,
if there is not much garbage to collect.
You may also specify the current stack size via ``stackSize`` parameter.
You may also specify the current stack size via `stackSize` parameter.
It can improve performance when you know that there are no unique Nim references
below a certain point on the stack. Make sure the size you specify is greater
than the potential worst-case size.
@ -130,16 +132,16 @@ Time measurement with garbage collectors
----------------------------------------
The garbage collectors' way of measuring time uses
(see ``lib/system/timers.nim`` for the implementation):
(see `lib/system/timers.nim` for the implementation):
1) ``QueryPerformanceCounter`` and ``QueryPerformanceFrequency`` on Windows.
2) ``mach_absolute_time`` on Mac OS X.
3) ``gettimeofday`` on Posix systems.
1) `QueryPerformanceCounter` and `QueryPerformanceFrequency` on Windows.
2) `mach_absolute_time` on Mac OS X.
3) `gettimeofday` on Posix systems.
As such it supports a resolution of nanoseconds internally; however, the API
uses microseconds for convenience.
Define the symbol ``reportMissedDeadlines`` to make the
Define the symbol `reportMissedDeadlines` to make the
garbage collector output whenever it missed a deadline.
The reporting will be enhanced and supported by the API in later versions of the collector.
@ -148,9 +150,9 @@ Tweaking the garbage collector
------------------------------
The collector checks whether there is still time left for its work after
every ``workPackage``'th iteration. This is currently set to 100 which means
every `workPackage`'th iteration. This is currently set to 100 which means
that up to 100 objects are traversed and freed before it checks again. Thus
``workPackage`` affects the timing granularity and may need to be tweaked in
`workPackage` affects the timing granularity and may need to be tweaked in
highly specialized environments or for older hardware.
@ -158,22 +160,22 @@ Keeping track of memory
=======================
If you need to pass around memory allocated by Nim to C, you can use the
procs ``GC_ref`` and ``GC_unref`` to mark objects as referenced to avoid them
procs `GC_ref` and `GC_unref` to mark objects as referenced to avoid them
being freed by the garbage collector.
Other useful procs from `system <system.html>`_ you can use to keep track of memory are:
* ``getTotalMem()`` Returns the amount of total memory managed by the garbage collector.
* ``getOccupiedMem()`` Bytes reserved by the garbage collector and used by objects.
* ``getFreeMem()`` Bytes reserved by the garbage collector and not in use.
* ``GC_getStatistics()`` Garbage collector statistics as a human-readable string.
* `getTotalMem()` Returns the amount of total memory managed by the garbage collector.
* `getOccupiedMem()` Bytes reserved by the garbage collector and used by objects.
* `getFreeMem()` Bytes reserved by the garbage collector and not in use.
* `GC_getStatistics()` Garbage collector statistics as a human-readable string.
These numbers are usually only for the running thread, not for the whole heap,
with the exception of ``--gc:boehm`` and ``--gc:go``.
with the exception of `--gc:boehm` and `--gc:go`.
In addition to ``GC_ref`` and ``GC_unref`` you can avoid the garbage collector by manually
allocating memory with procs like ``alloc``, ``alloc0``, ``allocShared``, ``allocShared0`` or ``allocCStringArray``.
In addition to `GC_ref` and `GC_unref` you can avoid the garbage collector by manually
allocating memory with procs like `alloc`, `alloc0`, `allocShared`, `allocShared0` or `allocCStringArray`.
The garbage collector won't try to free them, you need to call their respective *dealloc* pairs
(``dealloc``, ``deallocShared``, ``deallocCStringArray``, etc)
(`dealloc`, `deallocShared`, `deallocCStringArray`, etc)
when you are done with them or they will leak.
@ -182,12 +184,12 @@ Heap dump
The heap dump feature is still in its infancy, but it already proved
useful for us, so it might be useful for you. To get a heap dump, compile
with ``-d:nimTypeNames`` and call ``dumpNumberOfInstances`` at a strategic place in your program.
with `-d:nimTypeNames` and call `dumpNumberOfInstances` at a strategic place in your program.
This produces a list of the used types in your program and for every type
the total amount of object instances for this type as well as the total
amount of bytes these instances take up.
The numbers count the number of objects in all garbage collector heaps, they refer to
all running threads, not only to the current thread. (The current thread
would be the thread that calls ``dumpNumberOfInstances``.) This might
would be the thread that calls `dumpNumberOfInstances`.) This might
change in later versions.