diff --git a/docs/api/configured-logger-close.md b/docs/api/configured-logger-close.md index 7517139..c2cf7fb 100644 --- a/docs/api/configured-logger-close.md +++ b/docs/api/configured-logger-close.md @@ -2,8 +2,8 @@ name: configured-logger-close group: api category: runtime -update-time: 20260512 -description: Close the configured runtime logger sink and return whether the underlying sink reported a close action. +update-time: 20260613 +description: Close the configured runtime logger sink and return whether the wrapped RuntimeSink reported a successful close action. key-word: - logger - runtime @@ -13,7 +13,7 @@ key-word: ## Configured-logger-close -Close the sink behind a `ConfiguredLogger`. This helper is the config-driven runtime close surface for queue-backed or file-backed sinks. +Close the sink behind a `ConfiguredLogger`. This helper is the configured logger wrapper over `RuntimeSink::close(...)` for config-driven runtime teardown. ### Interface @@ -27,16 +27,16 @@ pub fn ConfiguredLogger::close(self : ConfiguredLogger) -> Bool {} #### output -- `Bool` - Whether the underlying runtime sink reported a successful close action. +- `Bool` - Whether the wrapped `RuntimeSink::close(...)` call reported a successful close action. ### Explanation Detailed rules explaining key parameters and behaviors -- Queue-backed file sinks close the wrapped file sink. -- Plain file sinks forward directly to file close behavior. -- Console-style sinks usually report `true` because they do not have a meaningful close step. -- This helper delegates to `RuntimeSink::close(...)` through the configured logger wrapper. +- This helper delegates directly to `self.sink.close()`. +- Plain file sinks forward to `FileSink::close()` through `RuntimeSink`. +- Queue-backed file sinks close the wrapped file sink instead of only the queue wrapper. +- Console-style sinks and queue-wrapped console-style sinks return `true` as a no-op success because they do not expose a meaningful close step here. ### How to Use @@ -63,7 +63,7 @@ In this example, callers can branch on the reported close result. ### Error Case e.g.: -- If the runtime sink has no real close action, the helper may still return `true` as a no-op success. +- If the configured runtime sink shape has no real close action, the helper may still return `true` as a no-op success. - If callers need a file-specific close path with queue flush nuances, `file_close()` may be the better API. @@ -71,4 +71,4 @@ e.g.: 1. This is the generic configured runtime close helper. -2. Prefer file-specific helpers when the sink shape is known to be file-backed. +2. Prefer file-specific helpers when the configured sink shape is known to be file-backed. diff --git a/docs/api/configured-logger-drain.md b/docs/api/configured-logger-drain.md index ef64248..2bb8bea 100644 --- a/docs/api/configured-logger-drain.md +++ b/docs/api/configured-logger-drain.md @@ -2,8 +2,8 @@ name: configured-logger-drain group: api category: runtime -update-time: 20260512 -description: Drain queued work from a configured runtime logger with optional item limits. +update-time: 20260613 +description: Drain queued work from a configured runtime logger with optional item limits through RuntimeSink. key-word: - logger - runtime @@ -13,7 +13,7 @@ key-word: ## Configured-logger-drain -Drain queued work from a `ConfiguredLogger`. This helper is useful when config-driven queue wrapping should be advanced in a controlled, bounded way. +Drain queued work from a `ConfiguredLogger`. This helper is the configured logger wrapper over `RuntimeSink::drain(...)` when config-driven queue wrapping should be advanced in a controlled, bounded way. ### Interface @@ -28,16 +28,16 @@ pub fn ConfiguredLogger::drain(self : ConfiguredLogger, max_items~ : Int = -1) - #### output -- `Int` - Number of drained items. +- `Int` - Count returned by the wrapped `RuntimeSink::drain(...)` call. ### Explanation Detailed rules explaining key parameters and behaviors -- Queue-wrapped sinks may drain up to `max_items` records. -- For plain file sinks, the runtime falls back to file flush behavior instead of queue draining. -- For sinks without queue semantics, the result is typically `0`. -- This helper delegates to `RuntimeSink::drain(...)` through the configured logger wrapper. +- This helper delegates directly to `self.sink.drain(max_items=max_items)`. +- Queue-wrapped sinks forward to the concrete queue sink's `drain(...)` behavior and may drain up to `max_items` records. +- Plain file sinks fall back to `FileSink::flush()` behavior through `RuntimeSink` and return `1` or `0`. +- Plain console-style sinks return `0` because they do not own a drainable queue here. ### How to Use @@ -64,7 +64,7 @@ In this example, the configured runtime logger drains without imposing an item c ### Error Case e.g.: -- If the runtime sink is not queue-backed, draining may return `0` or follow fallback flush behavior. +- If the configured runtime sink is not queue-backed, draining may return `0` or follow the plain-file flush fallback. - If callers only need generic flush semantics, `flush()` may be the simpler API. @@ -72,4 +72,4 @@ e.g.: 1. Prefer this helper when queue progress should be bounded or observable. -2. Use `pending_count()` to inspect remaining backlog after the drain call. +2. Use `pending_count()` to inspect remaining backlog after the drain call when the configured sink is queue-backed. diff --git a/docs/api/configured-logger-dropped-count.md b/docs/api/configured-logger-dropped-count.md index 872bc81..25d7f26 100644 --- a/docs/api/configured-logger-dropped-count.md +++ b/docs/api/configured-logger-dropped-count.md @@ -2,8 +2,8 @@ name: configured-logger-dropped-count group: api category: runtime -update-time: 20260512 -description: Read the cumulative dropped-record count from a configured runtime logger. +update-time: 20260613 +description: Read the cumulative dropped-record count from a configured runtime logger through RuntimeSink. key-word: - logger - runtime @@ -13,7 +13,7 @@ key-word: ## Configured-logger-dropped-count -Read the cumulative dropped-record count from a `ConfiguredLogger`. This helper is useful when config-driven queue wrapping may discard records under pressure. +Read the cumulative dropped-record count from a `ConfiguredLogger`. This helper is the configured logger wrapper over `RuntimeSink::dropped_count(...)` when config-driven queue wrapping may discard records under pressure. ### Interface @@ -27,16 +27,16 @@ pub fn ConfiguredLogger::dropped_count(self : ConfiguredLogger) -> Int {} #### output -- `Int` - Number of dropped records reported by the runtime sink. +- `Int` - Number returned by the wrapped `RuntimeSink::dropped_count()` call. ### Explanation Detailed rules explaining key parameters and behaviors -- Queue-backed sinks return their live dropped-count metric. -- Non-queued sinks report `0`. -- The counter is cumulative for the runtime sink lifetime. -- This helper delegates to `RuntimeSink::dropped_count(...)` through the configured logger wrapper. +- This helper delegates directly to `self.sink.dropped_count()`. +- Queue-backed runtime sink variants return their live dropped-count metric. +- Plain console and plain file runtime sink variants return `0` because they do not track queued record drops. +- The counter is cumulative for the lifetime of the concrete runtime sink value owned by the configured logger. ### How to Use @@ -65,7 +65,7 @@ In this example, the helper exposes the metric needed to compare runtime queue t ### Error Case e.g.: -- If the logger is not queue-backed, the method simply returns `0`. +- If the configured logger is not queue-backed, the method simply returns `0`. - If callers need queue shape and file status together, `file_runtime_state()` may carry more useful context for file sinks. diff --git a/docs/api/configured-logger-flush.md b/docs/api/configured-logger-flush.md index 49a09e9..e23f9d5 100644 --- a/docs/api/configured-logger-flush.md +++ b/docs/api/configured-logger-flush.md @@ -2,8 +2,8 @@ name: configured-logger-flush group: api category: runtime -update-time: 20260512 -description: Flush a configured runtime logger and return how many queued or file-backed operations were advanced. +update-time: 20260613 +description: Flush a configured runtime logger and return how many queued or file-backed operations were advanced through RuntimeSink. key-word: - logger - runtime @@ -13,7 +13,7 @@ key-word: ## Configured-logger-flush -Flush a `ConfiguredLogger` and return how much work was advanced. This is the main runtime helper for forcing queued or file-backed logger output to move forward after config-driven construction. +Flush a `ConfiguredLogger` and return how much work was advanced. This is the configured logger wrapper over `RuntimeSink::flush(...)` for forcing queued or file-backed output to move forward after config-driven construction. ### Interface @@ -27,16 +27,16 @@ pub fn ConfiguredLogger::flush(self : ConfiguredLogger) -> Int {} #### output -- `Int` - Count of flushed or drained items as reported by the runtime sink. +- `Int` - Count returned by the wrapped `RuntimeSink::flush(...)` call. ### Explanation Detailed rules explaining key parameters and behaviors -- For queue-wrapped sinks, this forwards to the queue drain/flush behavior. -- For plain file sinks, the return value reflects whether a file flush happened. -- For plain console-style sinks, the result is typically `0` because there is no meaningful buffered flush step. -- This helper delegates to `RuntimeSink::flush(...)` through the configured logger wrapper. +- This helper delegates directly to `self.sink.flush()`. +- Queue-wrapped sinks forward to the concrete queue sink's `flush()` behavior. +- Plain file sinks call `FileSink::flush()` through `RuntimeSink` and convert the boolean result into `1` or `0`. +- Plain console-style sinks return `0` because they do not expose a meaningful buffered flush step here. ### How to Use @@ -63,7 +63,7 @@ In this example, callers can observe how much work was advanced by the flush req ### Error Case e.g.: -- If the configured sink has no flushable buffering, the method may simply return `0`. +- If the configured runtime sink shape has no flushable state, the method may simply return `0`. - If callers need bounded manual draining rather than generic flush behavior, `drain(...)` is the better API. @@ -71,4 +71,4 @@ e.g.: 1. Use this helper after config-driven logger construction when explicit runtime flushing matters. -2. The exact return value depends on the underlying runtime sink shape. +2. The exact return value depends on which `RuntimeSink` variant the configured logger owns. diff --git a/docs/api/configured-logger-pending-count.md b/docs/api/configured-logger-pending-count.md index 24b73f9..0254314 100644 --- a/docs/api/configured-logger-pending-count.md +++ b/docs/api/configured-logger-pending-count.md @@ -2,8 +2,8 @@ name: configured-logger-pending-count group: api category: runtime -update-time: 20260512 -description: Read the current queued backlog count from a configured runtime logger. +update-time: 20260613 +description: Read the current queued backlog count from a configured runtime logger through RuntimeSink. key-word: - logger - runtime @@ -13,7 +13,7 @@ key-word: ## Configured-logger-pending-count -Read the current queued backlog count from a `ConfiguredLogger`. This is the direct runtime metric for config-driven queue wrapping. +Read the current queued backlog count from a `ConfiguredLogger`. This is the configured logger wrapper over `RuntimeSink::pending_count(...)` for config-driven queue metrics. ### Interface @@ -27,16 +27,16 @@ pub fn ConfiguredLogger::pending_count(self : ConfiguredLogger) -> Int {} #### output -- `Int` - Current number of pending queued records. +- `Int` - Current number returned by the wrapped `RuntimeSink::pending_count()` call. ### Explanation Detailed rules explaining key parameters and behaviors -- Queue-backed sinks return their live pending count. -- Non-queued sinks report `0`. +- This helper delegates directly to `self.sink.pending_count()`. +- Queue-backed runtime sink variants return their live pending count. +- Plain console and plain file runtime sink variants return `0` because they do not own a pending queue here. - This is a point-in-time metric and may change immediately after it is read. -- This helper delegates to `RuntimeSink::pending_count(...)` through the configured logger wrapper. ### How to Use @@ -64,7 +64,7 @@ In this example, the queue metric helps verify manual drain progress. ### Error Case e.g.: -- If the logger is not queue-backed, the method simply returns `0`. +- If the configured logger is not queue-backed, the method simply returns `0`. - If callers need richer file-plus-queue state for file sinks, `file_runtime_state()` is the better API.