433 lines
12 KiB
ReStructuredText
433 lines
12 KiB
ReStructuredText
==================================
|
|
Nim Destructors and Move Semantics
|
|
==================================
|
|
|
|
.. contents::
|
|
|
|
|
|
About this document
|
|
===================
|
|
|
|
This document describes the upcoming Nim runtime which does
|
|
not use classical GC algorithms anymore but is based on destructors and
|
|
move semantics. The new runtime's advantages are that Nim programs become
|
|
oblivious to the involved heap sizes and programs are easier to write to make
|
|
effective use of multi-core machines. As a nice bonus, files and sockets and
|
|
the like will not require manual ``close`` calls anymore.
|
|
|
|
This document aims to be a precise specification about how
|
|
move semantics and destructors work in Nim.
|
|
|
|
|
|
Motivating example
|
|
==================
|
|
|
|
With the language mechanisms described here a custom seq could be
|
|
written as:
|
|
|
|
.. code-block:: nim
|
|
|
|
type
|
|
myseq*[T] = object
|
|
len, cap: int
|
|
data: ptr UncheckedArray[T]
|
|
|
|
proc `=destroy`*[T](x: var myseq[T]) =
|
|
if x.data != nil:
|
|
for i in 0..<x.len: `=destroy`(x[i])
|
|
dealloc(x.data)
|
|
x.data = nil
|
|
|
|
proc `=`*[T](a: var myseq[T]; b: myseq[T]) =
|
|
# do nothing for self-assignments:
|
|
if a.data == b.data: return
|
|
`=destroy`(a)
|
|
a.len = b.len
|
|
a.cap = b.cap
|
|
if b.data != nil:
|
|
a.data = cast[type(a.data)](alloc(a.cap * sizeof(T)))
|
|
for i in 0..<a.len:
|
|
a.data[i] = b.data[i]
|
|
|
|
proc `=move`*[T](a, b: var myseq[T]) =
|
|
# do nothing for self-assignments:
|
|
if a.data == b.data: return
|
|
`=destroy`(a)
|
|
a.len = b.len
|
|
a.cap = b.cap
|
|
a.data = b.data
|
|
# b's elements have been stolen so ensure that the
|
|
# destructor for b does nothing:
|
|
b.data = nil
|
|
b.len = 0
|
|
|
|
proc add*[T](x: var myseq[T]; y: sink T) =
|
|
if x.len >= x.cap: resize(x)
|
|
x.data[x.len] = y
|
|
inc x.len
|
|
|
|
proc `[]`*[T](x: myseq[T]; i: Natural): lent T =
|
|
assert i < x.len
|
|
x.data[i]
|
|
|
|
proc `[]=`*[T](x: myseq[T]; i: Natural; y: sink T) =
|
|
assert i < x.len
|
|
x.data[i] = y
|
|
|
|
proc createSeq*[T](elems: varargs[T]): myseq[T] =
|
|
result.cap = elems.len
|
|
result.len = elems.len
|
|
result.data = cast[type(result.data)](alloc(result.cap * sizeof(T)))
|
|
for i in 0..<result.len: result.data[i] = elems[i]
|
|
|
|
proc len*[T](x: myseq[T]): int {.inline.} = x.len
|
|
|
|
|
|
|
|
Lifetime-tracking hooks
|
|
=======================
|
|
|
|
The memory management for Nim's standard ``string`` and ``seq`` types as
|
|
well as other standard collections is performed via so called
|
|
"Lifetime-tracking hooks" or "type-bound operators". There are 3 different
|
|
hooks for each (generic or concrete) object type ``T`` (``T`` can also be a
|
|
``distinct`` type) that are called implicitly by the compiler.
|
|
|
|
(Note: The word "hook" here does not imply any kind of dynamic binding
|
|
or runtime indirections, the implicit calls are statically bound and
|
|
potentially inlined.)
|
|
|
|
|
|
`=destroy` hook
|
|
---------------
|
|
|
|
A `=destroy` hook frees the object's associated memory and releases
|
|
other associated resources. Variables are destroyed via this hook when
|
|
they go out of scope or when the routine they were declared in is about
|
|
to return.
|
|
|
|
The prototype of this hook for a type ``T`` needs to be:
|
|
|
|
.. code-block:: nim
|
|
|
|
proc `=destroy`(x: var T)
|
|
|
|
|
|
The general pattern in ``=destroy`` looks like:
|
|
|
|
.. code-block:: nim
|
|
|
|
proc `=destroy`(x: var T) =
|
|
if x.field != nil:
|
|
dealloc(x.field)
|
|
x.field = nil
|
|
|
|
|
|
|
|
`=move` hook
|
|
------------
|
|
|
|
A `=move` hook moves an object around, the resources are stolen from the source
|
|
and passed to the destination. It must be ensured that source's destructor does
|
|
not free the resources afterwards.
|
|
|
|
The prototype of this hook for a type ``T`` needs to be:
|
|
|
|
.. code-block:: nim
|
|
|
|
proc `=move`(dest, source: var T)
|
|
|
|
|
|
The general pattern in ``=move`` looks like:
|
|
|
|
.. code-block:: nim
|
|
|
|
proc `=move`(dest, source: var T) =
|
|
# protect against self-assignments:
|
|
if dest.field != source.field:
|
|
`=destroy`(dest)
|
|
dest.field = source.field
|
|
source.field = nil
|
|
|
|
|
|
|
|
`=` (copy) hook
|
|
---------------
|
|
|
|
The ordinary assignment in Nim conceptually copies the values. The ``=`` hook
|
|
is called for assignments that couldn't be transformed into moves.
|
|
|
|
The prototype of this hook for a type ``T`` needs to be:
|
|
|
|
.. code-block:: nim
|
|
|
|
proc `=`(dest: var T; source: T)
|
|
|
|
|
|
The general pattern in ``=`` looks like:
|
|
|
|
.. code-block:: nim
|
|
|
|
proc `=`(dest: var T; source: T) =
|
|
# protect against self-assignments:
|
|
if dest.field != source.field:
|
|
`=destroy`(dest)
|
|
dest.field = copy source.field
|
|
|
|
|
|
The ``=`` proc can be marked with the ``{.error.}`` pragma. Then any assignment
|
|
that otherwise would lead to a copy is prevented at compile-time.
|
|
|
|
|
|
Move semantics
|
|
==============
|
|
|
|
A "move" can be regarded as an optimized copy operation. If the source of the
|
|
copy operation is not used afterwards, the copy can be replaced by a move. This
|
|
document uses the notation ``lastReadOf(x)`` to describe that ``x`` is not
|
|
used afterwards. This property is computed by a static control flow analysis
|
|
but can also be enforced by using ``system.move`` explicitly.
|
|
|
|
|
|
Swap
|
|
====
|
|
|
|
The need to check for self-assignments and also the need to destroy previous
|
|
objects inside ``=`` and ``=move`` is a strong indicator to treat ``system.swap``
|
|
as a builtin primitive of its own that simply swaps every field in the involved
|
|
objects via ``copyMem`` or a comparable mechanism.
|
|
In other words, ``swap(a, b)`` is **not** implemented
|
|
as ``let tmp = move(a); b = move(a); a = move(tmp)``!
|
|
|
|
This has further consequences:
|
|
|
|
* Objects that contain pointers that point to the same object are not supported
|
|
by Nim's model. Objects can be swapped and end up in an inconsistent state.
|
|
* Seqs can use ``realloc`` in the implementation.
|
|
|
|
|
|
Sink parameters
|
|
===============
|
|
|
|
To move a variable into a collection usually ``sink`` parameters are involved.
|
|
A location that is passed to a ``sink`` parameters should not be used afterwards.
|
|
This is ensured by a static analysis over a control flow graph. A sink parameter
|
|
*may* be consumed once in the proc's body but doesn't have to be consumed at all.
|
|
The reason for this is that signatures
|
|
like ``proc put(t: var Table; k: sink Key, v: sink Value)`` should be possible
|
|
without any further overloads and ``put`` might not take owership of ``k`` if
|
|
``k`` already exists in the table. Sink parameters enable an affine type system,
|
|
not a linear type system.
|
|
|
|
The employed static analysis is limited and only concerned with local variables;
|
|
however object and tuple fields are treated as separate entities:
|
|
|
|
.. code-block:: nim
|
|
|
|
proc consume(x: sink Obj) = discard "no implementation"
|
|
|
|
proc main =
|
|
let tup = (Obj(), Obj())
|
|
consume tup[0]
|
|
# ok, only tup[0] was consumed, tup[1] is still alive:
|
|
echo tup[1]
|
|
|
|
|
|
Sometimes it is required to explicitly ``move`` a value into its final position:
|
|
|
|
.. code-block:: nim
|
|
|
|
proc main =
|
|
var dest, src: array[10, string]
|
|
# ...
|
|
for i in 0..high(dest): dest[i] = move(src[i])
|
|
|
|
An implementation is allowed, but not required to implement even more move
|
|
optimizations (and the current implementation does not).
|
|
|
|
|
|
Self assignments
|
|
================
|
|
|
|
Unfortunately this document departs significantly from
|
|
the older design as specified here, https://github.com/nim-lang/Nim/wiki/Destructors.
|
|
The reason is that under the old design so called "self assignments" could not work.
|
|
|
|
|
|
.. code-block:: nim
|
|
|
|
proc select(cond: bool; a, b: sink string): string =
|
|
if cond:
|
|
result = a # moves a into result
|
|
else:
|
|
result = b # moves b into result
|
|
|
|
proc main =
|
|
var x = "abc"
|
|
var y = "xyz"
|
|
|
|
# possible self-assignment:
|
|
x = select(rand() < 0.5, x, y)
|
|
# 'select' must communicate what parameter has been
|
|
# consumed. We cannot simply generate:
|
|
# (select(...); wasMoved(x); wasMoved(y))
|
|
|
|
Consequence: ``sink`` parameters for objects that have a non-trivial destructor
|
|
must be passed as by-pointer under the hood. A further advantage is that parameters
|
|
are never destroyed, only variables are. The caller's location passed to
|
|
a ``sink`` parameter has to be destroyed by the caller and does not burden
|
|
the callee.
|
|
|
|
|
|
Const temporaries
|
|
=================
|
|
|
|
Constant literals like ``nil`` cannot be easily be ``=moved``'d. The solution
|
|
is to pass a temporary location that contains ``nil`` to the sink location.
|
|
|
|
For example:
|
|
|
|
.. code-block:: nim
|
|
|
|
var x: owned ref T = nil
|
|
# gets turned into:
|
|
var tmp = nil
|
|
move(x, tmp)
|
|
|
|
|
|
Rewrite rules
|
|
=============
|
|
|
|
**Note**: A function call ``f()`` is always the "last read" of the involved
|
|
temporary location and so covered under the more general rewrite rules.
|
|
|
|
**Note**: There are two different allowed implementation strategies:
|
|
|
|
1. The produced ``finally`` section can be a single section that is wrapped
|
|
around the complete routine body.
|
|
2. The produced ``finally`` section is wrapped around the enclosing scope.
|
|
|
|
The current implementation follows strategy (1). This means that resources are
|
|
not destroyed at the scope exit, but at the proc exit.
|
|
|
|
::
|
|
|
|
var x: T; stmts
|
|
--------------- (var)
|
|
var x: T; try stmts
|
|
finally: `=destroy`(x)
|
|
|
|
|
|
f(...)
|
|
------------------------ (function-call)
|
|
(let tmp = f(...); tmp)
|
|
finally: `=destroy`(tmp)
|
|
|
|
|
|
x = lastReadOf z
|
|
------------------ (move-optimization)
|
|
`=move`(x, z)
|
|
|
|
|
|
x = y
|
|
------------------ (copy)
|
|
`=`(x, y)
|
|
|
|
|
|
x = move y
|
|
------------------ (enforced-move)
|
|
`=move`(x, y)
|
|
|
|
|
|
f_sink(notLastReadOf y)
|
|
----------------------- (copy-to-sink)
|
|
(let tmp; `=`(tmp, y); f_sink(tmp))
|
|
finally: `=destroy`(tmp)
|
|
|
|
|
|
f_sink(move y)
|
|
----------------------- (enforced-move-to-sink)
|
|
(let tmp; `=move`(tmp, y); f_sink(tmp))
|
|
finally: `=destroy`(tmp)
|
|
|
|
|
|
Cursor variables
|
|
================
|
|
|
|
There is an additional rewrite rule for so called "cursor" variables.
|
|
A cursor variable is a variable that is only used for navigation inside
|
|
a data structure. The otherwise implied copies (or moves) and destructions
|
|
can be avoided altogether for cursor variables:
|
|
|
|
::
|
|
|
|
var x {.cursor.}: T
|
|
x = path(z)
|
|
stmts
|
|
-------------------------- (cursor-var)
|
|
x = bitwiseCopy(path z)
|
|
stmts
|
|
# x is not destroyed.
|
|
|
|
|
|
``stmts`` must not mutate ``z`` nor ``x``. All assignments to ``x`` must be
|
|
of the form ``path(z)`` but the ``z`` can differ. Neither ``z`` nor ``x``
|
|
can be aliased; this implies the addresses of these locations must not be
|
|
used explicitly.
|
|
|
|
The current implementation does not compute cursor variables but supports
|
|
the ``.cursor`` pragma annotation. Cursor variables are respected and
|
|
simply trusted: No checking is performed that no mutations or aliasing
|
|
occurs.
|
|
|
|
Cursor variables are commonly used in ``iterator`` implementations:
|
|
|
|
.. code-block:: nim
|
|
|
|
iterator nonEmptyItems(x: seq[string]): string =
|
|
for i in 0..high(x):
|
|
let it {.cursor.} = x[i] # no string copies, no destruction of 'it'
|
|
if it.len > 0:
|
|
yield it
|
|
|
|
|
|
Owned refs
|
|
==========
|
|
|
|
Let ``W`` be an ``owned ref`` type. Conceptually its hooks look like:
|
|
|
|
.. code-block:: nim
|
|
|
|
proc `=destroy`(x: var W) =
|
|
if x != nil:
|
|
assert x.refcount == 0, "dangling unowned pointers exist!"
|
|
`=destroy`(x[])
|
|
x = nil
|
|
|
|
proc `=`(x: var W; y: W) {.error: "owned refs can only be moved".}
|
|
|
|
proc `=move`(x, y: var W) =
|
|
if x != y:
|
|
`=destroy`(x)
|
|
bitwiseCopy x, y # raw pointer copy
|
|
y = nil
|
|
|
|
Let ``U`` be an unowned ``ref`` type. Conceptually its hooks look like:
|
|
|
|
.. code-block:: nim
|
|
|
|
proc `=destroy`(x: var U) =
|
|
if x != nil:
|
|
dec x.refcount
|
|
|
|
proc `=`(x: var U; y: U) =
|
|
# Note: No need to check for self-assignments here.
|
|
if y != nil: inc y.refcount
|
|
if x != nil: dec x.refcount
|
|
bitwiseCopy x, y # raw pointer copy
|
|
|
|
proc `=move`(x, y: var U) =
|
|
# Note: Moves are the same as assignments.
|
|
`=`(x, y)
|
|
|