Go Adapter

Use Zinc from Go with cgo

The Go adapter uses cgo to call the Zinc C ABI directly. It returns a []byte slice backed by the shared memory mapping.

Installation

Build the core from a source checkout, then set up the adapter:

# In your application go.mod:
# replace zinc => /path/to/zinc/adapters/go
go get zinc

SharedRegion

import "zinc"

Create

region, err := zinc.Create("my-data", 16384)

Creates a new region. Returns an error if the region already exists or if the name or size is invalid.

Open

region, err := zinc.Open("my-data")

Opens an existing region. Returns an error if the region does not exist.

Bytes

Returns a []byte slice backed directly by the shared memory mapping. No copying occurs.

data := region.Bytes()
// data is a []byte pointing into the mmap
binary.LittleEndian.PutUint32(data[0:4], 42)

Read, Write, and Seek

SharedRegion implements io.Reader, io.Writer, io.Seeker, io.ReaderAt, and io.WriterAt. Each opened handle starts at offset zero. Copies of a handle share its position.

if _, err := region.Write([]byte("ZINC")); err != nil {
    return err
}
region.Notify()
if _, err := region.Seek(0, io.SeekStart); err != nil {
    return err
}
buf := make([]byte, 4)
if _, err := io.ReadFull(region, buf); err != nil {
    return err
}

ReadAt(buf, offset) and WriteAt(data, offset) leave the position unchanged. Reads return io.EOF when fewer bytes remain than requested. Writes copy what fits and return io.ErrShortWrite at capacity. Seek accepts positions from zero through capacity and returns zinc.ErrInvalidOffset for invalid positions or origins. Failed seeks leave the position unchanged. Closed handles return io.ErrClosedPipe from these methods.

The region has a fixed size. The stream covers its full capacity, including unwritten bytes; store a payload length separately if needed. Copying methods serialize access through one handle, but other mappings and borrowed slices still need synchronization. Writes do not send notifications.

Notify

region.Notify()

Wait

ok := region.Wait(1000)

Returns true if notified and false on any wait failure, including timeout. TryWait() returns true when it consumes a pending notification.

Close

region.Close()

Close() waits for active methods, including a pending Wait, and releases the native handle once. Closing any copy invalidates all copies. A zero-value or nil *SharedRegion behaves as a closed handle.

Complete example

package main

import (
    "encoding/binary"
    "fmt"
    "math"
    "time"
    "zinc"
)

func main() {
    // Create region
    region, err := zinc.Create("sensor", 16384)
    if err != nil {
        panic(err)
    }
    defer region.Close()

    // Write a float64
    data := region.Bytes()
    binary.LittleEndian.PutUint64(data[0:8], math.Float64bits(3.14159))

    // Signal readers
    region.Notify()

    fmt.Println("wrote 3.14159, waiting...")
    time.Sleep(5 * time.Second)
}

Reader process:

package main

import (
    "encoding/binary"
    "fmt"
    "math"
    "zinc"
)

func main() {
    region, err := zinc.Open("sensor")
    if err != nil {
        panic(err)
    }
    defer region.Close()

    // Wait for data
    if region.Wait(3000) {
        data := region.Bytes()
        val := math.Float64frombits(binary.LittleEndian.Uint64(data[0:8]))
        fmt.Printf("read: %f\n", val)
    }
}

Cgo flags

The adapter uses #cgo LDFLAGS: -lzinc_core -L${SRCDIR}/../../target/release to locate the library during development. For production builds, ensure the library is on the system library path or pass -L and -l flags through CGO_LDFLAGS.

Safety

The Bytes() call returns a Go slice pointing to C memory. Go’s garbage collector does not manage this memory. The slice is valid as long as the SharedRegion handle is not closed. Calling Close() and then using the returned slice results in undefined behavior.

Copy benchmark

go test -run '^$' -bench BenchmarkCopyAt -benchmem

This measures paired WriteAt/ReadAt copies through one handle, at 64 bytes and one system page. The data view is cached when the handle opens, so copy operations avoid cgo calls. Results cover local copies and locking; they do not measure IPC notification latency.