Primatomic API Docs

Primatomic is a distributed synchronization system providing consistent locks, read/write locks, atomic key-value operations, and high-performance memory regions via a gRPC API. It ensures reliable coordination for microservices requiring synchronization across multiple processes or hosts.

Key Features

  • Distributed Concurrency Primitives – acquire and release exclusive or shared locks with automatic TTL cleanup
  • Atomic Key-Value Store – thread-safe operations with compare-and-swap support and namespace isolation
  • High-Performance Memory Regions – shared memory with NVMe-oF backend for sub-millisecond access
  • High Availability – built on Raft consensus algorithm with automatic cluster formation
  • Multi-Language SDKs – comprehensive Python SDK and JavaScript client libraries
  • Usage Tracking – integrated billing and metrics collection for SaaS deployments
  • Kubernetes Native – Helm charts and StatefulSet deployment with automatic scaling

Quick Start

Local Development

Launch a local three-node cluster with NATS using Docker Compose:

docker compose -f conserver/dev.docker-compose.yaml up --build

Kubernetes Deployment

Deploy using the Helm chart (recommended):

cd primatomic
helm dependency build
helm upgrade --install primatomic . --namespace primatomic --create-namespace

Python SDK Usage

import primatomic

client = primatomic.Client("localhost:50051")

# Key-value operations
await client.put_key("mykey", b"myvalue", namespace="test")
value = await client.get_key("mykey", namespace="test")

# Distributed locking
async with client.lock("resource", namespace="test"):
    # Critical section
    pass

# Memory regions for high-throughput data
region_id = await client.allocate_memory(1024*1024, namespace="test")
await client.write_memory(region_id, 0, b"data")

Authentication

For production deployments, all operations require JWT authentication. Generate tokens using the CLI:

scripts/primctl token --namespace myapp --ttl 24h

API Reference

The following sections document each API endpoint in detail with comprehensive examples and usage patterns.