Fixed-capacity control block container for non-copyable, non-movable types. More...

#include <memory>
#include <vector>
#include <type_traits>
#include "jh/conceptual/container_traits.h"

Classes
class	jh::sync::control_buf< T, Alloc >
	Fixed-capacity, block-allocated container for control-only types (e.g., mutexes, atomics). More...

Namespaces
namespace	jh::sync
	Aggregated entry point for synchronization and coordination facilities.

Macros
#define	JH_CTRL_BUFFER_BLOCK_SIZE 64
	Specifies the number of elements allocated per block in jh::sync::control_buf (default: 64).

Detailed Description

Fixed-capacity control block container for non-copyable, non-movable types.

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

Author: JeongHan-Bae <mastropseudo@gmail.com>

Overview

jh::sync::control_buf<T> is a special-purpose, heap-backed container designed to store control-related types (such as std::mutex or std::atomic) that are:

Default-constructible
Non-copyable and non-movable
Unsuitable for use with std::vector, std::deque, etc.

Unlike STL containers, this type intentionally disables element-wise relocation such as move or copy during reallocation. This is critical for storing control-type objects whose addresses must remain stable during their lifetime — for instance, synchronization primitives like std::mutex, std::atomic, or file descriptors.

This constraint is formalized by rejecting types that satisfy jh::concepts::is_contiguous_reallocable, which checks whether a type supports move- or copy-based relocation under contiguous growth strategies.

Internally, control_buf uses a block-allocated growth model, where memory is allocated in fixed-size blocks. These blocks are never relocated, and each element is constructed in-place, preserving pointer stability.

Core Features

Block-based allocation: memory grows by allocating fixed-sized blocks on demand.
Block size: each block contains JH_CTRL_BUFFER_BLOCK_SIZE elements (default: 64). This can be configured via a preprocessor macro.
Each element is default-constructed in-place; no relocation, no reordering.
Strict type constraints: relocation-disabled types only (e.g. std::mutex).
Dynamic growth supported at block level (like std::deque), but never at element level.
No iteration interfaces (e.g., range-for); access is by index only.
Allocator-aware with safe RAII block lifetime management.

Key Properties

Only supports emplace_back() to append default-constructed elements.
Does not support resizing via insert/erase; only resize() or clear().
Provides indexed access but not STL-compatible iteration or range-for loops.
Respects allocator customization through standard std::allocator_traits.

Note: This is not a general-purpose container. It should only be used for types explicitly disallowed from standard containers due to allocator or relocation requirements (e.g., std::mutex, std::atomic).

See also: jh::concepts::is_contiguous_reallocable

Version

1.4.x

Date

Macro Definition Documentation

◆ JH_CTRL_BUFFER_BLOCK_SIZE

#define JH_CTRL_BUFFER_BLOCK_SIZE 64

Specifies the number of elements allocated per block in jh::sync::control_buf (default: 64).

This macro controls the fixed block size used for internal block-based allocation. Larger values reduce allocation frequency but increase per-block memory usage.

Classes