Go SDK

The Go SDK uses syscall.Mmap (via an internal mmap package) to map the compiled binary read-only into the process address space. Lookups traverse the MPHF routing table and blob entirely through pointer arithmetic; unsafe.String returns a zero-copy string aliasing the mapped region.

Installation

Requires Go 1.22+. No CGo, no libc dependency.

go get github.com/Attos-Labs/attos-go@latest

Configuration & Initialisation

OpenConfig controls a single map open. Synchronizer options are supplied as variadic Option funcs to NewSynchronizer.

import (
    "context"
    "log"
    "os"
    "time"

    attos "github.com/Attos-Labs/attos-go"
)

appLogger := log.New(os.Stderr, "[myapp] ", log.LstdFlags)

sync, err := attos.NewSynchronizer(
    context.Background(),
    "my-dataset",
    attos.WithBaseURL("https://api.attoscloud.com"),
    attos.WithAPIKey(os.Getenv("ATTOS_API_KEY")),
    attos.WithCacheDir("/var/lib/attos"),
    attos.WithSyncInterval(30 * time.Second),
    attos.WithLogger(appLogger),
)
if err != nil {
    log.Fatalf("attos init: %v", err)
}
defer sync.Close()

For local file access without the control plane, use attos.OpenWithConfig(path, cfg) directly.

cfg := attos.OpenConfig{
    ValidateChecksum: true,
    PinToMemory:      true,
}
m, err := attos.OpenWithConfig("data.attos", cfg)
if err != nil {
    500">// err is one of the typed sentinels defined in errors.go
    log.Fatal(err)
}
defer m.Close()

Core API — Lookups

Both methods perform a single xxHash64 hash, two array reads (routing table + values table), and a key-match verification. Allocation profile: 0 B/op, 0 allocs/op (verified by BenchmarkLookupLatency).

GetString

500">// Zero-copy: returned string aliases the mmap region.
500">// Valid until m.Close() or the next hot-swap.
value, err := m.GetString("user-42")
if errors.Is(err, attos.ErrKeyNotFound) {
    500">// absent key — not an error condition in most applications
}
fmt.Println(value) 500">// e.g. "mock_data_42_rev_1234567890"

Get ([]byte)

500">// Returns a slice into the mmap region — no copy.
payload, err := m.Get([]byte("user-42"))
if err == nil {
    500">// payload is valid until m.Close()
}

Scan (full iteration)

m.Scan(func(key, value []byte) bool {
    fmt.Printf("%s → %s
", key, value)
    return true 500">// return false to halt early
})

Hot-Swap Lifecycle

The Synchronizer's background goroutine calls Sync(ctx) on the configured interval. On each successful sync:

1. The new .nh binary is downloaded and written to the cache directory.
2. Open(blobPath) maps it via syscall.Mmap.
3. atomic.Pointer[Map].Swap(newMap) publishes the new pointer — readers see the new map immediately.
4. oldMap.Close() is called only after the swap — preventing any window where no map is available.

Synchronizer.Close() cancels the polling context, stops the ticker, calls wg.Wait() to drain the goroutine, and only then unmaps the final blob.

Error Handling

All methods return typed sentinel errors. Use errors.Is — never string matching.

Plan limits

When a sync hits a plan limit (for example more than 3 active nodes or 10 GB of bandwidth a month on Free), the control plane answers 402 (or 429) with a JSON body whose code says which limit. The SDK keeps serving the data it already has, pauses syncing for 5 minutes (or the Retry-After seconds, capped at 1 hour) and then retries; lookups are never affected. See Plans, limits & error codes for every code and how to fix it.

Benchmarks

Measured on linux/amd64, 11th Gen Intel Core i5-1155G7 @ 2.50 GHz.

$ cd attos-go && go test -bench=BenchmarkLookupLatency -benchmem -run=400">'^$' ./...

BenchmarkLookupLatency-8    58958785    21.29 ns/op    0 B/op    0 allocs/op