nim-ownership-hooks

Files (5)

• SKILL.md
• custom_sink.md · references/
• deep_owning_container.md · references/
• move_only_owner.md · references/
• shared_refcounted.md · references/

SKILL.md (first lines)

# 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.

### 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`**
- Reset every field that `=destroy` checks, so that `=destroy` becomes a no-op on the same variable. For pointer fields, set to `nil`.
- 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.

| Model | Hooks needed |
|-------|-------------|
| Plain / auto-managed | None |
| Borrowing / view | None. Use `lent T` for accessors. |
| Move-only owner | `=destroy`, `=wasMoved`, `=copy` as `{.error.}`, `=dup` as `{.error.}` |
| Deep-owning container | `=destroy`, `=wasMoved`, `=copy`, `=dup` |
| Shared / refcounted | `=destroy`, `=wasMoved`, `=dup`, `=copy` |

### 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`

```
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)
- Self-copy (`x = x` does not crash)
- Sink from temporaries
- Zero-length initialization (if the type has constructors)

## Common Mistakes

From Vyrnexis/nim-agent-template, MIT.

More from Vyrnexis/nim-agent-template