Crate procref 

procref - Cross-platform Process Reference Counting

A library for managing shared service lifecycles across multiple processes using kernel-level reference counting mechanisms.

Platform Support

Platform	Mechanism	Auto-cleanup on crash
Linux	System V Semaphore + SEM_UNDO	✅ Kernel auto-undo
macOS	Mach Port send rights	✅ Kernel auto-release
Windows	Named Semaphore	✅ Handle auto-close

Design Philosophy

This library trusts the kernel to manage reference counts, not userspace files. When a process crashes:

• The kernel automatically decrements the reference count
• No stale state accumulates
• No manual cleanup needed

Files (like port hints) are just hints for optimization, not the source of truth. The actual process state is always verified against reality.

Lifecycle Callbacks

The library provides hooks for business logic at key lifecycle points:

• on_first_acquire: Called when first client registers (count 0→1)
• on_last_release: Called when last client exits (count 1→0)
• on_health_check: Called to verify service is healthy
• on_recover: Called when service needs recovery

Usage

use procref::{SharedService, ServiceInfo};

let service = SharedService::builder("my-database")
    .on_first_acquire(|| async {
        // Start the database process
        let port = 5432;
        let pid = start_database(port)?;
        Ok(ServiceInfo::new(pid, port))
    })
    .on_last_release(|info| async move {
        // Stop the database when last client exits
        procref::process::terminate(info.pid());
        Ok(())
    })
    .build()?;

// Acquire a reference (starts service if first client)
let handle = service.acquire().await?;
println!("Service running on port {}", handle.info().port());

// handle.drop() releases reference
// If last client, on_last_release is called

Modules

process

Utility functions for process management.

Structs

PlatformRefCounter

Linux reference counter using System V semaphores.

ServiceHandle

A handle to a shared service.

ServiceInfo

Information about a running service.

SharedService

Shared service manager.

SharedServiceBuilder

Builder for SharedService.

Enums

Error

Errors that can occur in procref operations.

Traits

RefCounter

Core trait for kernel-level reference counting.

Type Aliases

Result

Result type alias for procref operations.