mirror of
https://github.com/Nanaloveyuki/BitLogger.git
synced 2026-07-24 00:42:18 +00:00
📝 document runtime sink rotation methods
This commit is contained in:
Nanaloveyuki
@@ -371,6 +371,10 @@ BitLogger API navigation.
|
||||
- [runtime-sink-file-set-append-mode.md](./runtime-sink-file-set-append-mode.md)
|
||||
- [runtime-sink-file-auto-flush.md](./runtime-sink-file-auto-flush.md)
|
||||
- [runtime-sink-file-set-auto-flush.md](./runtime-sink-file-set-auto-flush.md)
|
||||
- [runtime-sink-file-rotation-enabled.md](./runtime-sink-file-rotation-enabled.md)
|
||||
- [runtime-sink-file-rotation-config.md](./runtime-sink-file-rotation-config.md)
|
||||
- [runtime-sink-file-set-rotation.md](./runtime-sink-file-set-rotation.md)
|
||||
- [runtime-sink-file-clear-rotation.md](./runtime-sink-file-clear-rotation.md)
|
||||
- [configured-logger.md](./configured-logger.md)
|
||||
- [configured-logger-flush.md](./configured-logger-flush.md)
|
||||
- [configured-logger-drain.md](./configured-logger-drain.md)
|
||||
|
||||
@@ -0,0 +1,74 @@
|
||||
---
|
||||
name: runtime-sink-file-clear-rotation
|
||||
group: api
|
||||
category: runtime
|
||||
update-time: 20260613
|
||||
description: Disable runtime rotation on a file-backed RuntimeSink.
|
||||
key-word:
|
||||
- runtime
|
||||
- sink
|
||||
- file
|
||||
- public
|
||||
---
|
||||
|
||||
## Runtime-sink-file-clear-rotation
|
||||
|
||||
Disable runtime rotation on a file-backed `RuntimeSink`. This helper is the direct shortcut for clearing rotation policy from a runtime sink value.
|
||||
|
||||
### Interface
|
||||
|
||||
```moonbit
|
||||
pub fn RuntimeSink::file_clear_rotation(self : RuntimeSink) -> Bool {
|
||||
```
|
||||
|
||||
#### input
|
||||
|
||||
- `self : RuntimeSink` - Runtime sink whose rotation policy should be cleared.
|
||||
|
||||
#### output
|
||||
|
||||
- `Bool` - Whether the policy update was applied.
|
||||
|
||||
### Explanation
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- Plain `File` runtime variants clear rotation on the wrapped `FileSink` and return `true`.
|
||||
- `QueuedFile` runtime variants forward the update to the wrapped inner `FileSink` and return `true`.
|
||||
- Non-file runtime variants return `false`.
|
||||
- This helper is equivalent in intent to setting rotation to `None`, but is clearer at the call site.
|
||||
|
||||
### How to Use
|
||||
|
||||
Here are some specific examples provided.
|
||||
|
||||
#### When Need To Disable Rotation Explicitly
|
||||
|
||||
When runtime file rotation should be turned off on a direct sink value:
|
||||
```moonbit
|
||||
ignore(sink.file_clear_rotation())
|
||||
```
|
||||
|
||||
In this example, rotation policy is removed directly.
|
||||
|
||||
#### When Need A Clear Intent Shortcut
|
||||
|
||||
When code should make the disable-rotation intent obvious:
|
||||
```moonbit
|
||||
let ok = sink.file_clear_rotation()
|
||||
```
|
||||
|
||||
In this example, the call site reads more clearly than a generic config setter.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
- If the runtime sink is not file-backed, the method returns `false`.
|
||||
|
||||
- If callers need to switch to another rotation config rather than disable rotation, `file_set_rotation(...)` is the better API.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper when the desired effect is simply `rotation off`.
|
||||
|
||||
2. It is clearer than passing `None` through a broader setter when intent matters.
|
||||
@@ -0,0 +1,77 @@
|
||||
---
|
||||
name: runtime-sink-file-rotation-config
|
||||
group: api
|
||||
category: runtime
|
||||
update-time: 20260613
|
||||
description: Read the current rotation configuration used by a file-backed RuntimeSink.
|
||||
key-word:
|
||||
- runtime
|
||||
- sink
|
||||
- file
|
||||
- public
|
||||
---
|
||||
|
||||
## Runtime-sink-file-rotation-config
|
||||
|
||||
Read the current rotation configuration used by a file-backed `RuntimeSink`. This helper exposes active direct runtime rotation parameters when rotation is enabled.
|
||||
|
||||
### Interface
|
||||
|
||||
```moonbit
|
||||
pub fn RuntimeSink::file_rotation_config(self : RuntimeSink) -> FileRotation? {
|
||||
```
|
||||
|
||||
#### input
|
||||
|
||||
- `self : RuntimeSink` - Runtime sink whose file rotation config should be inspected.
|
||||
|
||||
#### output
|
||||
|
||||
- `FileRotation?` - Current rotation config, or `None` if rotation is disabled or the sink is not file-backed.
|
||||
|
||||
### Explanation
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- Plain `File` runtime variants return the current rotation config from the wrapped `FileSink`.
|
||||
- `QueuedFile` runtime variants forward the config from the wrapped inner `FileSink`.
|
||||
- Non-file runtime variants return `None`.
|
||||
- This helper is useful when callers need the active direct runtime policy rather than only a boolean flag.
|
||||
|
||||
### How to Use
|
||||
|
||||
Here are some specific examples provided.
|
||||
|
||||
#### When Need Direct Runtime Rotation Parameters
|
||||
|
||||
When diagnostics should include the active file rotation policy:
|
||||
```moonbit
|
||||
let rotation = sink.file_rotation_config()
|
||||
```
|
||||
|
||||
In this example, the runtime sink exposes live rotation parameters directly.
|
||||
|
||||
#### When Branch On Optional Rotation Presence
|
||||
|
||||
When code should react differently for rotating file sinks:
|
||||
```moonbit
|
||||
match sink.file_rotation_config() {
|
||||
Some(cfg) => ignore(cfg)
|
||||
None => ()
|
||||
}
|
||||
```
|
||||
|
||||
In this example, the optional return shape reflects whether rotation is active.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
- If the runtime sink is not file-backed, the method returns `None`.
|
||||
|
||||
- If callers only need to know whether rotation is enabled, `file_rotation_enabled()` is the simpler API.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper when current direct runtime rotation parameters matter.
|
||||
|
||||
2. It is useful after policy updates or recovery flows.
|
||||
@@ -0,0 +1,76 @@
|
||||
---
|
||||
name: runtime-sink-file-rotation-enabled
|
||||
group: api
|
||||
category: runtime
|
||||
update-time: 20260613
|
||||
description: Read whether rotation is currently enabled on a file-backed RuntimeSink.
|
||||
key-word:
|
||||
- runtime
|
||||
- sink
|
||||
- file
|
||||
- public
|
||||
---
|
||||
|
||||
## Runtime-sink-file-rotation-enabled
|
||||
|
||||
Read whether rotation is currently enabled on a file-backed `RuntimeSink`. This helper exposes direct runtime rotation state without requiring a `ConfiguredLogger` wrapper.
|
||||
|
||||
### Interface
|
||||
|
||||
```moonbit
|
||||
pub fn RuntimeSink::file_rotation_enabled(self : RuntimeSink) -> Bool {
|
||||
```
|
||||
|
||||
#### input
|
||||
|
||||
- `self : RuntimeSink` - Runtime sink whose file rotation state should be inspected.
|
||||
|
||||
#### output
|
||||
|
||||
- `Bool` - Whether rotation is currently enabled.
|
||||
|
||||
### Explanation
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- Plain `File` runtime variants report whether the wrapped `FileSink` currently has a rotation config.
|
||||
- `QueuedFile` runtime variants forward the state from the wrapped inner `FileSink`.
|
||||
- Non-file runtime variants return `false`.
|
||||
- This helper is narrower than `file_rotation_config()` when callers only need a yes-or-no answer.
|
||||
|
||||
### How to Use
|
||||
|
||||
Here are some specific examples provided.
|
||||
|
||||
#### When Need Direct Runtime Rotation Visibility
|
||||
|
||||
When code owns a `RuntimeSink` directly and should expose whether rotation is active:
|
||||
```moonbit
|
||||
let rotating = sink.file_rotation_enabled()
|
||||
```
|
||||
|
||||
In this example, runtime rotation state is checked without inspecting an optional config value.
|
||||
|
||||
#### When Guard Rotation-specific Direct Logic
|
||||
|
||||
When code should branch only for rotating file sinks:
|
||||
```moonbit
|
||||
if sink.file_rotation_enabled() {
|
||||
println("rotation active")
|
||||
}
|
||||
```
|
||||
|
||||
In this example, direct runtime policy drives control flow.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
- If the runtime sink is not file-backed, the method returns `false`.
|
||||
|
||||
- If callers need the actual rotation parameters, `file_rotation_config()` is the better API.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper for simple direct runtime rotation checks.
|
||||
|
||||
2. Pair it with `file_rotation_config()` when policy details also matter.
|
||||
@@ -0,0 +1,75 @@
|
||||
---
|
||||
name: runtime-sink-file-set-rotation
|
||||
group: api
|
||||
category: runtime
|
||||
update-time: 20260613
|
||||
description: Update the rotation configuration used by a file-backed RuntimeSink.
|
||||
key-word:
|
||||
- runtime
|
||||
- sink
|
||||
- file
|
||||
- public
|
||||
---
|
||||
|
||||
## Runtime-sink-file-set-rotation
|
||||
|
||||
Update the rotation configuration used by a file-backed `RuntimeSink`. This helper changes direct runtime file rotation behavior without rebuilding or rewrapping the sink.
|
||||
|
||||
### Interface
|
||||
|
||||
```moonbit
|
||||
pub fn RuntimeSink::file_set_rotation(self : RuntimeSink, rotation : FileRotation?) -> Bool {
|
||||
```
|
||||
|
||||
#### input
|
||||
|
||||
- `self : RuntimeSink` - Runtime sink whose rotation policy should change.
|
||||
- `rotation : FileRotation?` - New rotation config, or `None` to disable rotation.
|
||||
|
||||
#### output
|
||||
|
||||
- `Bool` - Whether the policy update was applied.
|
||||
|
||||
### Explanation
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- Plain `File` runtime variants update the wrapped `FileSink` rotation policy and return `true`.
|
||||
- `QueuedFile` runtime variants forward the update to the wrapped inner `FileSink` and return `true`.
|
||||
- Passing `None` disables rotation.
|
||||
- Non-file runtime variants return `false`.
|
||||
|
||||
### How to Use
|
||||
|
||||
Here are some specific examples provided.
|
||||
|
||||
#### When Need Direct Runtime Rotation Tuning
|
||||
|
||||
When a file-backed runtime sink should enable or change rotation dynamically:
|
||||
```moonbit
|
||||
ignore(sink.file_set_rotation(Some(file_rotation(1024, max_backups=3))))
|
||||
```
|
||||
|
||||
In this example, runtime rotation behavior is updated without rebuilding the sink.
|
||||
|
||||
#### When Need To Disable Rotation Through The Setter
|
||||
|
||||
When the file sink should stop rotating through one general update path:
|
||||
```moonbit
|
||||
let ok = sink.file_set_rotation(None)
|
||||
```
|
||||
|
||||
In this example, the direct runtime file sink has its rotation policy cleared explicitly.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
- If the runtime sink is not file-backed, the method returns `false`.
|
||||
|
||||
- If callers only want to remove rotation, `file_clear_rotation()` is the more direct API.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper when setting a full direct runtime rotation config.
|
||||
|
||||
2. It is useful for operational tuning without rebuilding the sink.
|
||||
Reference in New Issue
Block a user