Harden Chronicle Threads docs and runtime introspection; enable section numbering and add loop introspection tests

AGENTS.md

@@ -8,23 +8,23 @@ LLM-based agents can accelerate development only if they respect our house rules
 
 ## Language & character-set policy
 
-| Requirement  | Rationale |
-|--------------|-----------|
-| **British English** spelling (`organisation`, `licence`, *not* `organization`, `license`) except technical US spellings like `synchronized` | Keeps wording consistent with Chronicle's London HQ and existing docs. See the University of Oxford style guide for reference. |
-| **ASCII-7 only** (code-points 0-127). Avoid smart quotes, non-breaking spaces and accented characters. | ASCII-7 survives every toolchain Chronicle uses, incl. low-latency binary wire formats that expect the 8th bit to be 0. |
-| If a symbol is not available in ASCII-7, use a textual form such as `micro-second`, `>=`, `:alpha:`, `:yes:`. This is the preferred approach and Unicode must not be inserted. | Extended or '8-bit ASCII' variants are *not* portable and are therefore disallowed. |
+| Requirement                                                                                                                                                                    | Rationale                                                                                                                      |
+|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|
+| **British English** spelling (`organisation`, `licence`, *not* `organization`, `license`) except technical US spellings like `synchronized`                                    | Keeps wording consistent with Chronicle's London HQ and existing docs. See the University of Oxford style guide for reference. |
+| **ISO-8859-1** (code-points 0-255). Avoid smart quotes, non-breaking spaces and accented characters.                                                                         | ISO-8859-1 survives every toolchain Chronicle uses, incl. low-latency binary wire formats that expect the 8th bit to be 0.        |
+| If a symbol is not available in ISO-8859-1, use a textual form such as `micro-second`, `>=`, `:alpha:`, `:yes:`. This is the preferred approach and Unicode must not be inserted. | Extended or '8-bit ASCII' variants are *not* portable and are therefore disallowed.                                            |
 
 ## Javadoc guidelines
 
 **Goal:** Every Javadoc block should add information you cannot glean from the method signature alone. Anything else is
 noise and slows readers down.
 
-| Do | Don't |
-|----|-------|
-| State *behavioural contracts*, edge-cases, thread-safety guarantees, units, performance characteristics and checked exceptions. | Restate the obvious ("Gets the value", "Sets the name"). |
-| Keep the first sentence short; it becomes the summary line in aggregated docs. | Duplicate parameter names/ types unless more explanation is needed. |
-| Prefer `@param` for *constraints* and `@throws` for *conditions*, following Oracle's style guide. | Pad comments to reach a line-length target. |
-| Remove or rewrite autogenerated Javadoc for trivial getters/setters. | Leave stale comments that now contradict the code. |
+| Do                                                                                                                              | Don't                                                               |
+|---------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
+| State *behavioural contracts*, edge-cases, thread-safety guarantees, units, performance characteristics and checked exceptions. | Restate the obvious ("Gets the value", "Sets the name").            |
+| Keep the first sentence short; it becomes the summary line in aggregated docs.                                                  | Duplicate parameter names/ types unless more explanation is needed. |
+| Prefer `@param` for *constraints* and `@throws` for *conditions*, following Oracle's style guide.                               | Pad comments to reach a line-length target.                         |
+| Remove or rewrite autogenerated Javadoc for trivial getters/setters.                                                            | Leave stale comments that now contradict the code.                  |
 
 The principle that Javadoc should only explain what is *not* manifest from the signature is well-established in the
 wider Java community.
@@ -55,12 +55,13 @@ mvn -q verify
 
 ## Project requirements
 
-See the [Decision Log](src/main/adoc/decision-log.adoc) for the latest project decisions.
-See the [Project Requirements](src/main/adoc/project-requirements.adoc) for details on project requirements.
+See the [Decision Log](src/main/docs/decision-log.adoc) for the latest project decisions.
+See the [Project Requirements](src/main/docs/project-requirements.adoc) for details on project requirements.
 
 ## Elevating the Workflow with Real-Time Documentation
 
