Nim Ownership Hooks

Nim Ownership Hooks

Start by classifying the type's ownership model. Then implement exactly the hook set that model requires — no more, no less. Do not force one ownership model onto another: a shared handle should not become move-only just because it has a destructor, and a deep-owning container should not pretend copies are cheap shares.

Rules

When to write hooks

Do not write hooks unless the type owns a resource the compiler cannot release on its own.

The compiler auto-manages destruction for primitives, string, seq[T], ref T, array, tuples, closures, and objects whose fields are all auto-managed. Hooks lift through nesting: if a field's type already has custom hooks, the enclosing type gets correct compiler-generated hooks for free.

Custom hooks are needed only for non-managed resources: raw pointers (ptr T) to manually allocated memory, OS file descriptors, socket handles, distinct types whose base has no hooks, or similar. distinct types whose base already has hooks lift them automatically.

Export custom hooks for exported types.

Hook-by-hook rules

=destroy

• Check the moved-from sentinel (nil or default handle) before touching fields. Release only resources the type still owns.
• When the type owns raw storage containing elements with their own hooks, destroy each element before freeing the raw storage pointer.
• =destroy is implicitly .raises: []. Keep destructor behavior non-raising.
• Use the signature =destroy(x: T), not var T. Both compile, but T prevents accidental field mutation.

=wasMoved

• Define a valid moved-from state. Reset only the fields needed by =destroy and the operations permitted in that state.
• The compiler eliminates a =destroy call that follows =wasMoved on the same variable.

=sink

• Do not write a custom =sink by default. The compiler synthesizes one from =destroy plus a raw move, and that is usually sufficient.
• When a custom =sink is required: call =destroy(dest), then =wasMoved(dest), then transfer source fields. No self-assignment check — the compiler eliminates x = x before reaching your hook.
• Do not use copyMem or whole-object raw moves — they bypass child hook semantics.

=copy

• Deep-copy types: protect against self-assignment (if dest.data == src.data: return). Without it, x = x destroys the source before copying.
• After the guard: =destroy(dest), =wasMoved(dest), then rebuild from source. Check that source data is non-nil before allocating.
• For move-only types, use {.error.} (bare pragma, no custom message — the compiler ignores custom error strings).
• For refcounted types: =copy does destroy-then-share. No pointer self-assignment guard needed — the counter increment balances the destroy.

=dup

• Move-only types: add =dup {.error.}.
• Deep-owning raw-storage containers: mark =dup with {.nodestroy.}. The copied elements are written into raw memory that does not hold valid old values yet. {.nodestroy.} prevents implicit hook calls on those destination slots. Use child =dup for elements with hooks.
• Refcounted types: increment the counter and share the pointer. No {.nodestroy.} needed unless the hook writes into raw uninitialized storage.

=trace

• Only when all three conditions hold: the type manually owns storage, stored values can participate in ORC cycles, and ORC needs to traverse them.
• Forward-declare =destroy and =trace alongside each other to prevent the mutual-use generation conflict.

lent T

• Use lent T for immutable accessors that should borrow from a container instead of copying.

Declaration order

Declare all custom hooks before any proc, converter, iterator, closure, or generic instantiation that mentions the type. The compiler eagerly generates implicit hooks and will error if a custom hook appears afterward.

Safe order: type definition, then =destroy, =wasMoved, =copy, then =dup.

Only templates may safely appear between the type definition and the hooks. If a hook body needs a shared helper, write it as a template directly before the hooks.

importc procs are opaque and do not trigger implicit hook generation — they may appear before hooks.

Move semantics

• sink parameters are affine, not linear: the callee may consume the value once, or not at all.
• When the compiler cannot prove a sink argument is last use, it inserts =copy or =dup before passing. See nim-api-design for the caller-facing rules on when move() is required.
• move(x) leaves the source alive and moved-from; the source's =destroy still runs.
• ensureMove(x) makes the source dead: later use is a compile error, and the source's =destroy is skipped. Use it for return positions and must-fail-instead-of-copy cases, not routine sink arguments.
• =wasMoved(x) followed by =destroy(x) cancel: the destroy is eliminated.

Edge cases

• Zero-length allocations: Guard against alloc(0) in constructors and =copy. Only allocate when length is positive. alloc(0) may return nil or an invalid pointer.
• Thread-aware allocation: When a refcounted payload may cross thread boundaries, switch between allocShared/deallocShared and alloc/dealloc using when compileOption("threads").

Workflow

Step 1: Classify the ownership model

Match the type to exactly one model. Use the hook set that model requires.

Step 2: Implement the minimal hook set

Follow the hook-by-hook rules in section 2. See references/ for complete examples of each model.

Step 3: Verify with --expandArc

Copy code
nim c --expandArc:nameOfFunction yourfile.nim

Confirm the compiler inserts the hooks you expect. Check that synthesized hooks match intent.

Step 4: Run stress tests

Test these scenarios for every custom-hook type:

• Move into another variable
• Overwrite existing owned data
• Copy independence (mutating copy does not affect original)
• Dup independence
• Destroy-after-move (destroy is a no-op)
• Test every operation the type permits on a moved-from value
• Self-copy (x = x does not crash)
• Sink from temporaries
• Zero-length initialization (if the type has constructors)

Common Mistakes

References

• references/move_only_owner.md — Hooks for exclusive ownership with copying forbidden.
• references/deep_owning_container.md — Destroy, copy, and duplicate hooks for raw storage with independent copies.
• references/shared_refcounted.md — Separate-counter and generic SharedPtr patterns for shared ownership.