Hi,
I'm curious whether this <https://nim-lang.org/docs/destructors.html> manual is still relevant and if not where I can read updated documentation about the new GC free runtime if any?
Yes, it's relevant, however:
On devel destruction is now scoped based (the devel documentation reflects this). And owned is only active for --newruntime, all other GC modes ignore the owned annotation.
+1 on confusing. A single central source of knowledge explaining Nim's current and near-future semantics is sorely needed. Right now information is spread out all over the place, and is often rather vague. A best practices manual detailing how the semantics work, and how they change using different settings would be extremely useful, especially to somebody who is coming to Nim for the first time and is not well versed in how it was designed and how it has changed over the years. I'm talking specifically about anything having to do with copying and moving, deep/shallow copying, destructors, etc., and how those features interact with the GC and the ffi.
Example from shallow pragma docs:
https://nim-lang.github.io/Nim/manual.html#pragmas-shallow-pragma
"This can cause serious semantic issues and break memory safety! However, it can speed up assignments considerably, because the semantics of Nim require deep copying of sequences and strings. "
What issues can it cause, precisely? How would one use the pragma in a safe way? Where are the semantics of nim described in detail to allow one to make these kinds of judgment calls? Where are there examples of it's correct usage?
example from shallowCopy:
https://nim-lang.github.io/Nim/system.html#shallowCopy%2CT%2CT
"The shallow copy only changes the semantics for sequences and strings (and types which contain those). Be careful with the changed semantics though! There is a reason why the default assignment does a deep copy of sequences and strings."'
How would I be careful? What are the best practices? When would I not want to use this? What is the "reason" that assignment does a deep copy, and where is this reason described?
Well a certain amount of confusion is expected when you read documentation for version X while using version Y. But it's like this:
We have multiple "GCs" since a long time. Though in retrospect GC should have been called "memory management strategy". There are two new GCs in development, ARC and ORC. ARC is reference counting with move semantics and RC elisions. ORC is ARC with a cycle collector. --newruntime should be removed, it is an experiment that lead to ARC's development. All GCs except ORC are moribund, the only trouble is that ORC is still in heavy development...
Shallow copies are problematic because you cannot shallow copy a seq and then grow it later afterwards. Move sematics are a much better solution to the problem but back then they were unknown to me -- C++ still lacked them.