SharedMemoryStore 1.0.0

SharedMemoryStore

SharedMemoryStore is a net10.0 library package for bounded named shared-memory key-value storage. It stores opaque byte keys, optional descriptor bytes, and immutable payload bytes in a memory-mapped region so producers and readers can exchange data without copying payloads through a broker process.

Package identity:

• PackageId: SharedMemoryStore
• Version: 1.0.0
• Target framework: net10.0
• License: MIT, see the license file
• Runtime dependencies: .NET BCL only

The 1.0.0 package establishes the production public API contract. Linux and Windows are supported runtime and development targets. Same-host Linux Docker containers are supported when they share the required IPC, owner-liveness, permission, and shared-memory capacity capabilities. C++ and Python are future portability audiences, not current bindings.

What It Provides

The initial public contract supports:

• create or open a named store with explicit capacity limits.
• publish immutable value bytes and optional descriptor bytes under an opaque byte key.
• acquire a ValueLease, read descriptor and value spans, and release or dispose the lease exactly once.
• remove values and reuse slots after active readers release their leases.
• reserve store-owned payload memory for direct length-delimited frame ingest, advance exact write progress, and commit atomically.
• publish segmented buffered payloads through ReadOnlySequence<byte> without a temporary full-payload array.
• abort or explicitly recover incomplete reservations without exposing partial bytes to readers.
• run owner-controlled stale lease recovery when enabled.
• inspect caller-formatted diagnostics snapshots without library console output, including lease recovery results and key-index tombstone health.

The store does not parse frame headers, own application schemas, provide a cross-host cache, persist data beyond process and mapping lifetime, or turn Docker into distributed storage.

First Use

For package consumers, start with Getting started and the Usage guide. A local package source workflow is documented because this prerelease repository may be consumed before a public NuGet publish.

dotnet pack src/SharedMemoryStore/SharedMemoryStore.csproj -c Release -o artifacts/package
dotnet new console -f net10.0 -n SharedMemoryStore.Tryout -o artifacts/tryout
dotnet add artifacts/tryout/SharedMemoryStore.Tryout.csproj package SharedMemoryStore --source artifacts/package

Minimal workflow:

using SharedMemoryStore;

var options = new SharedMemoryStoreOptions
{
    Name = $"sms-{Guid.NewGuid():N}",
    OpenMode = OpenMode.CreateOrOpen,
    SlotCount = 2,
    MaxValueBytes = 64,
    MaxDescriptorBytes = 16,
    MaxKeyBytes = 16,
    LeaseRecordCount = 4,
    EnableLeaseRecovery = true,
    TotalBytes = SharedMemoryStoreOptions.CalculateRequiredBytes(2, 64, 16, 16, 4)
};

var open = MemoryStore.TryCreateOrOpen(options, out var store);
if (open != StoreOpenStatus.Success || store is null)
{
    return;
}

using (store)
{
    var status = store.TryPublish([1, 2, 3], [4, 5, 6], [9]);
    status = store.TryAcquire([1, 2, 3], out var lease);
    var firstByte = lease.ValueSpan[0];
    status = lease.Release();
    status = store.TryRemove([1, 2, 3]);

    status = store.TryReserve([4], 3, [1], out var reservation);
    new byte[] { 7, 8, 9 }.CopyTo(reservation.GetSpan());
    status = reservation.Advance(3);
    status = reservation.Commit();
}

Expected operational failures are returned as StoreOpenStatus or StoreStatus values. See Errors and statuses for duplicate keys, missing keys, full stores, oversized values, invalid leases, unsupported platforms, stale leases, cleanup failures, and version mismatches. Current-process lease recovery skips other live owner processes, disposal races return documented statuses or empty token views, and slot lifecycle identity is safe across generation rollover.

Documentation

• Documentation index: complete table of contents by audience.
• Getting started: install, local package source, minimal workflow, and expected statuses.
• Concepts: store, name, key, descriptor, payload, slot, lease, reservation, wait policy, status, diagnostics, recovery, capacity, lifecycle, portability, and package contract vocabulary.
• Byte encoding: canonical key, descriptor, and payload byte layouts with allocation-conscious helper patterns.
• Usage guide: create/open, publish, reserve, segmented publish, acquire, release, remove, reuse, diagnostics, recovery, and dispose.
• Examples: basic values, frame-shaped values, direct reservation ingest, segmented payloads, diagnostics, waits, and error handling.
• Errors and statuses: deterministic status outcomes and troubleshooting.
• Diagnostics: snapshot fields and consumer-owned observability.
• Lifecycle: store ownership, leases, removal, stale recovery, abnormal termination, and cleanup.
• Integration: optional lifecycle, health, hosting, and narrow-interface boundaries outside the core package.
• Performance scope: measured scope and unmeasured claims.
• Portability: .NET 10 baseline, Linux, Windows, and same-host Docker support, layout compatibility, and future C++/Python constraints.
• Samples: ordered runnable sample ladder from minimal usage through frame values, zero-copy ingest, optional hosted integration, and same-host Docker validation.
• Architecture: maintainer internals, source areas, invariants, storage, lifecycle, synchronization, recovery, and diagnostics.
• Maintainers: documentation update rules, validation commands, contract boundaries, performance evidence, and release impact.
• Packaging: package metadata, package README, release notes, and clean consumer validation.
• Release preparation: maintainer checks before publication.

Detailed behavior sources:

• Public API contract
• Error taxonomy contract
• Shared-memory layout contract
• Reservation API contract
• Ingest layout contract
• Reservation diagnostics and errors
• Owner recovery hardening contract
• Disposal and rollover hardening contract
• Index health hardening contract
• Production public API contract
• Contention configuration contract
• Diagnostics integration contract
• Reservation memory contract

Runnable samples:

• Basic usage sample
• Frame value sample
• Zero-copy ingest sample
• Hosted service integration sample
• Docker shared-memory sample

Project Policies

• Contributing: setup, validation, compatibility review, and pull request expectations.
• Code of conduct: project-specific conduct expectations.
• Support: questions, bugs, unsupported scenarios, and best-effort prerelease support.
• Security: private vulnerability reporting guidance.
• Issue templates: bug report, documentation issue, and feature request.
• Pull request template: review checklist for behavior, API, package, validation, documentation, compatibility, security, support, and release-note impact.
• Changelog: reverse-chronological package and documentation history.
• Release notes: release readiness checklist and package notes alignment.

Local Validation

pwsh ./scripts/validate-docs.ps1
dotnet build SharedMemoryStore.slnx -c Release
dotnet run --project samples/BasicUsage/BasicUsage.csproj -c Release
dotnet run --project samples/FrameValue/FrameValue.csproj -c Release
dotnet run --project samples/ZeroCopyIngest/ZeroCopyIngest.csproj -c Release
dotnet run --project samples/HostedServiceIntegration/HostedServiceIntegration.csproj -c Release
dotnet run --project samples/DockerSharedMemory/DockerSharedMemory.csproj -c Release -- all
pwsh ./scripts/validate-package-consumption.ps1
dotnet test SharedMemoryStore.slnx -c Release
dotnet pack src/SharedMemoryStore/SharedMemoryStore.csproj -c Release -o artifacts/package
pwsh ./scripts/validate-cross-platform.ps1 -SkipDocker
pwsh ./scripts/validate-docker-shared-memory.ps1

Documentation changes must keep package metadata, README content, release notes, support policy, security policy, and contract links aligned with the current 1.0.0 package behavior.