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

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
commit a78ee8ae84
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
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! 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 Under the `--gc:arc|orc`:option: modes Nim's `ref` type is implemented
via the same runtime "hooks" and thus via reference counting. via the same runtime "hooks" and thus via reference counting.
This means that cyclic structures cannot be freed This means that cyclic structures cannot be freed
immediately (`--gc:orc`:option: ships with a cycle collector). 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 .. 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. involved in the reference counting, it is a raw pointer without runtime checks.
Automatic reference counting also has the disadvantage that it introduces overhead 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: to avoid this overhead:
.. code-block:: nim .. code-block:: nim
@ -586,10 +586,10 @@ to avoid this overhead:
it = it.next 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 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 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 to be safe, but for `ptr` the compiler has to remain silent about possible
problems. problems.
@ -597,7 +597,7 @@ problems.
Cursor inference / copy elision 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. a form of copy elision.
To see how and when we can do that, think about this question: In `dest = src` when 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 .. code-block:: nim
proc main(tab: Table[string, string]) = 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'. # no copy into 'v', no destruction of 'v'.
use(v) use(v)
useItAgain(v) useItAgain(v)