mirror of
https://github.com/Nanaloveyuki/BitLogger.git
synced 2026-07-24 08:52:35 +00:00
Nanaloveyuki
93 lines
2.9 KiB
Markdown
93 lines
2.9 KiB
Markdown
---
|
|
name: runtime-file-state-new
|
|
group: api
|
|
category: runtime
|
|
update-time: 20260613
|
|
description: Construct a RuntimeFileState snapshot from explicit file state and queue-runtime values.
|
|
key-word:
|
|
- runtime
|
|
- file
|
|
- state
|
|
- public
|
|
---
|
|
|
|
## Runtime-file-state-new
|
|
|
|
Construct a `RuntimeFileState` snapshot from explicit file state and queue-runtime values. This is the low-level constructor behind the public combined file-and-queue runtime state shape used in diagnostics.
|
|
|
|
### Interface
|
|
|
|
```moonbit
|
|
pub fn RuntimeFileState::new(
|
|
file : FileSinkState,
|
|
queued~ : Bool = false,
|
|
pending_count~ : Int = 0,
|
|
dropped_count~ : Int = 0,
|
|
) -> RuntimeFileState {
|
|
```
|
|
|
|
#### input
|
|
|
|
- `file : FileSinkState` - Embedded file sink snapshot.
|
|
- `queued : Bool` - Whether queue wrapping is involved for the runtime file sink.
|
|
- `pending_count : Int` - Current queued backlog count.
|
|
- `dropped_count : Int` - Current dropped-record count.
|
|
|
|
#### output
|
|
|
|
- `RuntimeFileState` - Combined runtime snapshot containing the supplied file snapshot plus queue metadata.
|
|
|
|
### Explanation
|
|
|
|
Detailed rules explaining key parameters and behaviors
|
|
|
|
- Omitting optional arguments builds a non-queued baseline around the supplied file snapshot.
|
|
- This constructor simply packages the supplied fields into one public runtime snapshot value.
|
|
- It does not inspect a live runtime sink or configured logger by itself.
|
|
- `RuntimeSink::file_runtime_state()` and `ConfiguredLogger::file_runtime_state()` are the higher-level APIs that read these values from concrete runtime objects.
|
|
|
|
### How to Use
|
|
|
|
Here are some specific examples provided.
|
|
|
|
#### When Need A Hand-built Combined File And Queue Snapshot
|
|
|
|
When tests or adapters should construct runtime file diagnostics explicitly:
|
|
```moonbit
|
|
let snapshot = RuntimeFileState::new(
|
|
FileSinkState::new("app.log", available=true),
|
|
queued=true,
|
|
pending_count=3,
|
|
dropped_count=1,
|
|
)
|
|
```
|
|
|
|
In this example, the runtime file snapshot is built directly without querying a live runtime object.
|
|
|
|
#### When Need Structured Runtime Diagnostics Input Before Serialization
|
|
|
|
When code should prepare a typed runtime file state value for later export:
|
|
```moonbit
|
|
let snapshot = RuntimeFileState::new(
|
|
runtime.file_state(),
|
|
queued=true,
|
|
pending_count=runtime.pending_count(),
|
|
dropped_count=runtime.dropped_count(),
|
|
)
|
|
```
|
|
|
|
In this example, callers still use the direct constructor while making each queue-related input explicit.
|
|
|
|
### Error Case
|
|
|
|
e.g.:
|
|
- This constructor itself does not have a normal failure mode; it only packages the provided values.
|
|
|
|
- If callers want a snapshot directly from a live runtime sink or configured logger, `file_runtime_state()` is the simpler API.
|
|
|
|
### Notes
|
|
|
|
1. Use this helper when code should construct a `RuntimeFileState` value explicitly.
|
|
|
|
2. Pair it with `runtime_file_state_to_json(...)` or `stringify_runtime_file_state(...)` when the snapshot should be exported.
|