Go API reference

Use Go byte slices and context cancellation over the native C ABI. Endpoints support concurrent calls and explicit cleanup.

Generated Go reference ↗ · API source ↗

Install

Requires Go 1.24 or later, cgo enabled, a C compiler, and pkg-config. Install the C SDK first and set PKG_CONFIG_PATH to its lib/pkgconfig directory. On Windows, add the SDK's lib directory to PATH and use a cgo-compatible compiler.

go get github.com/cloudtoid/interprocess/src/go/v3@latest

The module's package name is interprocess. On Unix, the pkg-config flags include the installed library's runtime search path.

Send and receive

package main

import (
    "context"
    "fmt"
    "time"

    "github.com/cloudtoid/interprocess/src/go/v3"
)

func main() {
    if err := run(); err != nil { panic(err) }
}

func run() error {
    options := interprocess.Options{Name: "example", Capacity: 65536}
    subscriber, err := interprocess.OpenSubscriber(options)
    if err != nil { return err }
    defer subscriber.Close()
    publisher, err := interprocess.OpenPublisher(options)
    if err != nil { return err }
    defer publisher.Close()

    sent, err := publisher.TrySend([]byte("hello"))
    if err != nil { return err }
    if !sent { return fmt.Errorf("queue is full or recovering") }
    ctx, cancel := context.WithTimeout(context.Background(), time.Second)
    defer cancel()
    message, err := subscriber.Receive(ctx)
    if err != nil { return err }
    fmt.Println(string(message))
    return nil
}

Options

type Options struct {
    Name, Path string
    Capacity   int
}

Name identifies the queue. Empty Path uses the OS temporary directory; Windows ignores it. Capacity is message-buffer bytes, greater than 16 and divisible by 8. Options must match all other participants.

Publisher

OpenPublisher(o Options) (*Publisher, error)

Creates or joins the transient queue and registers a publisher. Defer Close after a successful open.

(*Publisher).TrySend(message []byte) (bool, error)

Copies a message without waiting for space. (false, nil) means full or recovering; (true, nil) means committed.

(*Publisher).Close() error

Waits for the current native calls, releases the endpoint, and returns nil. Repeated calls are safe.

Subscriber

OpenSubscriber(o Options) (*Subscriber, error)

Creates or joins the queue as a competing subscriber.

(*Subscriber).TryReceive() ([]byte, error)

(nil, nil) means no ready message. A received empty message is a non-nil zero-length slice. Returned bytes are owned by Go.

(*Subscriber).TryReceiveInto(buffer []byte) (int, bool, error)

Returns bytes copied, whether a message was consumed, and an error. The boolean distinguishes an empty queue from an empty message. An undersized buffer truncates and consumes the entire message.

(*Subscriber).Receive(ctx context.Context) ([]byte, error)

Waits for a message, closure, or context cancellation. Returns ctx.Err() for cancellation or deadline expiry. Pass context.Background() for an indefinite wait; do not pass a nil context.

(*Subscriber).Close() error

Waits for current native calls before releasing the handle. Outstanding receives observe ErrClosed on their next attempt. Repeated close is safe.

Errors

Use errors.Is with ErrInvalidArgument, ErrCapacityMismatch, ErrPublisherLimit, ErrExhausted, ErrCorrupt, ErrIO, ErrInternal, or ErrClosed. Full queues are reported through the send boolean, not a sentinel error. Context errors are context.Canceled or context.DeadlineExceeded.

Concurrency and scheduling

Do not copy endpoints after first use. Always close them; concurrent operations are protected against handle release. Each idle Receive uses a Go timer with 1–10 ms adaptive backoff, interrupted by context cancellation. It does not keep an OS thread blocked in cgo while idle. Prefer one receive loop per subscriber and distribute work after receiving.

This binding has no batch-send method. For lifetime and delivery guarantees, see queue concepts.