sem_safe

An interface to POSIX Semaphores that is Rust-ified, but direct, and no_std, and enforces safe usage of them.

Example

// (The `Semaphore` type under the `plaster` module enables portability even to macOS.)
use sem_safe::{plaster::non_named::Semaphore, non_named::Semaphore as _};
use std::{pin::Pin, thread, sync::atomic::{AtomicI32, Ordering::Relaxed}};

static SEMAPHORE: Semaphore = Semaphore::uninit();
static THING: AtomicI32 = AtomicI32::new(0);

fn main() {
    let sem = Pin::static_ref(&SEMAPHORE);
    let sem = sem.init().unwrap();

    thread::spawn(move || {
        THING.store(1, Relaxed);
        // It's guaranteed that this thread's preceding writes are always visible to other threads
        // as happens-before our post is visible to (and possibly wakes) other threads.
        sem.post().unwrap();
    });

    sem.wait().unwrap();
    // It's guaranteed that this thread always sees the other thread's write as happens-before
    // this thread sees the other thread's post (that woke us if we'd waited).
    assert_eq!(1, THING.load(Relaxed));
}

Motivation

POSIX Semaphores, in particular the sem_post function, are especially useful for an async-signal handler to wake a blocked thread, because sem_post() is async-signal-safe (in contrast to many thread-waking APIs, such as Thread::unpark or channels, that don't guarantee this). sem_post provides the critical ability to wake another thread (e.g. to further handle exfiltrated representations of the received signals in a normal context (without the extreme restrictions of async-signal safety)), from within an extremely-limited signal handler.

Signal-handling is not the only use-case. POSIX Semaphores also enable various patterns of coordinating and synchronizing multiple processes, which could be compelling. This crate provides an analogue of the C API that can be used for various other semaphore use-cases. Both the unnamed and the named semaphores APIs are supported, for both the shared-between-multiple-processes mode or the private-to-only-a-single-process mode. The rest of the API for "timed-wait" could be implemented in the future.

Unlike std::thread parking, this crate does not require the std library, and this crate's semaphores can wake multiple threads on a single semaphore, can model resource counts greater than one, can be used between multiple processes, and this crate's SemaphoreRef::post guarantees async-signal-safety.

Design

The challenges with using POSIX Semaphores safely and in the Rust ways, and what this crate provides solutions to, are:

• To share a semaphore between multiple threads, the type must be Sync, which requires "interior mutability". This crate implements its own abstractions over UnsafeCell<libc::sem_t> or *mut libc::sem_t to achieve this, and this also enables values of these to be global static items (not mut) which can be convenient, or values of these can be shorter-lived locals and lifetime-safety is enforced.

• The values of the unnamed sem_t type must start as uninitialized and then be initialized by calling sem_init(), and the values of the named sem_t * must be initialized by calling sem_open(), before applying any of the other operations to them. This crate has separate owned Semaphore and borrowed SemaphoreRef types to enforce that the operations can only be done to safe references to initialized values and that the references can only be gotten after initializing owned values, which first requires pinning for the unnamed type. This also ensures thread safety.

• Deinitialization (sem_destroy() or (safely) sem_close()) is only done when dropping an owned Semaphore and only if it was initialized. Dropping is prevented when there are any SemaphoreRefs extant, which prevents invalidating a semaphore when there still are potential use-sites. This also ensures avoidance of undefined behavior.

• It's not clear if moving a sem_t value is permitted after it's been initialized with sem_init(). The POSIX and OpenIndiana man pages say that "copies" (which would be at addresses different than where initialized) would be undefined, which might imply that moved values could also be. This crate uses Pinning to enforce that the values can't be moved once initialized.

• The sem_init() must only be done once to a sem_t. Creating an anonymous semaphore must only do sem_open() once. This crate uses atomics directly (because this crate is no_std) to enforce this, even if there are additional calls and perhaps from multiple threads concurrently.

Crate Features

All features below are enabled by default. All are optional, except at least one of unnamed or named must be enabled, and except as otherwise noted for Mac.

• unnamed - Enables the Unnamed Semaphores of POSIX. Unavailable on Mac and ignored there.
• named - Enables the Named Semaphores of POSIX. Required on Mac.
• anonymous - Enables the crate's own semaphore abstraction that is a "named" semaphore whose name doesn't exist and so can't be used, which is especially useful for non-named use-cases that need a workaround on Mac.
• plaster - Enables the crate's own shim that provides a uniform API for non-named use-cases to be portable across Mac and all other OSs. This "plasters over" the lack of unnamed semaphores on Mac by using anonymous semaphores on Mac or using unnamed semaphores on all other OSs.

Portability

This crate was confirmed to build and pass its tests on (x86_64 only so far):

• BSD
  • FreeBSD 14.0
  • NetBSD 9.1
  • OpenBSD 7.5
• Linux
  • Adélie 1.0 (uses musl)
  • Alpine 3.18 (uses musl)
  • Debian 12
  • NixOS 24.05
  • RHEL (Rocky) 9.4
  • openSUSE 15.5
  • Ubuntu 23.10
• Mac
  • 10.13 High Sierra
  • 12 Monterey
• Solaris
  • OpenIndiana 2024.04

All glibc- or musl-based Linux OSs, and all macOS and Mac OS X versions, should already work. It might already work on further POSIX OSs. If not, adding support for other POSIX OSs should be easy but might require making tweaks to this crate's conditional compilation and/or linking.

macOS Partially Unsupportable

Unfortunately, macOS (and Mac OS X) does not provide the unnamed semaphores API nor the sem_getvalue function (in violation of modern POSIX versions requiring these), and so it's not possible for those aspects of this crate to work on macOS. However, this crate's support for the named semaphores does work on macOS because it does provide that. This crate provides a helper to create anonymous "named" semaphores that are mostly like unnamed private semaphores, and this crate provides an abstraction for use across all OSs that uses the anonymous or unnamed semaphores depending on the OS's support, for use-cases of non-named private semaphores that need a workaround on macOS.

OpenBSD Partially Unsupportable

Unfortunately, OpenBSD does not provide the shared-between-multiple-processes unnamed semaphores API, and so it's not possible for that aspect of this crate to work on OpenBSD. However, this crate's support for the private-to-only-a-single-process unnamed semaphores and for all of the named semaphores (which can be shared between multiple processes) does work on OpenBSD because it does provide those.