Getting Started

Quickstart — Go SDK

Attos compiles arbitrary key-value sets into a minimal perfect hash function (MPHF) binary (.attos / .nh), memory-maps it into your process, and streams updates automatically. Lookups are pointer arithmetic — P50 29 ns, zero heap allocations.

1. Install the SDK

Requires Go 1.22 or newer. No CGo dependencies.

bash

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

2. Initialize NewSynchronizer

NewSynchronizer performs an initial synchronous sync against the control plane, memory-maps the downloaded binary, and — if WithSyncInterval is provided — starts a background goroutine that polls for updates at that interval.

main.go

package main

import (
    "context"
    "log"

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

func main() {
    sync, err := attos.NewSynchronizer(
        context.Background(),
        "edge-router",                        500">// dataset ID
        attos.WithBaseURL("https://api.attoscloud.com"),
        attos.WithAPIKey("at_live_9f3a21b47c02"),
        attos.WithCacheDir("/var/lib/attos"),  500">// persists blob between restarts
        attos.WithSyncInterval(30 * time.Second),
    )
    if err != nil {
        log.Fatalf("attos: %v", err)
    }
    defer sync.Close() 500">// drains poll goroutine, then munmaps
}

3. Perform a lookup

GetString returns a zero-copy string aliasing the mmap region. No allocation is performed on the hot path (verified: 0 B/op, 0 allocs/op).

value, err := sync.GetString("user-42")
switch {
case err == nil:
    fmt.Println("value:", value)
case errors.Is(err, attos.ErrKeyNotFound):
    500">// key absent in current dataset — normal; handle accordingly
case errors.Is(err, attos.ErrMapClosed):
    500">// sync.Close() was called; stop using this instance
default:
    log.Printf("unexpected attos error: %v", err)
}

4. Hot-swap (no restart required)

The Synchronizer's background goroutine calls Sync on the configured interval. It downloads the new binary, maps it, and atomically swaps the atomic.Pointer[Map] — readers are never blocked and the old map is unmapped only after the swap completes.

500">// Manual one-shot sync (e.g. triggered by a webhook):
if err := sync.Sync(ctx); err != nil {
    log.Printf("manual sync failed: %v", err)
}

Next: read the full Go SDK reference or explore the REST API for control-plane automation.