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

ORC: support for custom =trace procs (#18459)

Browse source 
* ORC: support custom =trace procs (WIP)
* Update tests/arc/tcustomtrace.nim

Co-authored-by: Clyybber <darkmine956@gmail.com>

* =trace is now documented and seems to work
* make test green

Co-authored-by: Clyybber <darkmine956@gmail.com>
This commit is contained in:
Andreas Rumpf 2021-07-09 15:15:49 +02:00 • committed by GitHub
commit 4ec2f74246
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
13 changed files with 321 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

37
doc/destructors.rst
View file

@ -42,6 +42,12 @@ written as:
for i in 0..<x.len: `=destroy`(x.data[i])
dealloc(x.data)
proc `=trace`[T](x: var myseq[T]; env: pointer) =
# `=trace` allows the cycle collector `--gc:orc`
# to understand how to trace the object graph.
if x.data != nil:
for i in 0..<x.len: `=trace`(x.data[i], env)
proc `=copy`*[T](a: var myseq[T]; b: myseq[T]) =
# do nothing for self-assignments:
if a.data == b.data: return
@ -198,6 +204,37 @@ that otherwise would lead to a copy is prevented at compile-time. This looks lik
but a custom error message (e.g., `{.error: "custom error".}`) will not be emitted
by the compiler. Notice that there is no `=` before the `{.error.}` pragma.
`=trace` hook
---------------
A custom **container** type can support Nim's cycle collector `--gc:orc` via
the `=trace` hook. If the container does not implement `=trace`, cyclic data
structure which are constructed with the help of the container might leak
memory or resources, but memory safety is not compromised.
The prototype of this hook for a type `T` needs to be:
.. code-block:: nim
proc `=trace`(dest: var T; env: pointer)
`env` is used by ORC to keep track of its internal state, it should be passed around
to calls of the built-in `=trace` operation.
The general pattern in `=trace` looks like:
.. code-block:: nim
proc `=trace`(dest: var T; env: pointer) =
for child in childrenThatCanContainPointers(dest):
`=trace`(child, env)
**Note**: The `=trace` hooks is currently more experimental and less refined
than the other hooks.
Move semantics
==============

5
doc/manual.rst
View file

@ -3840,9 +3840,8 @@ the operator is in scope (including if it is private).
# will still be called upon exiting scope
doAssert witness == 3
Type bound operators currently include:
`=destroy`, `=copy`, `=sink`, `=trace`, `=deepcopy`
(some of which are still implementation defined and not yet documented).
Type bound operators are:
`=destroy`, `=copy`, `=sink`, `=trace`, `=deepcopy`.
For more details on some of those procs, see
`Lifetime-tracking hooks <destructors.html#lifetimeminustracking-hooks>`_.