JH Toolkit

A Modern, Duck-Typed C++20 Toolkit for Generic and Asynchronous Programming — Featuring Concurrency-Safe Infrastructure, POD Subsystems, Concept-Bridged Type Compatibility, and Extended Range Utilities — Fully Template-Driven and RTTI-Free.

---

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.

---

🧰 Build & Platform Guide

For detailed build instructions, supported compilers, and Conan packaging notes,
please refer to the Build & Platform Guide.

Covers: toolchains, CMake targets, Conan .tar.gz releases, and dual-mode headers.

---

📚 JH Toolkit Modules Overview

---

🧩 Conceptual & Ranges-Views System — Duck Typing Philosophy

The jh::concepts & jh::views system embodies JH Toolkit's duck typing philosophy — if a type behaves like a sequence, it is treated as one. This system generalizes iteration and range utilities through behavior rather than inheritance, bridging standard and non-standard containers seamlessly.

jh::concepts defines JH Toolkit's duck-typing model for iteration, recognizing behavioral compatibility rather than formal inheritance.

Any type that supports range-for iteration — readable or writable — and preserves its state across iterations is treated as a duck sequence. jh::concepts::iterator and jh::concepts::sequence together enable jh::to_range(), which transparently proxies such types into a standard-like range view.

jh::views provides lazy, allocation-free adapters that extend this model. jh::views::zip and jh::views::enumerate operate on duck sequences through jh::to_range(), built upon jh::ranges::zip_view, a C++20 implementation mirroring C++23's std::ranges::zip_view when available.

In all 1.3.x releases, jh::concepts are globally down-leveled to jh::* for backward compatibility, while jh::views::* remains the canonical interface, following the same convention as the C++ standard library (std::views::*).

---

🌀 Async System — Cooperative Concurrency, True Parallelism

jh::async — Unified Asynchronous Semantics

jh::async defines the asynchronous behavior model of JH Toolkit. It provides coroutine-based lazy evaluation through jh::async::generator, a deferred state machine that models computation rather than storage. Generators are consumable, representing one logical evaluation path per lifetime, and are exposed under both jh::generator and jh::async::generator for convenience.

The upcoming 1.4.x series extends jh::async with other concurrency primitives:

• occ_box for optimistic transactional control
• process_mutex for timed interprocess synchronization
• process_launcher for isolated, parallel process execution

Concurrency in JH Toolkit is defined by behavior, not class hierarchy — every asynchronous primitive follows explicit lifetime and deterministic semantics.

---

🧊 POD System — Plain Old Data, Modern Discipline

jh::pod defines a layout-stable, trivially copyable type system for C++20. It provides a suite of fixed-layout value primitives — like pod::pair, pod::array, pod::optional, and pod::bitflags — built for raw memory safety, placement-new, and binary serialization.

All pod types are:

• 🧩 memcpy-safe, trivially copyable, and standard-layout
• 🧱 Designed for mmap, arena, and zero-overhead serialization
• ⚙️ Usable inside STL containers with no hidden heap or lifetime coupling

*_view and span<T> types are non-owning references — they borrow external memory and must not outlive their backing buffers or mapped regions. They are designed for inspection, slicing, and serialization, not ownership or mutation.

jh::pod also introduces lightweight tools for structure definition and validation:

• JH_POD_STRUCT(...) — define POD structs with compile-time layout checks
• JH_ASSERT_POD_LIKE(T) — enforce POD compliance on existing types

Together they form a foundation for safe binary data modeling — bridging high-level C++ templates with low-level, deterministic memory control.

✅ 64-bit only, fully constexpr, header-only, and STL-compatible. Designed for predictable layout, not legacy C-style "plain structs."

---

🧱 Core System — Immutable, Pooled, Runtime-Stable

The Core System (immutable_str, runtime_arr, sim_pool) provides stable storage, safe sharing, and deterministic ownership across threads.

• jh::immutable_str — a fully immutable string, managed via smart pointers. Objects are never moved or modified; only their handles (unique_ptr / shared_ptr) are replaceable.

• jh::runtime_arr<T> — a mutable buffer container, uniquely owned or shared through smart pointers. Specialized precompiled variants (bit-packed and byte-based) ensure layout stability and performance.

• jh::sim_pool<T> — a Smart Immutable-objects Managing Pool, acting as a non-owning observer and redistributor. It tracks objects via weak references, allowing automatic reuse without owning lifetimes. The lightweight jh::pool<T> is its duck-type counterpart.

🧩 Identical API for both header-only and static-build modes — same code, different linkage (jh::jh-toolkit / jh::jh-toolkit-static).

