# Platform Notes

> NumKong for Go

### cGo Integration Notes

This package is a cGo wrapper over the C library.
That means a few rules matter:

- Input slices must have matching lengths where the API expects paired vectors.
- Length mismatches and insufficient slice capacity panic uniformly across all functions.
- A kernel that reports a failure status, like a packed matrix of another capability, panics too.
- Empty slices return zero for scalar outputs rather than crashing.
- The slice backing arrays remain owned by Go.
- `DotsPackedMatrix` and `MaxSimPackedMatrix` structs own their packed buffers and carry dimensions and dtype metadata.
- Constructors validate that input slices are large enough for the given dimensions.
- Batch functions validate both input and output slice sizes.
- Symmetric output matrices must be n × n in size.

#### Memory Safety

Go automatically pins slice backing arrays for the duration of each cGo call.
No `runtime.Pinner` or manual pinning is needed from the caller.

`DotsPackedMatrix` and `MaxSimPackedMatrix` hold strong Go references to their `[]byte` buffers.
This keeps the packed data alive for garbage collection as long as the struct is reachable.

Memory footprint in Go is easiest to think about in two layers.
The slice header is the ordinary Go slice header.
The payload is the backing array you already own.
NumKong does not wrap those slices in extra heap-owning tensor objects in this binding.