mirrors/Nim
1
0
Fork 0
mirror of https://github.com/nim-lang/Nim.git synced 2025-12-30 09:54:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

Call {.cursor.} a pragma. (#19116)

Browse Source 
* Call {.cursor.} a pragma.

Its hard to find .curser annotation while googling because all other things like it are called pragmas. See https://nim-lang.org/docs/manual.html#pragmas
Also the . in front of the name makes it hard to find and search for.

Can we just call it cursor pragma?

* Small fix for comment.
This commit is contained in:
treeform
2021-11-09 23:52:34 -08:00
committed by GitHub
parent 15157d06c3
commit a78ee8ae84
1 changed files with 8 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
doc/destructors.rst
View File

@@ -555,14 +555,14 @@ for expressions of type `lent T` or of type `var T`.
echo t[0] # accessor does not copy the element!
The .cursor annotation
======================
The cursor pragma
=================
Under the `--gc:arc|orc`:option: modes Nim's `ref` type is implemented
via the same runtime "hooks" and thus via reference counting.
This means that cyclic structures cannot be freed
immediately (`--gc:orc`:option: ships with a cycle collector).
With the `.cursor` annotation one can break up cycles declaratively:
With the `cursor` pragma one can break up cycles declaratively:
.. code-block:: nim
@@ -575,7 +575,7 @@ But please notice that this is not C++'s weak_ptr, it means the right field is n
involved in the reference counting, it is a raw pointer without runtime checks.
Automatic reference counting also has the disadvantage that it introduces overhead
when iterating over linked structures. The `.cursor` annotation can also be used
when iterating over linked structures. The `cursor` pragma can also be used
to avoid this overhead:
.. code-block:: nim
@@ -586,10 +586,10 @@ to avoid this overhead:
it = it.next
In fact, `.cursor` more generally prevents object construction/destruction pairs
In fact, `cursor` more generally prevents object construction/destruction pairs
and so can also be useful in other contexts. The alternative solution would be to
use raw pointers (`ptr`) instead which is more cumbersome and also more dangerous
for Nim's evolution: Later on, the compiler can try to prove `.cursor` annotations
for Nim's evolution: Later on, the compiler can try to prove `cursor` pragmas
to be safe, but for `ptr` the compiler has to remain silent about possible
problems.
@@ -597,7 +597,7 @@ problems.
Cursor inference / copy elision
===============================
The current implementation also performs `.cursor` inference. Cursor inference is
The current implementation also performs `cursor` inference. Cursor inference is
a form of copy elision.
To see how and when we can do that, think about this question: In `dest = src` when
@@ -612,7 +612,7 @@ indirections:
.. code-block:: nim
proc main(tab: Table[string, string]) =
let v = tab["key"] # inferred as .cursor because 'tab' is not mutated.
let v = tab["key"] # inferred as cursor because 'tab' is not mutated.
# no copy into 'v', no destruction of 'v'.
use(v)
useItAgain(v)