mirror of
https://github.com/Nanaloveyuki/BitLogger.git
synced 2026-07-24 00:42:18 +00:00
📝 refresh runtime file model docs
This commit is contained in:
Nanaloveyuki
@@ -3,7 +3,7 @@ name: file-sink-policy
|
||||
group: api
|
||||
category: sink
|
||||
update-time: 20260613
|
||||
description: Public file policy alias used by file sinks and configured runtime file controls.
|
||||
description: Public file policy alias used by file sinks and runtime file-control APIs.
|
||||
key-word:
|
||||
- file
|
||||
- policy
|
||||
@@ -13,7 +13,7 @@ key-word:
|
||||
|
||||
## File-sink-policy
|
||||
|
||||
`FileSinkPolicy` is the public policy object used to describe file append mode, auto-flush behavior, and optional rotation settings together. It is a direct alias to the file policy model shared by `FileSink`, `ConfiguredLogger`, and file policy JSON helpers.
|
||||
`FileSinkPolicy` is the public policy object used to describe file append mode, auto-flush behavior, and optional rotation settings together. It is a direct alias to the file policy model shared by `FileSink`, `RuntimeSink`, `ConfiguredLogger`, and file policy JSON helpers.
|
||||
|
||||
### Interface
|
||||
|
||||
@@ -31,8 +31,8 @@ Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- This is a type alias, not a separate runtime wrapper.
|
||||
- The current policy fields are `append : Bool`, `auto_flush : Bool`, and `rotation : FileRotation?`.
|
||||
- The same policy object is returned by `FileSink::policy()` and `ConfiguredLogger::file_policy()`.
|
||||
- It is also accepted by `FileSink::set_policy(...)` and `ConfiguredLogger::file_set_policy(...)`.
|
||||
- The same policy object is returned by `FileSink::policy()`, `RuntimeSink::file_policy()`, and `ConfiguredLogger::file_policy()`.
|
||||
- It is also accepted by `FileSink::set_policy(...)`, `RuntimeSink::file_set_policy(...)`, and `ConfiguredLogger::file_set_policy(...)`.
|
||||
|
||||
### How to Use
|
||||
|
||||
@@ -55,7 +55,7 @@ In this example, the file policy can be passed around as one typed value instead
|
||||
|
||||
When current file behavior should be read, adjusted, and written back:
|
||||
```moonbit
|
||||
let policy = logger.file_policy()
|
||||
let policy = sink.file_policy()
|
||||
let next = FileSinkPolicy::new(
|
||||
append=policy.append,
|
||||
auto_flush=false,
|
||||
@@ -63,7 +63,7 @@ let next = FileSinkPolicy::new(
|
||||
)
|
||||
```
|
||||
|
||||
In this example, the policy object is the handoff boundary for runtime file control.
|
||||
In this example, the policy object is the handoff boundary for direct runtime file control.
|
||||
|
||||
### Error Case
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@ key-word:
|
||||
|
||||
## File-sink-state
|
||||
|
||||
`FileSinkState` is the public snapshot object used to describe the current state of a file sink. It is a direct alias to the file state model returned by `FileSink::state()` and configured runtime file inspection helpers.
|
||||
`FileSinkState` is the public snapshot object used to describe the current state of a file sink. It is a direct alias to the file state model returned by `FileSink::state()` and by higher-level runtime file inspection helpers.
|
||||
|
||||
### Interface
|
||||
|
||||
@@ -32,7 +32,8 @@ Detailed rules explaining key parameters and behaviors
|
||||
- This is a type alias, not a live file handle wrapper.
|
||||
- The current snapshot fields are `path`, `available`, `append`, `auto_flush`, `rotation`, `open_failures`, `write_failures`, `flush_failures`, and `rotation_failures`.
|
||||
- `FileSink::state()` returns this object directly for a concrete file sink.
|
||||
- `ConfiguredLogger::file_state()` also returns this type, including fallback snapshots for non-file runtime sinks.
|
||||
- `RuntimeSink::file_state()` also returns this type, including fallback snapshots for non-file runtime sinks.
|
||||
- `ConfiguredLogger::file_state()` returns the same snapshot type through the config-built runtime wrapper.
|
||||
|
||||
### How to Use
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@ name: runtime-file-state
|
||||
group: api
|
||||
category: runtime
|
||||
update-time: 20260613
|
||||
description: Public combined file-and-queue runtime state alias used by configured logger diagnostics.
|
||||
description: Public combined file-and-queue runtime state alias used by runtime file diagnostics.
|
||||
key-word:
|
||||
- runtime
|
||||
- file
|
||||
@@ -13,7 +13,7 @@ key-word:
|
||||
|
||||
## Runtime-file-state
|
||||
|
||||
`RuntimeFileState` is the public snapshot object that combines file state with queue runtime context for configured loggers. It is a direct alias to the runtime model used by configured file diagnostics and JSON export helpers.
|
||||
`RuntimeFileState` is the public snapshot object that combines file state with queue runtime context for file-backed runtime diagnostics. It is a direct alias to the runtime model used by `RuntimeSink`, `ConfiguredLogger`, and JSON export helpers.
|
||||
|
||||
### Interface
|
||||
|
||||
@@ -31,7 +31,7 @@ Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- This is a type alias, not a live runtime controller.
|
||||
- The current fields are `file : FileSinkState`, `queued : Bool`, `pending_count : Int`, and `dropped_count : Int`.
|
||||
- This type is returned by `ConfiguredLogger::file_runtime_state()` when the configured sink can expose file runtime context.
|
||||
- This type is returned by `RuntimeSink::file_runtime_state()` and by `ConfiguredLogger::file_runtime_state()` when file runtime context is available.
|
||||
- It is broader than `FileSinkState` because it also reports whether queue wrapping is involved and how the queue is behaving.
|
||||
|
||||
### How to Use
|
||||
@@ -40,9 +40,9 @@ Here are some specific examples provided.
|
||||
|
||||
#### When Need Combined File And Queue Diagnostics
|
||||
|
||||
When a configured logger may wrap a file sink in a queue:
|
||||
When a direct runtime sink may wrap a file sink in a queue:
|
||||
```moonbit
|
||||
match logger.file_runtime_state() {
|
||||
match sink.file_runtime_state() {
|
||||
Some(snapshot) => println(snapshot.pending_count)
|
||||
None => ()
|
||||
}
|
||||
@@ -54,7 +54,7 @@ In this example, queue backlog can be inspected alongside the embedded file stat
|
||||
|
||||
When runtime support output should include both file and queue context:
|
||||
```moonbit
|
||||
match logger.file_runtime_state() {
|
||||
match sink.file_runtime_state() {
|
||||
Some(snapshot) => println(stringify_runtime_file_state(snapshot, pretty=true))
|
||||
None => ()
|
||||
}
|
||||
@@ -67,7 +67,7 @@ In this example, one typed object covers both the file snapshot and queue counte
|
||||
e.g.:
|
||||
- `RuntimeFileState` itself does not have a runtime failure mode.
|
||||
|
||||
- If the configured logger is not file-backed, `file_runtime_state()` may return `None` instead of producing this snapshot.
|
||||
- If the runtime sink is not file-backed, `file_runtime_state()` may return `None` instead of producing this snapshot.
|
||||
|
||||
### Notes
|
||||
|
||||
|
||||
Reference in New Issue
Block a user