mirror of
https://github.com/Nanaloveyuki/BitLogger.git
synced 2026-07-24 08:52:35 +00:00
Nanaloveyuki
78 lines
2.5 KiB
Markdown
78 lines
2.5 KiB
Markdown
---
|
|
name: runtime-file-state
|
|
group: api
|
|
category: runtime
|
|
update-time: 20260707
|
|
description: Public combined file-and-queue runtime state re-exported from file_model for runtime diagnostics.
|
|
key-word:
|
|
- runtime
|
|
- file
|
|
- state
|
|
- public
|
|
---
|
|
|
|
## Runtime-file-state
|
|
|
|
`RuntimeFileState` is the public snapshot object that combines file state with queue runtime context for file-backed runtime diagnostics. On the root `src` facade, it is re-exported from `src/file_model`, which is the real owner of the concrete runtime file state model.
|
|
|
|
### Interface
|
|
|
|
```moonbit
|
|
pub using @file_model { type RuntimeFileState }
|
|
```
|
|
|
|
#### output
|
|
|
|
- `RuntimeFileState` - Public combined runtime snapshot containing a `file` snapshot plus queue metadata such as `queued`, `pending_count`, and `dropped_count`.
|
|
|
|
### Explanation
|
|
|
|
Detailed rules explaining key parameters and behaviors
|
|
|
|
- This root surface is a re-export, not the concrete owner definition.
|
|
- The concrete type lives in `@file_model.RuntimeFileState`, not in `@utils`.
|
|
- The current fields are `file : FileSinkState`, `queued : Bool`, `pending_count : Int`, and `dropped_count : Int`.
|
|
- 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
|
|
|
|
Here are some specific examples provided.
|
|
|
|
#### When Need Combined File And Queue Diagnostics
|
|
|
|
When a direct runtime sink may wrap a file sink in a queue:
|
|
```moonbit
|
|
match sink.file_runtime_state() {
|
|
Some(snapshot) => println(snapshot.pending_count)
|
|
None => ()
|
|
}
|
|
```
|
|
|
|
In this example, queue backlog can be inspected alongside the embedded file state.
|
|
|
|
#### When Need A Single Exportable Runtime Snapshot
|
|
|
|
When runtime support output should include both file and queue context:
|
|
```moonbit
|
|
match sink.file_runtime_state() {
|
|
Some(snapshot) => println(stringify_runtime_file_state(snapshot, pretty=true))
|
|
None => ()
|
|
}
|
|
```
|
|
|
|
In this example, one typed object covers both the file snapshot and queue counters.
|
|
|
|
### Error Case
|
|
|
|
e.g.:
|
|
- `RuntimeFileState` itself does not have a runtime failure mode.
|
|
|
|
- If the runtime sink is not file-backed, `file_runtime_state()` may return `None` instead of producing this snapshot.
|
|
|
|
### Notes
|
|
|
|
1. Use this type when queued-file diagnostics matter, not just raw file status.
|
|
|
|
2. Use `runtime_file_state_to_json(...)` or `stringify_runtime_file_state(...)` when the snapshot should be exported.
|