-Building upon our existing Iterative Workflow, the newest recommendation is to emphasise *real-time updates* to documentation.
+Building upon our existing Iterative Workflow, the newest recommendation is to emphasise *real-time updates* to
+documentation.
 Ensure the relevant `.adoc` files are updated when features, requirements, implementation details, or tests change.
 This tight loop informs the AI accurately and creates immediate clarity for all team members.
 
@@ -75,41 +76,54 @@ This tight loop informs the AI accurately and creates immediate clarity for all
 
 ### Best Practices
 
-* **Maintain Sync**: Keep documentation (AsciiDoc), tests, and code synchronised in version control. Changes in one area should prompt reviews and potential updates in the others.
-* **Doc-First for New Work**: For *new* features or requirements, aim to update documentation first, then use AI to help produce or refine corresponding code and tests. For refactoring or initial bootstrapping, updates might flow from code/tests back to documentation, which should then be reviewed and finalised.
-* **Small Commits**: Each commit should ideally relate to a single requirement or coherent change, making reviews easier for humans and AI analysis tools.
-- **Team Buy-In**: Encourage everyone to review AI outputs critically and contribute to maintaining the synchronicity of all artefacts.
+* **Maintain Sync**: Keep documentation (AsciiDoc), tests, and code synchronised in version control. Changes in one area
+  should prompt reviews and potential updates in the others.
+* **Doc-First for New Work**: For *new* features or requirements, aim to update documentation first, then use AI to help
+  produce or refine corresponding code and tests. For refactoring or initial bootstrapping, updates might flow from
+  code/tests back to documentation, which should then be reviewed and finalised.
+* **Small Commits**: Each commit should ideally relate to a single requirement or coherent change, making reviews easier
+  for humans and AI analysis tools.
+
+- **Team Buy-In**: Encourage everyone to review AI outputs critically and contribute to maintaining the synchronicity of
+  all artefacts.
 
 ## AI Agent Guidelines
 
 When using AI agents to assist with development, please adhere to the following guidelines:
 
-* **Respect the Language & Character-set Policy**: Ensure all AI-generated content follows the British English and ASCII-7 guidelines outlined above.
-Focus on Clarity: AI-generated documentation should be clear and concise and add value beyond what is already present in the code or existing documentation.
-* **Avoid Redundancy**: Do not generate content that duplicates existing documentation or code comments unless it provides additional context or clarification.
-* **Review AI Outputs**: Always review AI-generated content for accuracy, relevance, and adherence to the project's documentation standards before committing it to the repository.
+* **Respect the Language & Character-set Policy**: Ensure all AI-generated content follows the British English and
+  ISO-8859-1 guidelines outlined above.
+  Focus on Clarity: AI-generated documentation should be clear and concise and add value beyond what is already present
+  in the code or existing documentation.
+* **Avoid Redundancy**: Do not generate content that duplicates existing documentation or code comments unless it
+  provides additional context or clarification.
+* **Review AI Outputs**: Always review AI-generated content for accuracy, relevance, and adherence to the project's
+  documentation standards before committing it to the repository.
 
 ## Company-Wide Tagging
 
-This section records **company-wide** decisions that apply to *all* Chronicle projects. All identifiers use the <Scope>-<Tag>-xxx prefix. The `xxx` are unique across in the same Scope even if the tags are different. Component-specific decisions live in their xxx-decision-log.adoc files.
+This section records **company-wide** decisions that apply to *all* Chronicle projects. All identifiers use
+the <Scope>-<Tag>-xxx prefix. The `xxx` are unique across in the same Scope even if the tags are different.
+Component-specific decisions live in their xxx-decision-log.adoc files.
 
 ### Tag Taxonomy (Nine-Box Framework)
 
-To improve traceability, we adopt the Nine-Box taxonomy for requirement and decision identifiers. These tags are used in addition to the existing ALL prefix, which remains reserved for global decisions across every project.
+To improve traceability, we adopt the Nine-Box taxonomy for requirement and decision identifiers. These tags are used in
+addition to the existing ALL prefix, which remains reserved for global decisions across every project.
 
 .Adopt a Nine-Box Requirement Taxonomy
 
