mirror of
https://github.com/Nanaloveyuki/BitLogger.git
synced 2026-07-24 08:52:35 +00:00
Nanaloveyuki
86 lines
3.1 KiB
Markdown
86 lines
3.1 KiB
Markdown
---
|
|
name: runtime-sink-progress
|
|
group: api
|
|
category: runtime
|
|
update-time: 20260707
|
|
description: Public structured generic progress snapshot used by RuntimeSink and ConfiguredLogger flush or drain helpers.
|
|
key-word:
|
|
- runtime
|
|
- progress
|
|
- flush
|
|
- public
|
|
---
|
|
|
|
## Runtime-sink-progress
|
|
|
|
`RuntimeSinkProgress` is the public structured progress snapshot returned by the truthful generic `flush_progress(...)` and `drain_progress(...)` helpers. It separates queue advancement from plain file flush fallback steps so callers do not have to infer mixed `Int` semantics from `flush()` or `drain()` alone.
|
|
|
|
### Interface
|
|
|
|
```moonbit
|
|
pub struct RuntimeSinkProgress {
|
|
queue_advanced_count : Int
|
|
file_flush_step_count : Int
|
|
queue_backed : Bool
|
|
file_backed : Bool
|
|
}
|
|
```
|
|
|
|
#### output
|
|
|
|
- `RuntimeSinkProgress` - Public generic progress snapshot containing queue advancement count, plain-file flush fallback count, and runtime-shape flags.
|
|
|
|
### Explanation
|
|
|
|
Detailed rules explaining key parameters and behaviors
|
|
|
|
- This is a public root struct, not a type alias.
|
|
- `queue_advanced_count` reports how many queued records were consumed by a queue-backed runtime helper call.
|
|
- `file_flush_step_count` reports the plain-file fallback step count used by generic helpers on non-queued file sinks, currently `1` for a successful `FileSink::flush()` and `0` otherwise.
|
|
- `queue_backed` reports whether the runtime sink shape was queue-backed during the helper call.
|
|
- `file_backed` reports whether the runtime sink shape was file-backed during the helper call.
|
|
- For queued file sinks, `queue_advanced_count` may be positive while `file_flush_step_count` stays `0`; delayed file failures still belong to `file_flush()` and failure-counter inspection rather than to this generic progress snapshot.
|
|
|
|
### How to Use
|
|
|
|
Here are some specific examples provided.
|
|
|
|
#### When Need Truthful Generic Runtime Progress
|
|
|
|
When code should inspect generic flush or drain work without guessing what one `Int` means:
|
|
```moonbit
|
|
let progress = sink.flush_progress()
|
|
if progress.queue_backed {
|
|
println(progress.queue_advanced_count)
|
|
}
|
|
```
|
|
|
|
In this example, queue progress stays explicit instead of being folded into a compatibility count.
|
|
|
|
#### When Need To Distinguish Plain File Fallback From Queue Work
|
|
|
|
When generic runtime support code should tell plain-file fallback apart from queued advancement:
|
|
```moonbit
|
|
let progress = logger.drain_progress()
|
|
if progress.file_backed && !progress.queue_backed {
|
|
println(progress.file_flush_step_count)
|
|
}
|
|
```
|
|
|
|
In this example, the caller can recognize the plain-file generic fallback path directly.
|
|
|
|
### Error Case
|
|
|
|
e.g.:
|
|
- `RuntimeSinkProgress` itself does not have a runtime failure mode.
|
|
|
|
- This type reports generic progress only; it does not prove durable file delivery.
|
|
|
|
- If callers need file-specific success semantics, `file_flush()` is still the narrower API.
|
|
|
|
### Notes
|
|
|
|
1. Prefer this structured result over the legacy `Int` returned by `flush()` and `drain()` when new code can choose.
|
|
|
|
2. For queued file sinks, combine this snapshot with `file_flush()`, `file_runtime_state()`, or file failure counters when file outcome matters.
|