From dda0fc7cac55968da89d503d61b4a86f5c972c55 Mon Sep 17 00:00:00 2001 From: LimiNode <20008174+LimiNode@users.noreply.github.com> Date: Thu, 12 Nov 2026 15:03:17 +0300 Subject: [PATCH 1/3] docs(architecture): define atomic configuration registration Document the ownership, publication, identity, and compatibility contract for registering prepared configuration batches into Logger. Keep implementation, hot reload, parsing, and file loading outside this design slice. --- .../0010-atomic-configuration-registration.md | 115 ++++++++++++++++++ docs/adr/README.md | 1 + docs/future-plans.md | 6 +- 3 files changed, 120 insertions(+), 2 deletions(-) create mode 100644 docs/adr/0010-atomic-configuration-registration.md diff --git a/docs/adr/0010-atomic-configuration-registration.md b/docs/adr/0010-atomic-configuration-registration.md new file mode 100644 index 0000000..0ec5633 --- /dev/null +++ b/docs/adr/0010-atomic-configuration-registration.md @@ -0,0 +1,115 @@ +# ADR 0010: Atomic registration of prepared configuration batches + +- Status: Proposed +- Date: 2026-11-12 + +## Context + +`prepare_configuration()` produces a complete `ConfigurationPreparedSet`. +Each entry owns an `ILogger` and an `ILogFormatter` through `std::shared_ptr`, +because factories may share those objects and the prepared result is copyable. +The live `Logger` registry currently stores each pair in `LoggerStrategy` as +`std::unique_ptr` and exposes `add_logger()` for one-at-a-time registration. + +Converting a shared pointer to a unique pointer through `get()` would create +double ownership or dangling references. Registering entries one by one would +also publish a partially applied configuration if a later entry is invalid. +The existing copy-on-write strategy snapshot and shutdown checks must remain +the publication boundary for concurrent dispatch. + +## Decision + +Add a separate configuration-registration layer; do not change parsing, +binding resolution, or the existing `Logger::add_logger()` call contract in +this slice. + +The future registration operation will accept a complete prepared set and an +explicit registration-options object. It will: + +1. validate the entire batch before publication; +2. build all new strategies and registration metadata while holding the + registry write lock (or before taking it when no live state is inspected); +3. check `m_shutdown` before preparation and again before publication; +4. publish one immutable strategy-list snapshot with one release-store; +5. return a stable mapping from each configuration `id` to its runtime index. + +The operation is append-only in v1. Existing strategies are preserved. New +configuration entries use `single_mode=false` unless an explicit per-entry +registration option says otherwise. The operation rejects duplicate IDs in the +incoming batch and IDs already registered by this configuration-registration +layer. Legacy `add_logger()` entries have no configuration ID and do not +silently acquire one. Repeated registration is therefore an explicit append +operation, not replacement or hot reload; callers that need replacement must +use a separately designed API. + +The runtime index of an appended entry is its position in the published +registry after the existing strategies. The returned ID/index mapping is the +only supported way for a configuration caller to address a logger; vector +order and backend type are not inferred from the ID. + +### Ownership boundary + +The recommended implementation changes `LoggerStrategy`'s internal owners to +`std::shared_ptr`. The unchanged public `add_logger(std::unique_ptr<...>)` API +will wrap each incoming unique pointer in a shared pointer internally. The new +batch operation can then share the prepared logger and formatter without raw +pointer conversion or an ownership transfer that invalidates the prepared +set. Existing dispatch, per-strategy execution locking, and snapshot lifetime +rules remain unchanged. + +The prepared set remains caller-owned after successful registration. Clearing +or destroying it must not invalidate the live registry. A failed registration +must leave both the caller's prepared set and the live registry unchanged. + +### Atomicity and side effects + +Atomicity covers caller-visible registry publication only. The prepared set is +already materialized, so registration must not invoke factories, resolve +bindings, parse input, or start a backend-specific lifecycle outside the +normal logger construction contract. Backend shutdown remains governed by the +existing `Logger::shutdown()` and strategy lifetime rules. + +## Consequences + +- Configuration batches become visible to dispatch all at once. +- Existing applications retain the unique-pointer `add_logger()` API. +- Shared ownership removes unsafe pointer conversion and allows prepared-set + copies without changing logger lifetime semantics. +- The internal `LoggerStrategy` owner type changes, so implementation work must + cover shutdown, snapshots, `wait()`, clear/read APIs, targeted indices, and + concurrent dispatch on both C++11 and C++17. +- Registration does not provide replacement, rollback of external backend + effects, file watching, or hot reload. +- Configuration IDs require a small registry-side metadata map; they are not + retrofitted onto legacy unnamed registrations. + +## Alternatives considered + +### Move prepared pointers into `unique_ptr` + +Rejected. It would make `ConfigurationPreparedSet` move-only, break the +existing factory/shared-ownership contract, and make failed publication harder +to preserve safely. + +### Convert `shared_ptr` through `get()` + +Rejected. Constructing a `unique_ptr` from that raw pointer would either cause +double deletion or require a non-owning deleter, leaving lifetime dependent on +the prepared set. + +### Register each entry with the existing `add_logger()` + +Rejected for a configuration batch. It exposes partial state and cannot return +one atomic publication point or an unambiguous batch ID/index mapping. + +### Replace the registry wholesale on every configuration load + +Deferred. Replacement needs explicit semantics for in-flight records, +shutdown, ID collisions, and rollback. It is not implicit hot reload. + +## References + +- [Configuration runtime preparation](../configuration-loading.md) +- [ADR 0003: Immutable logger registry snapshots](0003-immutable-registry-snapshots.md) +- [Logger registry implementation](../../include/logit_cpp/logit/Logger.hpp) +- [Prepared runtime types](../../include/logit_cpp/logit/configuration_runtime.hpp) diff --git a/docs/adr/README.md b/docs/adr/README.md index fc0b246..ef1cec2 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -35,3 +35,4 @@ explains **why the current boundary or trade-off exists**. ## Proposed decisions - [0009 — Versioned configuration loading contract](0009-configuration-loading-contract.md) +- [0010 — Atomic registration of prepared configuration batches](0010-atomic-configuration-registration.md) diff --git a/docs/future-plans.md b/docs/future-plans.md index 3d8d6a3..7219b9b 100644 --- a/docs/future-plans.md +++ b/docs/future-plans.md @@ -53,8 +53,10 @@ Legend: the existing backend configuration. The proposed contract is recorded in [ADR 0009](adr/0009-configuration-loading-contract.md). The parser-neutral model, built-in materialization/runtime layers, and optional JSON text/value - frontend are delivered; file-loading convenience and a properties frontend - remain follow-ups. File watching/hot reload is not part of this API. + frontend are delivered; atomic registration is specified separately in + [ADR 0010](adr/0010-atomic-configuration-registration.md), while + file-loading convenience and a properties frontend remain follow-ups. File + watching/hot reload is not part of this API. - [ ] **Extended filtering** — evaluate source/file, message, tag/MDC, and range filters; define their cost and ordering before adding public API. - [x] **Benchmark follow-up** — formatted and passthrough public-macro scenarios, From df6eac23ac77b563d5d4a3b705236f7940d42115 Mon Sep 17 00:00:00 2001 From: LimiNode <20008174+LimiNode@users.noreply.github.com> Date: Thu, 12 Nov 2026 15:04:23 +0300 Subject: [PATCH 2/3] docs(architecture): specify registration race and failure tests Define the non-throwing publication sequence, shutdown linearization and regression matrix required before implementation of atomic configuration registration. --- .../0010-atomic-configuration-registration.md | 37 +++++++++++++++++-- 1 file changed, 34 insertions(+), 3 deletions(-) diff --git a/docs/adr/0010-atomic-configuration-registration.md b/docs/adr/0010-atomic-configuration-registration.md index 0ec5633..6a34784 100644 --- a/docs/adr/0010-atomic-configuration-registration.md +++ b/docs/adr/0010-atomic-configuration-registration.md @@ -27,9 +27,10 @@ The future registration operation will accept a complete prepared set and an explicit registration-options object. It will: 1. validate the entire batch before publication; -2. build all new strategies and registration metadata while holding the - registry write lock (or before taking it when no live state is inspected); -3. check `m_shutdown` before preparation and again before publication; +2. build all new strategies and candidate registry/ID-map snapshots before + mutating live state; +3. check `m_shutdown` before preparation and again under the registry write + lock before publication; 4. publish one immutable strategy-list snapshot with one release-store; 5. return a stable mapping from each configuration `id` to its runtime index. @@ -47,6 +48,21 @@ registry after the existing strategies. The returned ID/index mapping is the only supported way for a configuration caller to address a logger; vector order and backend type are not inferred from the ID. +All potentially throwing validation, allocation, strategy construction, and +ID-map work must finish before mutating `m_loggers`. Under its write lock, the +implementation prepares a complete candidate list and immutable snapshot, +then uses non-throwing swaps for the mutable registry and ID map before the +single release-store of the snapshot. No failure may leave the mutable registry +and published snapshot describing different batches. An empty batch is a +successful no-op with an empty returned mapping. + +Shutdown and batch registration must share a linearization boundary. The +future `shutdown()` path must set `m_shutdown` and capture the registry under +the same write lock used by registration. If shutdown wins, registration +fails without publishing. If registration wins, shutdown sees and shuts down +the entire appended batch. The existing fast-path `m_shutdown` check remains +an early exit, not the sole race guard. + ### Ownership boundary The recommended implementation changes `LoggerStrategy`'s internal owners to @@ -83,6 +99,21 @@ existing `Logger::shutdown()` and strategy lifetime rules. - Configuration IDs require a small registry-side metadata map; they are not retrofitted onto legacy unnamed registrations. +## Regression matrix for implementation + +| Case | Required result | +| --- | --- | +| Two-entry batch succeeds | One snapshot publication; both IDs map to consecutive runtime indices after existing strategies. | +| Invalid second entry or duplicate ID | No new strategy or ID is visible; existing registry and caller output remain unchanged. | +| Repeated batch | Duplicate configured IDs fail; no implicit replacement or idempotent success. | +| Legacy `add_logger()` before and after a batch | Existing API remains valid; unnamed indices remain stable and configured ID mapping remains unambiguous. | +| Prepared set destroyed after registration | Backend and formatter remain alive through registry ownership. | +| `single_mode` option and enabled state | Targeted/general routing and default enabled state match ordinary strategy behavior. | +| Concurrent dispatch during registration | Each dispatch sees either the old or complete new snapshot, never a partial batch. | +| Registration versus shutdown | Exactly one wins the registry lock; no published backend escapes shutdown. | +| Factory/formatter failure before registration | No registration call or live mutation occurs. | +| C++11/C++17 and feature-disabled builds | Public `add_logger()` remains source-compatible; registration uses no newer language features or optional parser dependency. | + ## Alternatives considered ### Move prepared pointers into `unique_ptr` From bd3b6f9226cf08d143ae2906db7e63b1f3c87242 Mon Sep 17 00:00:00 2001 From: LimiNode <20008174+LimiNode@users.noreply.github.com> Date: Thu, 12 Nov 2026 15:07:05 +0300 Subject: [PATCH 3/3] docs(architecture): use indexed ADR reference Point the registration contract at an indexed ADR so Doxygen can resolve its reference without adding unrelated documentation inputs. --- docs/adr/0010-atomic-configuration-registration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/0010-atomic-configuration-registration.md b/docs/adr/0010-atomic-configuration-registration.md index 6a34784..92bc224 100644 --- a/docs/adr/0010-atomic-configuration-registration.md +++ b/docs/adr/0010-atomic-configuration-registration.md @@ -140,7 +140,7 @@ shutdown, ID collisions, and rollback. It is not implicit hot reload. ## References -- [Configuration runtime preparation](../configuration-loading.md) +- [ADR 0009: Versioned configuration loading contract](0009-configuration-loading-contract.md) - [ADR 0003: Immutable logger registry snapshots](0003-immutable-registry-snapshots.md) - [Logger registry implementation](../../include/logit_cpp/logit/Logger.hpp) - [Prepared runtime types](../../include/logit_cpp/logit/configuration_runtime.hpp)