-|Tag | Scope | Typical examples |
-|----|-------|------------------|
-|FN |Functional user-visible behaviour | Message routing, business rules |
-|NF-P |Non-functional - Performance | Latency budgets, throughput targets |
-|NF-S |Non-functional - Security | Authentication method, TLS version |
-|NF-O |Non-functional - Operability | Logging, monitoring, health checks |
-|TEST |Test / QA obligations | Chaos scenarios, benchmarking rigs |
-|DOC |Documentation obligations | Sequence diagrams, user guides |
-|OPS |Operational / DevOps concerns | Helm values, deployment checklist |
-|UX |Operator or end-user experience | CLI ergonomics, dashboard layouts |
-|RISK |Compliance / risk controls | GDPR retention, audit trail |
+| Tag  | Scope                             | Typical examples                    |
+|------|-----------------------------------|-------------------------------------|
+| FN   | Functional user-visible behaviour | Message routing, business rules     |
+| NF-P | Non-functional - Performance      | Latency budgets, throughput targets |
+| NF-S | Non-functional - Security         | Authentication method, TLS version  |
+| NF-O | Non-functional - Operability      | Logging, monitoring, health checks  |
+| TEST | Test / QA obligations             | Chaos scenarios, benchmarking rigs  |
+| DOC  | Documentation obligations         | Sequence diagrams, user guides      |
+| OPS  | Operational / DevOps concerns     | Helm values, deployment checklist   |
+| UX   | Operator or end-user experience   | CLI ergonomics, dashboard layouts   |
+| RISK | Compliance / risk controls        | GDPR retention, audit trail         |
 
 `ALL-*` stays global, case-exact tags. Pick one primary tag if multiple apply.
 

LICENSE.adoc

@@ -1,14 +1,9 @@
-
 == Copyright 2016-2025 chronicle.software
 
-Licensed under the *Apache License, Version 2.0* (the "License");
-you may not use this file except in compliance with the License.
+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.
+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.

README.adoc

@@ -20,8 +20,7 @@ toc::[]
 This library provides high performance event loop implementations and utility functions to help with threading and concurrency.
 
 Concurrency is _hard_, and event loops provide an abstraction to make dealing with concurrency easier.
-Context switching between threads is expensive and best practice in a low latency system is to keep your latency-sensitive operations executing on a small number of "fast" threads
-and the event loop abstraction fits well with this approach.
+Context switching between threads is expensive and best practice in a low latency system is to keep your latency-sensitive operations executing on a small number of "fast" threads and the event loop abstraction fits well with this approach.
 
 For best latency these fast threads will be busy-spinning i.e. consuming a whole core, and the core running the fast thread is isolated from the OS and other applications.
 
@@ -35,18 +34,16 @@ This library contains a number of event loop implementations and additional feat
 == Event Handlers and Event Loops
 
 An event loop can have multiple event handlers installed on it and the event loop will repeatedly execute these event handlers.
-Each event handler is guaranteed to be called on only one thread. Event handlers are expected to perform a chunk of work
-quickly and return without blocking, although the <<Event Loops,EventGroup>> does provide a mechanism to support blocking
-event handlers - see
+Each event handler is guaranteed to be called on only one thread.
+Event handlers are expected to perform a chunk of work quickly and return without blocking, although the <<Event Loops,EventGroup>> does provide a mechanism to support blocking event handlers - see
 link:https://github.com/OpenHFT/Chronicle-Core/blob/ea/src/main/java/net/openhft/chronicle/core/threads/HandlerPriority.java[`HandlerPriority`].
 
 See
 link:https://github.com/OpenHFT/Chronicle-Core/blob/ea/src/main/java/net/openhft/chronicle/core/threads/EventLoop.java[`EventLoop`]
 and
 link:https://github.com/OpenHFT/Chronicle-Core/blob/ea/src/main/java/net/openhft/chronicle/core/threads/EventHandler.java[`EventHandler`].
 
