mirror of
https://github.com/Nanaloveyuki/BitLogger.git
synced 2026-07-24 00:42:18 +00:00
📝 document runtime sink reopen methods
This commit is contained in:
Nanaloveyuki
@@ -362,6 +362,11 @@ BitLogger API navigation.
|
||||
- [runtime-sink-pending-count.md](./runtime-sink-pending-count.md)
|
||||
- [runtime-sink-dropped-count.md](./runtime-sink-dropped-count.md)
|
||||
- [runtime-sink-file-path.md](./runtime-sink-file-path.md)
|
||||
- [runtime-sink-file-available.md](./runtime-sink-file-available.md)
|
||||
- [runtime-sink-file-reopen.md](./runtime-sink-file-reopen.md)
|
||||
- [runtime-sink-file-reopen-with-current-policy.md](./runtime-sink-file-reopen-with-current-policy.md)
|
||||
- [runtime-sink-file-reopen-append.md](./runtime-sink-file-reopen-append.md)
|
||||
- [runtime-sink-file-reopen-truncate.md](./runtime-sink-file-reopen-truncate.md)
|
||||
- [runtime-sink-file-append-mode.md](./runtime-sink-file-append-mode.md)
|
||||
- [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)
|
||||
|
||||
@@ -0,0 +1,76 @@
|
||||
---
|
||||
name: runtime-sink-file-available
|
||||
group: api
|
||||
category: runtime
|
||||
update-time: 20260613
|
||||
description: Read whether a RuntimeSink currently has an available file sink behind its runtime sink shape.
|
||||
key-word:
|
||||
- runtime
|
||||
- sink
|
||||
- file
|
||||
- public
|
||||
---
|
||||
|
||||
## Runtime-sink-file-available
|
||||
|
||||
Read whether a `RuntimeSink` currently has an available file sink. This helper is useful for direct runtime diagnostics and recovery checks when code owns a runtime sink value instead of a `ConfiguredLogger`.
|
||||
|
||||
### Interface
|
||||
|
||||
```moonbit
|
||||
pub fn RuntimeSink::file_available(self : RuntimeSink) -> Bool {
|
||||
```
|
||||
|
||||
#### input
|
||||
|
||||
- `self : RuntimeSink` - Runtime sink whose file sink availability should be inspected.
|
||||
|
||||
#### output
|
||||
|
||||
- `Bool` - Whether an underlying file sink is available.
|
||||
|
||||
### Explanation
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- Plain `File` runtime variants report actual file availability.
|
||||
- `QueuedFile` runtime variants expose the availability of their wrapped inner file sink.
|
||||
- Non-file runtime variants return `false`.
|
||||
- This helper does not mutate runtime sink state.
|
||||
|
||||
### How to Use
|
||||
|
||||
Here are some specific examples provided.
|
||||
|
||||
#### When Need Direct Runtime File Health Checks
|
||||
|
||||
When operators or code should check file sink readiness on a runtime sink value:
|
||||
```moonbit
|
||||
if !sink.file_available() {
|
||||
println("file sink unavailable")
|
||||
}
|
||||
```
|
||||
|
||||
In this example, the runtime sink exposes file health directly.
|
||||
|
||||
#### When Gate Direct Recovery Logic
|
||||
|
||||
When reopen or fallback behavior depends on file availability:
|
||||
```moonbit
|
||||
let ok = sink.file_available()
|
||||
```
|
||||
|
||||
In this example, callers can decide whether a recovery action is needed.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
- If the runtime sink is not file-backed, the method returns `false`.
|
||||
|
||||
- If callers need detailed failure counters rather than a simple availability flag, `file_state()` or `file_runtime_state()` is the better API.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper for lightweight file sink health checks on direct `RuntimeSink` values.
|
||||
|
||||
2. Pair it with reopen and failure-counter APIs when diagnosing file sink problems.
|
||||
@@ -0,0 +1,74 @@
|
||||
---
|
||||
name: runtime-sink-file-reopen-append
|
||||
group: api
|
||||
category: runtime
|
||||
update-time: 20260613
|
||||
description: Reopen the file sink behind a RuntimeSink in append mode.
|
||||
key-word:
|
||||
- runtime
|
||||
- sink
|
||||
- file
|
||||
- public
|
||||
---
|
||||
|
||||
## Runtime-sink-file-reopen-append
|
||||
|
||||
Reopen the file sink behind a `RuntimeSink` in append mode. This helper is the explicit append-oriented direct recovery shortcut.
|
||||
|
||||
### Interface
|
||||
|
||||
```moonbit
|
||||
pub fn RuntimeSink::file_reopen_append(self : RuntimeSink) -> Bool {
|
||||
```
|
||||
|
||||
#### input
|
||||
|
||||
- `self : RuntimeSink` - Runtime sink whose file sink should be reopened in append mode.
|
||||
|
||||
#### output
|
||||
|
||||
- `Bool` - Whether reopen succeeded.
|
||||
|
||||
### Explanation
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- Plain `File` runtime variants reopen in append mode.
|
||||
- `QueuedFile` runtime variants forward reopen behavior to the wrapped inner file sink.
|
||||
- This helper is a specialized shortcut for a common reopen mode.
|
||||
- Non-file runtime variants return `false`.
|
||||
|
||||
### How to Use
|
||||
|
||||
Here are some specific examples provided.
|
||||
|
||||
#### When Need Append-preserving Direct Recovery
|
||||
|
||||
When file logging should continue appending after a reopen:
|
||||
```moonbit
|
||||
ignore(sink.file_reopen_append())
|
||||
```
|
||||
|
||||
In this example, reopen behavior is fixed to append mode.
|
||||
|
||||
#### When Want An Explicit Append Shortcut
|
||||
|
||||
When code should avoid manually setting append overrides:
|
||||
```moonbit
|
||||
let ok = sink.file_reopen_append()
|
||||
```
|
||||
|
||||
In this example, the call site states append intent directly.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
- If the runtime sink is not file-backed, the method returns `false`.
|
||||
|
||||
- If callers need truncate behavior instead, `file_reopen_truncate()` is the correct API.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper for explicit append-mode reopen flows on direct `RuntimeSink` values.
|
||||
|
||||
2. It is especially useful after transient file availability issues.
|
||||
@@ -0,0 +1,74 @@
|
||||
---
|
||||
name: runtime-sink-file-reopen-truncate
|
||||
group: api
|
||||
category: runtime
|
||||
update-time: 20260613
|
||||
description: Reopen the file sink behind a RuntimeSink in truncate mode.
|
||||
key-word:
|
||||
- runtime
|
||||
- sink
|
||||
- file
|
||||
- public
|
||||
---
|
||||
|
||||
## Runtime-sink-file-reopen-truncate
|
||||
|
||||
Reopen the file sink behind a `RuntimeSink` in truncate mode. This helper is the explicit truncate-oriented direct recovery or reset shortcut.
|
||||
|
||||
### Interface
|
||||
|
||||
```moonbit
|
||||
pub fn RuntimeSink::file_reopen_truncate(self : RuntimeSink) -> Bool {
|
||||
```
|
||||
|
||||
#### input
|
||||
|
||||
- `self : RuntimeSink` - Runtime sink whose file sink should be reopened in truncate mode.
|
||||
|
||||
#### output
|
||||
|
||||
- `Bool` - Whether reopen succeeded.
|
||||
|
||||
### Explanation
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- Plain `File` runtime variants reopen in truncate mode.
|
||||
- `QueuedFile` runtime variants forward reopen behavior to the wrapped inner file sink.
|
||||
- This helper is a specialized shortcut for a common reset-style reopen mode.
|
||||
- Non-file runtime variants return `false`.
|
||||
|
||||
### How to Use
|
||||
|
||||
Here are some specific examples provided.
|
||||
|
||||
#### When Need A Fresh Output File
|
||||
|
||||
When a runtime file should be reopened from an empty state:
|
||||
```moonbit
|
||||
ignore(sink.file_reopen_truncate())
|
||||
```
|
||||
|
||||
In this example, reopen behavior truncates the file before future writes continue.
|
||||
|
||||
#### When Want An Explicit Truncate Shortcut
|
||||
|
||||
When code should make destructive reopen intent obvious:
|
||||
```moonbit
|
||||
let ok = sink.file_reopen_truncate()
|
||||
```
|
||||
|
||||
In this example, the call site expresses reset-style reopen behavior directly.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
- If the runtime sink is not file-backed, the method returns `false`.
|
||||
|
||||
- If callers want to preserve existing file content, `file_reopen_append()` is the correct API.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper when starting from a fresh file is intentional.
|
||||
|
||||
2. Truncate-mode reopen is a stronger action than generic reopen recovery.
|
||||
@@ -0,0 +1,74 @@
|
||||
---
|
||||
name: runtime-sink-file-reopen-with-current-policy
|
||||
group: api
|
||||
category: runtime
|
||||
update-time: 20260613
|
||||
description: Reopen the file sink behind a RuntimeSink using its currently stored runtime policy.
|
||||
key-word:
|
||||
- runtime
|
||||
- sink
|
||||
- file
|
||||
- public
|
||||
---
|
||||
|
||||
## Runtime-sink-file-reopen-with-current-policy
|
||||
|
||||
Reopen the file sink behind a `RuntimeSink` using the currently stored runtime policy. This helper is useful when callers want direct recovery behavior without supplying a one-off append override.
|
||||
|
||||
### Interface
|
||||
|
||||
```moonbit
|
||||
pub fn RuntimeSink::file_reopen_with_current_policy(self : RuntimeSink) -> Bool {
|
||||
```
|
||||
|
||||
#### input
|
||||
|
||||
- `self : RuntimeSink` - Runtime sink whose file sink should be reopened with current policy.
|
||||
|
||||
#### output
|
||||
|
||||
- `Bool` - Whether reopen succeeded.
|
||||
|
||||
### Explanation
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- Plain `File` runtime variants reuse their current stored reopen policy.
|
||||
- `QueuedFile` runtime variants forward reopen behavior to the wrapped inner file sink.
|
||||
- This helper differs from `file_reopen(...)` because it does not accept a per-call append override.
|
||||
- Non-file runtime variants return `false`.
|
||||
|
||||
### How to Use
|
||||
|
||||
Here are some specific examples provided.
|
||||
|
||||
#### When Need Policy-preserving Direct Recovery
|
||||
|
||||
When a file sink should be reopened without changing runtime append behavior:
|
||||
```moonbit
|
||||
ignore(sink.file_reopen_with_current_policy())
|
||||
```
|
||||
|
||||
In this example, recovery reuses the runtime policy already stored on the sink.
|
||||
|
||||
#### When Separate Recovery From Policy Mutation
|
||||
|
||||
When append mode should be controlled elsewhere:
|
||||
```moonbit
|
||||
let ok = sink.file_reopen_with_current_policy()
|
||||
```
|
||||
|
||||
In this example, reopen is explicit while policy mutation stays separate.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
- If the runtime sink is not file-backed, the method returns `false`.
|
||||
|
||||
- If callers want to change append behavior during reopen, `file_reopen(...)` or `file_reopen_append()` / `file_reopen_truncate()` are better APIs.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper when direct recovery should respect the currently stored runtime policy.
|
||||
|
||||
2. It is clearer than passing no override through a more general reopen API.
|
||||
@@ -0,0 +1,75 @@
|
||||
---
|
||||
name: runtime-sink-file-reopen
|
||||
group: api
|
||||
category: runtime
|
||||
update-time: 20260613
|
||||
description: Reopen the file sink behind a RuntimeSink with an optional append-mode override.
|
||||
key-word:
|
||||
- runtime
|
||||
- sink
|
||||
- file
|
||||
- public
|
||||
---
|
||||
|
||||
## Runtime-sink-file-reopen
|
||||
|
||||
Reopen the file sink behind a `RuntimeSink`. This helper is useful for direct recovery flows after file unavailability or policy changes.
|
||||
|
||||
### Interface
|
||||
|
||||
```moonbit
|
||||
pub fn RuntimeSink::file_reopen(self : RuntimeSink, append~ : Bool? = None) -> Bool {
|
||||
```
|
||||
|
||||
#### input
|
||||
|
||||
- `self : RuntimeSink` - Runtime sink whose file sink should be reopened.
|
||||
- `append : Bool?` - Optional append-mode override used for reopen behavior.
|
||||
|
||||
#### output
|
||||
|
||||
- `Bool` - Whether reopen succeeded.
|
||||
|
||||
### Explanation
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- Plain `File` runtime variants reopen directly.
|
||||
- `QueuedFile` runtime variants forward reopen behavior to the wrapped inner file sink.
|
||||
- `append=None` preserves current reopen policy, while `Some(true/false)` overrides append mode.
|
||||
- Non-file runtime variants return `false`.
|
||||
|
||||
### How to Use
|
||||
|
||||
Here are some specific examples provided.
|
||||
|
||||
#### When Need Recovery After File Failure
|
||||
|
||||
When code should attempt to restore file logging through a `RuntimeSink` value:
|
||||
```moonbit
|
||||
ignore(sink.file_reopen())
|
||||
```
|
||||
|
||||
In this example, the runtime sink tries to reopen its file sink using current policy.
|
||||
|
||||
#### When Need Explicit Append-mode Reopen
|
||||
|
||||
When recovery should choose append or truncate behavior explicitly:
|
||||
```moonbit
|
||||
let ok = sink.file_reopen(append=Some(true))
|
||||
```
|
||||
|
||||
In this example, reopen behavior is directed by the call site.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
- If the runtime sink is not file-backed, the method returns `false`.
|
||||
|
||||
- If callers only need the current configured policy, `file_reopen_with_current_policy()` may be the clearer API.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper for explicit direct recovery flows on `RuntimeSink` values.
|
||||
|
||||
2. Pair it with `file_available()` and failure counters when diagnosing reopen behavior.
|
||||
Reference in New Issue
Block a user