process_counter.h File Reference

Cross-process shared integer counter implemented via named shared memory. 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 <cstring>
#include <cerrno>
#include <stdexcept>
#include <string>
#include <functional>
#include <sys/mman.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <unistd.h>

Go to the source code of this file.

Classes
class	jh::sync::ipc::process_counter< S, HighPriv >
	Cross-process integer counter stored in shared memory (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 shared integer counter implemented via named shared memory.

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_counter provides a process-visible 64-bit integer stored in OS-level shared memory and synchronized by a per-instance process_mutex<S + ".loc">. It behaves as a globally accessible atomic counter with read-modify-write semantics enforced through inter-process locking.

Implementation

• POSIX (Linux / BSD / Darwin):
  • Backed by shm_open + mmap.
  • Permissions determined by JH_PROCESS_MUTEX_SHARED (0644 or 0666).
  • No special privileges required.
• Windows / MSYS2:
  • Backed by CreateFileMapping + MapViewOfFile.
  • Objects are created under the Global\ namespace for inter-process visibility.
  • Administrator privilege is required to create or open Global\ objects.

Naming rules

• Allowed characters: [A-Za-z0-9_.-].
• No leading slash ('/'); it is added automatically when required by the OS.
• Name length is platform-dependent:
  • FreeBSD / Darwin: 30 characters (POSIX limit 31 bytes including '/').
  • Linux / Windows: 128 characters (portable engineering limit).
• The limit is verified at compile time using jh::sync::ipc::limits::valid_object_name<S, limits::max_name_length - 4>, where -4 reserves space for the ".loc" suffix used by its mutex.

unlink semantics

• POSIX: calls shm_unlink(); existing mappings remain valid until unmapped by all processes. The operation is idempotent.
• Windows: no explicit unlink; shared memory is destroyed automatically when the last handle closes.

Windows privilege requirement

On Windows, process_counter requires administrator privilege because shared memory objects are created in the Global\ namespace. This does not affect POSIX systems.