-Figure 1
-illustrates a diagram of an event loop that serves several event handlers sequentially.
+Figure 1 illustrates a diagram of an event loop that serves several event handlers sequentially.
 
 [#img-eventloop]
 .Event Loop and Event Handlers
@@ -57,10 +54,9 @@ image::docs/images/EventLoop.png[1000,600]
 In this section we explore common event handler use cases
 
 ==== Implement event handler
+
 An event handler can be created by implementing the `EventHandler` interface and overriding its `action()` method so that it executes the required work.
-The `action()` method returns a boolean value signifying whether some work was done by the `action()` - an
-example is an event handler that tries to poll from a Chronicle Queue - the return value of the `action()` should
-indicate if the read succeeded and a message was processed.
+The `action()` method returns a boolean value signifying whether some work was done by the `action()` - an example is an event handler that tries to poll from a Chronicle Queue - the return value of the `action()` should indicate if the read succeeded and a message was processed.
 
 NOTE: The event loop considers this return value by using a heuristic: if the `action()` did some work, it is likely to do some more work next time, and so we should call it again as soon as we can.
 If it did not do some work, it is less likely to do work next time, so it may appropriate to yield or pause before calling again - see <<Pausers>>.
@@ -80,6 +76,7 @@ public final class ExampleEventHandler implements EventHandler {
 ----
 
 ==== Adding to event loop
+
 call the `addHandler` method of the event loop, see also <<Start event loop>>
 
 [source,java]
@@ -88,8 +85,8 @@ el.addHandler(eh0);
 ----
 
 ==== Removing an event handler from an eventLoop
-When an event handler wants to remove itself
-from the event loop, its `action()` method should throw `InvalidEventHandlerException`.
+
+When an event handler wants to remove itself from the event loop, its `action()` method should throw `InvalidEventHandlerException`.
 The `InvalidEventHandlerException.reusable()` method returns a reusable, pre-created, `InvalidEventHandlerException` that is unmodifiable and contains no stack trace.
 The below event handler uninstalls itself after being called 30 times.
 
@@ -115,6 +112,7 @@ These are aggregated together in the link:src/main/java/net/openhft/chronicle/th
 The `EventGroup` also automatically enables <<Performance Monitoring>>..
 
 ==== Creating event loop
+
 event group is created by calling the using the
 link:src/main/java/net/openhft/chronicle/threads/EventGroupBuilder.java[`EventGroupBuilder`].
 Basic example shown below:
@@ -162,8 +160,7 @@ The second use of `HandlerPriority` is to enable each (child) event loop to dete
 Chronicle Threads provides a number of implementations of the
 link:src/main/java/net/openhft/chronicle/threads/Pauser.java[`Pauser`]
 and it is straightforward for the user to implement their own if need be.
-The `Pauser` allows the developer to choose an appropriate trade-off between latency vs CPU consumption for when
-an `EventLoop` is running events which exhibit "bursty" behaviour.
+The `Pauser` allows the developer to choose an appropriate trade-off between latency vs CPU consumption for when an `EventLoop` is running events which exhibit "bursty" behaviour.
 
 The recommended way to use `Pauser` - and this is how Chronicle Thread's event loop implementations use it:
 
@@ -184,13 +181,10 @@ The `Pauser` implementation can choose to yield, pause (with back off if require
 
 In the context of the heuristic in <<Implement event handler>> above - if an
 `EventHandler` does no work, then it may well not need to do any work for a while, as events often occur in bursts in the real world.
-In this case it makes sense for the `Pauser` to keep track of how many times
-it has been called, and progressively implement longer pauses every time its `pause()` is called.
-This behaviour allows a back off pauser to strike a reasonable balance between handling bursts of events quickly,
-but backing off and reducing CPU consumption in case of gap in incoming events.
+In this case it makes sense for the `Pauser` to keep track of how many times it has been called, and progressively implement longer pauses every time its `pause()` is called.
+This behaviour allows a back off pauser to strike a reasonable balance between handling bursts of events quickly, but backing off and reducing CPU consumption in case of gap in incoming events.
 
-A good example of a back off `Pauser` is the `LongPauser` which will busy-loop for `minBusy` events (allowing the event loop to respond
-quickly if a new event arrives immediately), then will yield for `minCount` times before it sleeping for `minTime` increasing up to `maxTime`.
+A good example of a back off `Pauser` is the `LongPauser` which will busy-loop for `minBusy` events (allowing the event loop to respond quickly if a new event arrives immediately), then will yield for `minCount` times before it sleeping for `minTime` increasing up to `maxTime`.
 
 === TimingPauser