diff --git a/doc/gc.rst b/doc/gc.rst index 4455afcbe7..5de02f73d7 100644 --- a/doc/gc.rst +++ b/doc/gc.rst @@ -1,9 +1,10 @@ -.. default-role:: code - ======================= Nim's Memory Management ======================= +.. default-role:: code +.. include:: rstcommon.rst + :Author: Andreas Rumpf :Version: |nimversion| @@ -29,24 +30,28 @@ and how the memory management strategies other than garbage collectors work. Multi-paradigm Memory Management Strategies =========================================== +.. default-role:: option + 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 `_, 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 +--gc:none No memory management strategy nor a garbage collector. Allocated memory is simply never freed. You should use `--gc:arc` instead. @@ -62,6 +67,9 @@ Go Shared Cycle Collector Yes `--gc:go` None Manual Manual Manual `--gc:none` ================== ======== ================= ============== =================== +.. default-role:: code +.. include:: rstcommon.rst + JavaScript's garbage collector is used for the `JavaScript and NodeJS `_ compilation targets. The `NimScript `_ target uses the memory management strategy built into @@ -82,7 +90,7 @@ 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`:option: (you can put this into your config file as well). With this switch the garbage collector supports the following operations: @@ -132,7 +140,7 @@ 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. @@ -170,7 +178,7 @@ Other useful procs from `system `_ you can use to keep track of mem * `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`:option: and `--gc:go`:option:. 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`. @@ -184,7 +192,8 @@ 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`:option: 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. diff --git a/lib/packages/docutils/rst.nim b/lib/packages/docutils/rst.nim index 9cbc4efb7d..da04e9b543 100644 --- a/lib/packages/docutils/rst.nim +++ b/lib/packages/docutils/rst.nim @@ -1151,6 +1151,18 @@ proc toOtherRole(n: PRstNode, kind: RstNodeKind, roleName: string): PRstNode = proc parsePostfix(p: var RstParser, n: PRstNode): PRstNode = var newKind = n.kind var newSons = n.sons + + proc finalizeInterpreted(node: PRstNode, newKind: RstNodeKind, + newSons: seq[PRstNode], roleName: string): + PRstNode {.nimcall.} = + # fixes interpreted text (`x` or `y`:role:) to proper internal AST format + if newKind in {rnUnknownRole, rnCodeFragment}: + result = node.toOtherRole(newKind, roleName) + elif newKind == rnInlineCode: + result = node.toInlineCode(language=roleName) + else: + result = newRstNode(newKind, newSons) + if isInlineMarkupEnd(p, "_", exact=true) or isInlineMarkupEnd(p, "__", exact=true): inc p.idx @@ -1175,19 +1187,10 @@ proc parsePostfix(p: var RstParser, n: PRstNode): PRstNode = # a role: let (roleName, lastIdx) = getRefname(p, p.idx+1) newKind = whichRole(p, roleName) - if newKind in {rnUnknownRole, rnCodeFragment}: - result = n.toOtherRole(newKind, roleName) - elif newKind == rnInlineCode: - result = n.toInlineCode(language=roleName) - else: - result = newRstNode(newKind, newSons) + result = n.finalizeInterpreted(newKind, newSons, roleName) p.idx = lastIdx + 2 else: - if p.s.currRoleKind == rnInlineCode: - result = n.toInlineCode(language=p.s.currRole) - else: - newKind = p.s.currRoleKind - result = newRstNode(newKind, newSons) + result = n.finalizeInterpreted(p.s.currRoleKind, newSons, p.s.currRole) proc matchVerbatim(p: RstParser, start: int, expr: string): int = result = start diff --git a/tests/stdlib/trst.nim b/tests/stdlib/trst.nim index e6c5d97005..71f5a858be 100644 --- a/tests/stdlib/trst.nim +++ b/tests/stdlib/trst.nim @@ -371,6 +371,27 @@ suite "RST inline markup": rnLeaf '```' """) + test "interpreted text parsing: code fragments": + check(dedent""" + .. default-role:: option + + `--gc:refc`""".toAst == + dedent""" + rnInner + rnDefaultRole + rnDirArg + rnLeaf 'option' + [nil] + [nil] + rnParagraph + rnCodeFragment + rnInner + rnLeaf '--' + rnLeaf 'gc' + rnLeaf ':' + rnLeaf 'refc' + rnLeaf 'option' + """) test """interpreted text can be ended with \` """: let output = (".. default-role:: literal\n" & """`\``""").toAst