naloveyuki/BitLogger
1
0
Fork 0
mirror of https://github.com/Nanaloveyuki/BitLogger.git synced 2026-07-31 07:24:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

📝 clarify sync facade unwrap aliasing

Browse Source
This commit is contained in:
Nanaloveyuki
2026-06-14 11:11:34 +08:00
parent 2fd1290179
commit e3c7e00b1e
1 changed files with 8 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/library-logger-to-logger.md
+8 -2
View File
@@ -2,8 +2,8 @@
name: library-logger-to-logger name: library-logger-to-logger
group: api group: api
category: facade category: facade
update-time: 20260613 update-time: 20260614
description: Recover the underlying full sync logger from the library-facing sync facade without rebuilding sink or logger composition state. description: Recover the underlying full sync logger from the library-facing sync facade without rebuilding, copying, or detaching the wrapped logger state.
key-word: key-word:
- logger - logger
- library - library
@@ -35,9 +35,11 @@ Detailed rules explaining key parameters and behaviors
- This conversion unwraps the existing logger instead of rebuilding it. - This conversion unwraps the existing logger instead of rebuilding it.
- Sink wiring, target, min level, timestamp behavior, and attached wrappers remain the same. - Sink wiring, target, min level, timestamp behavior, and attached wrappers remain the same.
- The returned `Logger[S]` is still that same live wrapped value, so later facade writes or later unwraps continue observing and mutating the same logger instance.
- Use this when code needs full-surface APIs such as `with_timestamp(...)`, `with_filter(...)`, or `with_patch(...)`. - Use this when code needs full-surface APIs such as `with_timestamp(...)`, `with_filter(...)`, or `with_patch(...)`.
- When the wrapped sink is `RuntimeSink`, unwrapping preserves that runtime sink value, but the result type is still `Logger[RuntimeSink]` rather than the `ConfiguredLogger` alias. Runtime-specific operations remain available through `full.sink` or by keeping a `ConfiguredLogger` value directly. - When the wrapped sink is `RuntimeSink`, unwrapping preserves that runtime sink value, but the result type is still `Logger[RuntimeSink]` rather than the `ConfiguredLogger` alias. Runtime-specific operations remain available through `full.sink` or by keeping a `ConfiguredLogger` value directly.
- That same unwrap also preserves queued runtime state and file-backed helper behavior exactly as they existed behind the facade, including drain or flush results, file state snapshots, and file control methods. - That same unwrap also preserves queued runtime state and file-backed helper behavior exactly as they existed behind the facade, including drain or flush results, file state snapshots, and file control methods.
- Runtime and file helper mutations are still live too. Draining queued records, flushing, or changing file helper state through the unwrapped logger changes the same runtime-backed logger that the facade already wrapped.
### How to Use ### How to Use
@@ -63,6 +65,8 @@ ignore(full.sink.pending_count())
In this example, unwrapping preserves the same `RuntimeSink` pipeline, and callers reach runtime-specific helpers through that preserved sink value. In this example, unwrapping preserves the same `RuntimeSink` pipeline, and callers reach runtime-specific helpers through that preserved sink value.
The same handle keeps reflecting later facade writes instead of becoming a detached snapshot.
### Error Case ### Error Case
e.g.: e.g.:
@@ -74,6 +78,8 @@ e.g.:
- Recovering the full logger does not translate configured runtime state into a simpler snapshot; queued counts, file availability, file failure counters, and runtime file controls stay exactly as they were on the wrapped logger. - Recovering the full logger does not translate configured runtime state into a simpler snapshot; queued counts, file availability, file failure counters, and runtime file controls stay exactly as they were on the wrapped logger.
- Recovering the full logger also does not isolate later runtime-helper mutations. If unwrapped code drains queued records or changes file helper state, later facade writes still run against that same updated wrapped logger.
### Notes ### Notes
1. Use this only when the narrower facade is no longer sufficient. 1. Use this only when the narrower facade is no longer sufficient.