process_cond_var.h File Reference

Cross-process condition variable primitive implemented via shared memory or named events. More...

#include "jh/metax/t_str.h"
#include "jh/macros/platform.h"
#include "jh/synchronous/ipc/process_mutex.h"
#include "jh/synchronous/ipc/ipc_limits.h"
#include <chrono>
#include <stdexcept>
#include <string>
#include <sys/mman.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <unistd.h>
#include <cerrno>
#include <cstring>
#include <pthread.h>

Go to the source code of this file.

Classes
class	jh::sync::ipc::process_cond_var< S, HighPriv >
	Cross-process condition variable primitive (POSIX / Win32). More...

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

Detailed Description

Cross-process condition variable primitive implemented via shared memory or named events.

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_cond_var is an inter-process signaling primitive modeled after pthread_cond_t / std::condition_variable_any. It provides a minimal, globally visible synchronization point usable across processes, implemented entirely via OS-named IPC mechanisms.

Platform implementation

• POSIX (Linux / BSD / Darwin):
  • Backed by shm_open + mmap + pthread_cond_t.
  • Condition and mutex objects are marked PTHREAD_PROCESS_SHARED.
  • All processes share the same shared-memory segment; no privilege escalation required.
• Windows / MSYS2:
  • Backed by CreateEventA and WaitForSingleObject.
  • Uses Global\ namespace for inter-process visibility.
  • Administrator privilege is required to create or open Global\ named events.

Design stance

In the jh-toolkit IPC model, Windows is treated as a second-class citizen: API compatibility and basic semantics are preserved, but exact parity of behavior (particularly in multi-notification semantics) is not guaranteed.

Notification semantics

• POSIX: notify_all(n) signals up to n waiting processes (default 32). Exceeding waiters remain blocked until the next call.
• Windows: there is no native multi-waiter broadcast. notify_all() simulates this behavior by setting the event for ~1 ms, which is sufficient for most engineering use cases but not strictly equivalent.
• For deterministic coordination across multiple listeners, users should layer a process_counter to implement precise wake control.

Privilege requirement

On POSIX systems, process_cond_var requires no special privileges. On Windows, due to Global\ namespace policy, creation and access require administrative rights. The same restriction applies to process_counter.

Design guarantees

• Global visibility: all processes referencing the same name participate in the same wait-set.
• Process-safe: internally protected by pthread_mutex_t or event handle.
• Primitive-level abstraction: can be freely composed with other IPC primitives (process_mutex, process_counter) to form higher-level protocols.
• Portable API: interface parity across POSIX and Windows, despite differing kernel behavior.

Unlink semantics

• POSIX: invokes shm_unlink() on the internal shared-memory segment.
• Windows: no explicit unlink; event objects are destroyed when the last handle closes.
• As with other IPC primitives, the operation is idempotent — redundant calls are no-ops.

Usage note

process_cond_var is an IPC primitive. It does not guarantee fairness or broadcast consistency across all platforms. Developers are encouraged to compose it with process_mutex or process_counter when building higher-level coordination patterns.