Cross-process shared-memory container for POD-like objects. More...

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

Classes
class	jh::sync::ipc::process_shm_obj< S, T, HighPriv >
	Cross-process shared-memory container for a single POD-like object. 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 shared-memory container for POD-like objects.

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_shm_obj exposes a process-visible, named shared-memory region containing a single POD-like object of type T. All participating processes reference the same mapped storage, coordinated through a pair of inter-process mutexes.

Type constraints

T must satisfy jh::pod::cv_free_pod_like.
This means T is trivially copyable, constructible, destructible, and has standard layout, without const or volatile qualification.
This restriction ensures T can be directly memory-mapped without invoking constructors or destructors.

Implementation

POSIX (Linux / BSD / Darwin):
- Backed by shm_open() + mmap().
- Permissions determined by JH_PROCESS_MUTEX_SHARED (0644 or 0666).
Windows / MSYS2:
- Backed by CreateFileMapping() + MapViewOfFile().
- Objects reside in Global\ namespace for inter-process visibility.
- Administrator privilege required to open or create mappings.

Internal synchronization objects

Initialization mutex: process_mutex — protects one-time initialization of the mapped region.
Access mutex: process_mutex<S + ".loc"> — protects all concurrent writes and ensures serialization of modifications.

Both mutexes are created in the same namespace as the shared object. Declaring a separate process_mutex or process_mutex<S + ".loc"> externally will conflict with this internal synchronization scheme.

`Usage guidelines`



Call instance() to obtain the singleton mapping. 

Use lock() to acquire the access mutex before any write. 

Perform reads using flush_acquire() beforehand to guarantee visibility of the latest writes from other processes. 

When writing: 

Acquire a std::lock_guard (RAII style) on lock(). 

Modify the object via ref() or ptr(). 

Before releasing the lock — i.e., before the RAII guard leaves scope — call flush_release() or flush_seq() to publish the change. 



This class generalizes process_counter: it provides the same memory-sharing model but allows arbitrary POD layouts. Users must therefore manually manage synchronization scope and visibility fences.

`Unlink semantics`



POSIX: Invokes shm_unlink() for the region, then calls process_mutex<S>::unlink() and process_mutex<S + ".loc">::unlink() to remove both locks. 

Windows: No explicit unlink; shared objects are destroyed automatically once all handles are closed. 

Operation is idempotent; redundant calls are safe.

`Windows privilege requirement`

On Windows, this primitive requires administrator privilege because named shared objects and events are created under Global\. POSIX platforms impose no such restriction.

Classes

Namespaces