📦 Located under jh::* and <jh/*> — STL-compatible, ABI-stable, and designed for concurrent environments.

---

🔗 Quick Links to Module Docs

🧩 Project Structure

Click to expand ▶️ / collapse 🔽

include/jh/
    ├── asynchronous           # jh::async
    │   ├── generator.h        # jh::async::generator
    │   └── ...                # future 1.4.x jh::async submodules
    ├── conceptual             # jh::concepts
    │   ├── iterator.h         # jh::concepts::iterator
    │   └── sequence.h         # jh::concepts::sequence
    ├── macros                 # jh::macros
    │   ├── header_begin.h     # dual-mode header basic
    │   ├── header_end.h       # dual-mode header basic
    │   ├── platform.h         # macro defined platform detection
    │   └── type_name.h        # jh::macros::type_name
    ├── pods                   # jh::pod
    │   ├── ...                # array, bits, bytes_view, optional, pair, pod_like, span, string_view
    │   ├── stringify.h        # visualize jh::pod debugging output
    │   └── tools.h            # supporting macros for jh::pod
    ├── ranges                 # jh::ranges bases
    │   ├── views              # jh::views
    │   │   ├── enumerate.h    # jh::views::enumerate based on zip
    │   │   └── zip.h          # jh::views::zip based on zip_view
    │   ├── range_wrapper.h    # jh::to_range base
    │   └── zip_view.h         # jh::ranges::zip_view mimic C++23
    ├── utils                  # jh::utils
    │   ├── ...                # jh::utils::base64, hash_fn
    │   ├── platform.h         # 1.3.x temporary alias for jh/macros/platform.h
    │   └── typed.h            # jh::typed::monostate
    ├── generator              # forwarding header for jh::generator
    ├── immutable_str          # forwarding header for jh::immutable_str
    ├── immutable_str.h        # jh::immutable_str
    ├── iterator               # 1.3.x temporary forwarding header for jh::iterator
    ├── pod                    # forwarding header for jh::pod
    ├── pod.h                  # aggregate header for jh::pod
    ├── pool                   # forwarding header for jh::pool
    ├── pool.h                 # jh::pool, duck typed jh::sim_pool
    ├── runtime_arr            # forwarding header for jh::runtime_arr
    ├── runtime_arr.h          # jh::runtime_arr
    ├── sequence               # 1.3.x temporary forwarding header for jh::sequence
    ├── sim_pool               # forwarding header for jh::sim_pool
    ├── sim_pool.h             # jh::sim_pool
    ├── views                  # forwarding header for jh::views
    └── views.h                # 1.3.x temporary aggregate header for jh::views

Documentation Navigation

Click to expand ▶️ / collapse 🔽

• asynchronous/ — jh::async
  • generator.h — jh::async::generator
  • ... — future 1.4.x jh::async submodules
• conceptual/ — jh::concepts
  • iterator.h — jh::concepts::iterator
  • sequence.h — jh::concepts::sequence
• macros/ — jh::macros
  • header_begin.h — dual-mode header basic
  • header_end.h — dual-mode header basic
  • platform.h — macro-defined platform detection
  • type_name.h — jh::macros::type_name
• pods/ — jh::pod
  • ... — array, bits, bytes_view, optional, pair, pod_like, span, string_view
  • stringify.h — visualize jh::pod debugging output
  • tools.h — supporting macros for jh::pod
• ranges/ — jh::ranges bases
  • views/ — jh::views
    • enumerate.h — jh::views::enumerate
    • zip.h — jh::views::zip
  • range_wrapper.h — jh::to_range base
  • zip_view.h — jh::ranges::zip_view
• utils/ — jh::utils
  • ... — jh::utils::base64, jh::utils::hash_fn
  • platform.h — alias for jh/macros/platform.h
  • typed.h — jh::typed::monostate
• generator — forwarding header for jh::generator
• immutable_str — forwarding header for jh::immutable_str
• immutable_str.h — jh::immutable_str
• iterator — temporary forwarding header for jh::iterator
• pod — forwarding header for jh::pod
• pod.h — aggregate header for jh::pod
• pool — forwarding header for jh::pool
• pool.h — jh::pool, duck-typed jh::sim_pool
• runtime_arr — forwarding header for jh::runtime_arr
• runtime_arr.h — jh::runtime_arr
• sequence — temporary forwarding header for jh::sequence
• sim_pool — forwarding header for jh::sim_pool
• sim_pool.h — jh::sim_pool
• views — forwarding header for jh::views
• views.h — temporary aggregate header for jh::views

---

Pythonic Aesthetics and Philosophy in JH Toolkit

JH Toolkit brings Pythonic expressiveness and clarity into modern C++20 design.

1. Duck Typing: Behavior matters more than declarations.
2. Lazy Evaluation: Compute only when necessary.
3. Automatic Memory Management: Resources manage themselves.
4. Explicit is Better Than Implicit: Clarity prevents unintended behavior.
5. Readability and Maintainability: Readable code lasts longer.

Why snake_case?

Aligns with std to provide a seamless and natural C++ toolkit experience.

---

👤 Author

Developed by JeongHan-Bae
📧 mastropseudo@gmail.com
🔗 GitHub Profile

📜 License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Feel free to open issues and pull requests to enhance the library.

---

🚀 Enjoy coding with jh-toolkit!