Pointer Conversion Rules

## Two words that look alike and are not `unsafe.Pointer` is a pointer as far as the runtime is concerned. It sits in the pointer maps the compiler emits for stack frames and heap objects, the collector follows it when marking, and the runtime rewrites it when it relocates the memory it points into. `uintptr` is an unsigned integer wide enough to hold an address. The runtime treats it as data. Nothing about a `uintptr` is special except its name. That single difference produces the whole rule. ## What can happen between two statements ``` u := uintptr(unsafe.Pointer(&x)) p := unsafe.Pointer(u + 8) ``` Between those two lines, two things may happen to `x`. **It may be collected.** If `u` is the only thing left holding the address, `x` is unreachable the moment the conversion happens, because the collector does not count integers as roots. A collection cycle can run between the statements and reclaim it. The address in `u` then names free memory that a later allocation will reuse. **It may move.** Goroutines start with small stacks and grow them by allocating a bigger one and copying the old frames across. Every real pointer into the old stack is found and rewritten during that copy — every `*T`, every `unsafe.Pointer`, in registers, in locals, in heap objects. A `uintptr` is skipped, because the runtime has no way to tell an address from an ordinary number. The stack can grow on any function call, including one the compiler inlines into the line between your two statements. Note that Go's heap collector is non-moving today, but stack copying alone is enough to break this code, and depending on it staying that way is not a bet worth making. ## Why one expression is different Written as a single expression: ``` p := unsafe.Pointer(uintptr(unsafe.Pointer(&x)) + 8) ``` the compiler can see the original `unsafe.Pointer` operand as part of the value being computed, and it keeps the referenced object live and anchored for the duration of that expression. There is no point at which the only surviving trace of the object is an integer stored in a variable the collector will read as data. This is not a stylistic preference in the documentation; it is the boundary of what the implementation promises. ## The rest of the rule The documented pattern has more to it than the single-expression requirement. - **Only arithmetic in between.** Addition and subtraction of an offset, and `&^` masking to round an address for alignment. A function call in the middle is not arithmetic and breaks the pattern. - **The result must stay inside the same allocated object.** Advancing through a struct or an array element by element is fine. Computing an address one past the end — the classic loop-termination trick from C — is listed as invalid, because that address is outside the object and the collector may associate it with something else entirely. - **You cannot invent an address.** Converting an arbitrary integer to `unsafe.Pointer` and dereferencing it is not one of the patterns; the number has to have come from a real pointer into a live object. There are a couple of narrow extra patterns worth recognising even if you never write them: a `uintptr(unsafe.Pointer(p))` conversion written directly in the argument list of a `syscall.Syscall` call is special-cased by the compiler so the object stays alive across the call, and the `uintptr` returned by `reflect.Value.Pointer` or `reflect.Value.UnsafeAddr` must be converted back to `Pointer` in the same expression that produced it, for exactly the same reason as above. ## Write unsafe.Add instead Modern Go gives you `unsafe.Add(ptr Pointer, len IntegerType) Pointer`, which offsets a pointer without a `uintptr` ever existing as a value you could store. It is shorter, it removes the possibility of the split-statement bug, and it makes review trivial: if a diff contains a bare `uintptr` local, that is the thing to question. ## How this fails in practice The bad version usually works. Objects are often reachable through something else, and a stack copy at exactly the wrong instruction is rare, so tests pass and the code ships. It fails later, under load, in a way that looks like memory corruption rather than a pointer bug. Building with `-race` turns on the compiler's checkptr instrumentation, which validates `unsafe.Pointer` conversions at runtime and reports arithmetic that lands outside a valid allocation; `go vet`'s `unsafeptr` check catches many of the split-statement forms statically. Run both against any package that does this arithmetic.