diff --git a/doc/destructors.rst b/doc/destructors.rst index c3a7e7744f0e9..cc483026fb92c 100644 --- a/doc/destructors.rst +++ b/doc/destructors.rst @@ -89,8 +89,9 @@ 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 +"Lifetime-tracking hooks", which are particular `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 diff --git a/doc/manual.rst b/doc/manual.rst index 0093e1a3f8999..5aca1be8050d0 100644 --- a/doc/manual.rst +++ b/doc/manual.rst @@ -3678,6 +3678,48 @@ Is short for: +Routines +-------- + +A routine is a symbol of kind: `proc`, `func`, `method`, `iterator`, `macro`, `template`, `converter`. + +Type bound operators +-------------------- + +A type bound operator is a `proc` or `func` whose name starts with `=` but isn't an operator +(i.e. containing only symbols, such as `==`). These are unrelated to setters +(see `properties `_), which instead end in `=`. +A type bound operator declared for a type applies to the type regardless of whether +the operator is in scope (including if it is private). + +.. code-block:: nim + # foo.nim: + var witness* = 0 + type Foo[T] = object + proc initFoo*(T: typedesc): Foo[T] = discard + proc `=destroy`[T](x: var Foo[T]) = witness.inc # type bound operator + + # main.nim: + import foo + block: + var a = initFoo(int) + doAssert witness == 0 + doAssert witness == 1 + block: + var a = initFoo(int) + doAssert witness == 1 + `=destroy`(a) # can be called explicitly, even without being in scope + doAssert witness == 2 + # will still be called upon exiting scope + doAssert witness == 3 + +Type bound operators currently include: +``=destroy``, ``=copy``, ``=sink``, ``=trace``, ``=dispose``, ``=deepcopy`` +(some of which are still implementation defined and not yet documented). + +For more details on some of those procs, see +`lifetimeminustracking-hooks `_. + Nonoverloadable builtins ------------------------