process_mutex.h File Reference

Cross-platform process-wide named mutex with timed try_lock. More...

#include "jh/metax/t_str.h"
#include "jh/macros/platform.h"
#include "jh/synchronous/ipc/ipc_limits.h"
#include <algorithm>
#include <string>
#include <stdexcept>
#include <chrono>
#include <cstdint>
#include <thread>
#include <semaphore.h>
#include <fcntl.h>
#include <cerrno>
#include <sys/stat.h>

Go to the source code of this file.

Classes
class	jh::sync::ipc::process_mutex< S, HighPriv >
	Cross-platform named process-wide mutex primitive. More...

Namespaces
namespace	jh::sync
	Aggregated entry point for synchronization and coordination facilities.
namespace	jh::sync::ipc
	Synchronous inter-process coordination primitives.

Macros
</code></li>
Because the name is a compile-time constant, invalid or overly long identifiers produce a compile-time error, ensuring deterministic and portable IPC behavior across all supported platforms. unlink semantics POSIX (Linux & UNIX): sem_unlink() removes the name from the namespace immediately, but does not destroy existing semaphore objects. Any process that already opened the semaphore can continue using it. The actual semaphore is destroyed only after all processes close their descriptors via sem_close(). New processes cannot open the same name until all old descriptors are closed. Windows / MSYS2: no unlink() concept. Named semaphores persist while any process holds an open handle and are destroyed automatically once the last handle closes. Permissions policy (POSIX only) Semaphore permission bits control which users can open or unlink the semaphore name. This library enforces a simple policy: If JH_PROCESS_MUTEX_SHARED is false (default): the mode is 0644 (only the creating user can unlink; others can open read-only). If JH_PROCESS_MUTEX_SHARED is true: the mode is 0666 (any user can open and unlink). This affects only the namespace (open/unlink); locking semantics are unaffected. On Windows, mode_t does not exist; access control is managed internally by the Win32 API and is unaffected by this policy. Standards note sem_open, sem_wait, sem_post, sem_unlink are part of the POSIX base standard. sem_timedwait belongs to the POSIX Realtime Extension (POSIX.1b). Linux/glibc exposes it widely. On pure POSIX systems (Darwin, BSD), it is not available, so this library emulates timed waits via backoff loop.
#define	JH_PROCESS_MUTEX_SHARED   false

Detailed Description

Cross-platform process-wide named mutex with timed try_lock.

Copyright

Copyright 2025 JeongHan-Bae <mastropseudo@gmail.com>
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Full license: GitHub

Overview

jh::sync::ipc::process_mutex is a cross-platform, process-wide synchronization primitive identified by a compile-time string literal. Each unique literal corresponds to a unique OS-level named semaphore.

Implementation

1. POSIX (Linux & generic UNIX): created/opened via sem_open, synchronized with sem_wait, sem_post.
   • POSIX + Realtime Extension (e.g. Linux/glibc): timed waiting via POSIX.1b API sem_timedwait.
   • Pure POSIX platforms (e.g. Darwin/macOS, some BSDs): the SDK does not declare sem_timedwait. Timed waiting is emulated with sem_trywait + exponential backoff sleep to approximate semantics.
2. Windows / MSYS2: implemented via Win32 API (CreateSemaphore, WaitForSingleObject, ReleaseSemaphore).

Naming rules

• Allowed characters: [A-Za-z0-9_.-].
• No leading slash ('/'); it is automatically added when required by the underlying platform namespace.
• Name length limits are platform-specific:
  • FreeBSD / Darwin (macOS): maximum base name length = 30 (POSIX limit is 31 bytes including the leading '/').
  • Linux / Windows / WASM: extended portable limit = 128.
  The limit is automatically enforced at compile time by jh::sync::ipc::limits::valid_object_name.
• Prefixes are applied automatically:
  • POSIX: "/" is prepended internally (per POSIX naming convention).
  • Windows:
    • C++ literal name: "Local\\name"
    • Runtime Win32 object: Local