It offers object pooling, safe immutable strings, coroutine-powered async facilities with sync-style syntax, a lightweight POD framework, expressive metaprogramming utilities, semantically rich range/view extensions, inter-process coordination primitives, new associative containers, and stable serialization components
— entirely RTTI-free and concurrency-friendly.
Let's meet our mascot — Oree
Oree, the green-headed duck whose name comes from the Korean word "오리",
embodies the philosophy of the JH Toolkit — a world where
if it behaves like a duck, it is a duck.
Instead of enforcing inheritance, the toolkit follows behavioral compatibility:
every type belongs by what it can do, not by what it inherits.
Oree represents freedom, adaptability, and elegance —
just like modern C++ itself.
JH Toolkit uses C++20 as a baseline, not as a showcase.
The choice is driven by the need for foundational language guarantees and tooling support, including:
- C++17+ guaranteed RVO/NRVO for predictable value semantics
- C++17 facilities such as
std::string_viewandstd::variant - C++20 coroutines for zero-boilerplate async composition
- C++20 NTTPs for compile-time identity and structural binding
More importantly, C++20 enables SFINAE + concepts–based constraints, which are used to:
- ensure behavior is locally and globally predictable
- enforce semantics that match the documented intent
- prevent invalid or ambiguous usage at compile time
- help compilers—especially LLVM-Clang—perform deeper analysis, pruning, and optimization
This improves both safety and performance, often by eliminating entire classes of misuse before code generation.
C++20 is therefore adopted as an engineering tool, not as a language feature showcase. The goal is not to demonstrate what "modern C++" can express, but to use the language to constrain behavior, reduce ambiguity, and support reliable system design.
Modern C++ is already a strong fit for software development workloads.
Even when it is not used as the exclusive implementation language, it can reliably take responsibility for critical parts of a system—such as high-performance paths, security-sensitive components, or logic that requires strong semantic guarantees.
Modern C++ integrates cleanly with long-lived, stable interfaces such as gRPC, HTTP-based services, and Cython bindings, allowing it to coexist naturally in polyglot systems. In such architectures, it is preferable to rely on typed, structured interfaces rather than raw C ABIs, which tend to erase semantics and weaken safety and auditability.
Importantly, modern C++ enables auditable and highly predictable systems. Its type system, constexpr facilities, and concepts allow illegal or ambiguous behavior to be intercepted at compile time, rather than deferred to runtime. This makes it possible to enforce design intent mechanically, not socially.
Modern C++ also supports safe semantic encapsulation of system-level primitives. Low-level APIs (for example, POSIX IPCs) can be wrapped into higher-level, intention-revealing abstractions with explicit guarantees—such asjh::ipc, which provides a semantic, constrained interface over POSIX IPC mechanisms.
From a performance standpoint, modern C++ is inherently fast—significantly faster than all dynamic languages, including those using ahead-of-time compilation. This performance comes without requiring heavyweight runtimes or hidden dynamic metadata.
Finally, modern C++ operates naturally in no-RTTI environments, does not require additional dynamic type data, and avoids bloated runtime infrastructures. When combined with specialized, allocation-aware data structures (such as those provided by JH Toolkit), it enables low fragmentation, compact memory layouts, and predictable resource usage—properties that are essential for long-running, production-grade software systems.
The project builds with GCC 13+ or Clang 15+, with GCC 14+ or LLVM 20 strongly recommended for optimal performance and language support. MSVC is not supported.
For complete build instructions, supported toolchains, and Conan packaging notes, refer to the Build & Platform Guide.
Covers: toolchains, CMake targets, Conan
.tar.gzreleases, and the dual-mode header design.
The project has no runtime dependencies.
Its only build-time requirement is a conforming C++20 standard library.
Testing uses Catch2.
For version details, see: Dependencies.
Below is the complete list of user-facing aggregate forwarding headers provided by JH-Toolkit. These headers are the recommended entry points for reading the API documentation.
All listed headers are suffix-free (for example, <jh/async>).
Headers ending with .h are implementation headers and are not intended as primary reading targets.
Each link below points to an overview document for the corresponding forwarding header. From there, you can navigate downward into each concrete submodule and its detailed API documentation.
In short: Start from the forwarding header overview → then drill down into specific APIs as needed.
The list below is ordered alphabetically by forwarding header name.
This ordering is purely for readability and navigation convenience and does not reflect internal structure,
module hierarchy, or dependency relationships.
Each entry links to a corresponding documentation page under the docs/ directory.
These pages are built-in, quick-start–level Markdown documents that introduce each module from a
usage-oriented and conceptual perspective.
They are intended to provide orientation, high-level guidance, and typical usage patterns.
The documents under docs/ are not exhaustive semantic specifications.
They deliberately focus on what to use and when to use it, rather than enumerating every rule and constraint.
For detailed and complete semantics—including:
- precise class and function behavior
- initialization requirements (copy, move, aggregate, and other forms)
- template constraints and substitution rules
- documented warnings, assumptions, and corner cases
please refer to the Doxygen documentation, which is the authoritative source.
The Doxygen documentation can be read either:
- directly inside an IDE (with classic CLion as the reference environment), or
- via the official pre-rendered web pages.
Due to the flat layout of the public headers under include/, forwarding headers without file suffixes
(for example, <jh/async>) and their implementation directories (for example, jh/asynchronous/)
must use different names.
This is a constraint imposed by the file system: a directory and a suffix-free file cannot share the same name
within a single directory.
As a result:
- Suffix-free headers (such as
<jh/async>) are aggregate or forwarding headers and do not have a one-to-one "file-matching" documentation page.
Their documentation is provided explicitly in this table. - Concrete APIs and implementations follow a direct mapping:
include/jh/{path}/{name}.h↔docs/{path}/{name}.md
All documentation pages are cross-linked and intentionally guide readers between forwarding headers, concrete modules, and detailed API references.
Please rely on the actual documentation when understanding the library.
Do not infer behavior or structure from file names alone, and avoid relying on
AI-generated guesses that are not grounded in the documented contracts.
<jh/async> |
🌀 | API References |
<jh/concepts> |
🧩 | API References |
<jh/concurrency> |
🎍 | API References |
<jh/flat_multimap> |
🧱 | API References |
<jh/generator> |
🌀 | API References |
<jh/immutable_str> |
🧱 | API References |
<jh/ipc> (InterProcess Coordination) |
🛰️ | API References |
<jh/jindallae> (Easter Egg Alias) |
⚗️ | API References |
<jh/meta> |
⚗️ | API References |
<jh/ordered_map> |
🧱 | API References |
<jh/pod> |
🧊 | API References |
<jh/pool> |
🎍 | API References |
<jh/ranges_ext> |
🌗 | API References |
<jh/runtime_arr> |
🧱 | API References |
<jh/serio> |
🍯 | API References |
<jh/sync> |
⏱️ | API References |
<jh/typed> |
🧬 | API References |
<jh/views> |
🔭 | API References |
These forwarding headers represent the entire public surface area of JH-Toolkit. They are designed to aggregate stable user-facing APIs, independent of internal layout or implementation details.
From each overview page, you may continue navigating into:
- individual components
- submodules
- concrete type and function references
This structure intentionally replaces long conceptual introductions with a clear API map, allowing users to quickly locate relevant functionality and then explore it at the desired depth.
The primary source of truth for understanding JH Toolkit is its Doxygen documentation.
All semantic guarantees, design intent, usage constraints, and documented limitations are expressed through
Doxygen comments embedded directly in the public headers under include/.
These comments define the authoritative API contract.
Implementations exist to realize that contract and may change over time.
The documentation is authored with IDE-based reading as the primary target.
In particular, classic CLion is used as the reference environment during documentation design. When viewed in classic CLion, standard Doxygen (HTML-style) comments are rendered inline with the source code, providing:
- Inline, fully rendered documentation while reading headers
- Rich hover tooltips with complete semantic descriptions
- Seamless navigation between types, functions, and their documentation
This creates a reading experience where code and documentation interleave naturally, similar to notebook-style workflows in other ecosystems.
While the documentation is IDE-first by design, the web-based Doxygen documentation is fully and officially supported.
The complete API reference is available as pre-rendered Doxygen HTML pages at:
The web documentation is generated from the same Doxygen sources as the IDE views and reflects the same authoritative API contracts, semantics, and design intent. It is intended for reference, review, external access, and situations where an IDE-based workflow is not available.
If you encounter any visual or rendering issues in the web documentation, please report them via the issue tracker.
When reading the project, keep the following structure in mind:
-
include/
Contains all real definitions, public APIs, and documented semantics. This is the authoritative source of truth. -
src/
Contains precompiled instantiation translation units (TUs) used to support static builds and improve compile times. These files are not the semantic specification of the library.
Under modern C++ semantics, directly inspecting implementations is often misleading. The interface and its documentation already define the behavior. Reading implementation details without the documented context can lead to incorrect assumptions.
The recommended reading approach is therefore:
- Read Doxygen comments embedded in public headers
- Use the IDE-integrated documentation view (preferred) or the official web documentation
- Treat implementations as replaceable details, not specifications
Doxygen documentation is where:
- Semantic guarantees are stated
- Design philosophy is explained
- Intended usage patterns are defined
- Assumptions and limitations are made explicit
Implementation details are documented only when necessary. The focus is on how the library is intended to be used correctly and safely, not on how it happens to be implemented at a particular point in time.
In short:
Doxygen explains the design and intent; implementations merely realize it.
For the best experience when browsing the source code together with Doxygen documentation, CLion is strongly recommended.
This recommendation is based on the fact that classic CLion can correctly render standard Doxygen comments
(HTML-tags style) and seamlessly integrate them into source code navigation.
Specifically:
- Doxygen comments written in standard HTML-style tags are properly rendered inline in the editor.
- Hover tooltips display fully rendered, highly readable Doxygen documentation, rather than plain text.
- This greatly improves readability when inspecting type definitions, APIs, and implementation philosophies.
All Doxygen comments in our codebase are written using standard Doxygen (HTML-tags style), as this format is significantly more expressive and helpful for understanding definitions and semantics.
- A non-commercial license is sufficient.
- CLion has been verified to work correctly up to version 2025.3.2.
- Please use version 2025.3.2 or earlier.
- Newer versions are not guaranteed to work as expected.
Please do not use CLion Nova.
In recent CLion releases, CLion Nova has been merged into the main CLion IDE and is enabled by default. This can negatively affect source code indexing and Doxygen navigation.
CLion Nova is not recommended because it only supports a JetBrains-specific documentation rendering format, which:
- Uses a Markdown-like / JavaDoc-style syntax instead of standard Doxygen HTML tags
- Does not fully support native Doxygen tags
- Cannot correctly render parts of our existing Doxygen documentation
As a result, using Nova leads to degraded documentation rendering and a poorer code-reading experience.
To disable the Nova engine, follow these steps:
- Open Settings
- Go to Advanced Settings
- Navigate to CLion
- Locate the option:
- Use ReSharper C++ language engine (CLion Nova)
- Uncheck this option
- Restart the IDE
After restarting, CLion will use the classic C++ engine, which provides a more stable and accurate code + Doxygen reading experience.
JH Toolkit is not designed solely for final production code.
A portion of its components are intentionally built to empower early-stage prototyping, lowering cognitive load while guiding users toward correct and scalable designs.
For example, some utilities (such as jh::conc::occ_box) are explicitly aimed at prototype-driven development.
They preserve generality while exposing complete compare-and-swap (CAS) reasoning models, encouraging users to write
logically sound concurrency code from the start.
The goal is not to lock users into these abstractions, but to make it easier to later migrate toward project-specific,
optimized implementations with minimal redesign cost.
In contrast, other components—such as jh::ordered_map and jh::ipc—are shaped by engineering constraints rather
than maximal generality.
Compared to STL or Boost equivalents, these modules intentionally reduce language-level freedom ("I want to do this, I
want to do that") in favor of operational stability ("this is what we repeatedly do in real systems, and it must be
reliable").
The jh::ipc module follows a similar philosophy:
it treats POSIX semantics as the final deployment target, while still allowing Windows-based prototyping and early
modeling.
This enables cross-platform experimentation without obscuring the actual production execution model.
The jh::concepts module—especially the sequence concept and iterator-related duck-typing—focuses on adapting
third-party or non-standard containers.
Its purpose is to elevate such types to valid std::ranges::range participants, unlocking modern range-based algorithms
without forcing invasive rewrites.
The jh::pod module supports early modeling and legacy code migration toward C++20 by enforcing a strict separation
between:
- semantic objects (behavior, invariants, logic)
- semantic data (plain, transportable, inspectable state)
This separation is crucial for long-term maintainability and safe system evolution.
Across modules such as jh::async, jh::meta, and jh::ipc, the toolkit also provides philosophical engineering
guidance.
APIs are shaped to encourage patterns that scale better in real systems, nudging users toward more disciplined and
production-oriented practices.
In summary, JH Toolkit is an engineering-first toolkit. It is oriented toward practice rather than language experimentation, with the explicit goal of helping C++ developers:
- internalize engineering-oriented thinking,
- adopt modern C++20 idioms naturally,
- and reduce the friction of moving from prototypes to robust systems.
The library is not about showing what modern C++ can do—it is about helping engineers do what they need to do, correctly and sustainably.
JH Toolkit brings Pythonic expressiveness and clarity into modern C++20 design.
- Duck Typing: Behavior matters more than declarations.
- Lazy Evaluation: Compute only when necessary.
- Automatic Memory Management: Resources manage themselves.
- Explicit is Better Than Implicit: Clarity prevents unintended behavior.
- Readability and Maintainability: Readable code lasts longer.
Aligns with std to provide a seamless and natural C++ toolkit experience.
Developed by JeongHan-Bae
📧 [email protected]
🔗 GitHub Profile
📜 License
This project is licensed under the Apache 2.0 License.
See the license text at the link above for full details.
Contributions are welcome!
Please refer to the contribution guidelines linked above before opening issues or pull requests.
🚀 Enjoy coding with jh-toolkit!