mirror of
https://github.com/Nanaloveyuki/BitLogger.git
synced 2026-07-24 00:42:18 +00:00
Nanaloveyuki
115 lines
4.9 KiB
Markdown
115 lines
4.9 KiB
Markdown
---
|
|
name: async-logger-state-new
|
|
group: api
|
|
category: async
|
|
update-time: 20260707
|
|
description: Construct an AsyncLoggerState snapshot from explicit runtime, lifecycle phase, queue, failure text, and flush-policy values without probing a live logger.
|
|
key-word:
|
|
- async
|
|
- logger
|
|
- state
|
|
- public
|
|
---
|
|
|
|
## Async-logger-state-new
|
|
|
|
Construct an `AsyncLoggerState` snapshot from explicit runtime, queue, lifecycle, and failure values. This is the low-level constructor behind the public async logger state shape used in diagnostics.
|
|
|
|
### Interface
|
|
|
|
```moonbit
|
|
pub fn AsyncLoggerState::new(
|
|
runtime : AsyncRuntimeState,
|
|
phase : AsyncLifecyclePhase,
|
|
pending_count : Int,
|
|
dropped_count : Int,
|
|
last_error : String,
|
|
flush_policy : AsyncFlushPolicy,
|
|
) -> AsyncLoggerState {
|
|
```
|
|
|
|
#### input
|
|
|
|
- `runtime : AsyncRuntimeState` - Embedded backend-level runtime snapshot.
|
|
- `phase : AsyncLifecyclePhase` - Primary lifecycle conclusion for the snapshot.
|
|
- `pending_count : Int` - Current async queue backlog.
|
|
- `dropped_count : Int` - Current dropped-record count.
|
|
- `last_error : String` - Latest error text, or an empty string when no failure has been recorded.
|
|
- `flush_policy : AsyncFlushPolicy` - Active async flush policy for the logger.
|
|
|
|
#### output
|
|
|
|
- `AsyncLoggerState` - Full async logger snapshot containing the supplied runtime, queue, lifecycle, and failure values.
|
|
|
|
### Explanation
|
|
|
|
Detailed rules explaining key parameters and behaviors
|
|
|
|
- This constructor packages the supplied runtime, phase, counters, last error, and flush policy into one public snapshot value.
|
|
- It does not inspect a live logger instance by itself.
|
|
- `AsyncLogger::state()` is the higher-level API that reads these values from a concrete logger.
|
|
- It also does not validate whether the supplied fields represent a combination that could come from one real logger instant.
|
|
- The supplied `runtime : AsyncRuntimeState` is stored exactly as provided; this constructor does not recompute `mode` or `background_worker` from the active backend.
|
|
- The constructor derives `is_closed`, `is_running`, `has_failed`, `backlog_retained`, `can_rerun`, and `terminal` from the supplied `phase` and `pending_count`.
|
|
- The constructed value matches the same public shape used by async logger serializers.
|
|
- Because `AsyncLoggerState` is only a data snapshot type, this constructor is mainly useful for tests, adapters, and synthetic diagnostics rather than ordinary logger inspection.
|
|
- Serialization helpers accept any `AsyncLoggerState` value, including hand-built ones from this constructor.
|
|
- That includes combinations such as `has_failed=true` together with non-zero `pending_count` or a retained `last_error`, and even a manually chosen runtime snapshot that does not match the current backend, all of which are valid for diagnostic snapshots and test fixtures.
|
|
|
|
### How to Use
|
|
|
|
Here are some specific examples provided.
|
|
|
|
#### When Need A Hand-built Async Logger Snapshot
|
|
|
|
When tests or adapters should construct a full async logger state explicitly:
|
|
```moonbit
|
|
let state = AsyncLoggerState::new(
|
|
runtime=AsyncRuntimeState::new(AsyncRuntimeMode::Compatibility, false),
|
|
phase=AsyncLifecyclePhase::Running,
|
|
pending_count=0,
|
|
dropped_count=0,
|
|
last_error="",
|
|
flush_policy=AsyncFlushPolicy::Never,
|
|
)
|
|
```
|
|
|
|
In this example, a complete async logger snapshot is assembled directly without querying a live logger instance.
|
|
|
|
#### When Need Structured Diagnostics Input Before Serialization
|
|
|
|
When code should prepare a typed logger state value for later export:
|
|
```moonbit
|
|
let state = AsyncLoggerState::new(
|
|
runtime=async_runtime_state(),
|
|
phase=logger.phase(),
|
|
pending_count=logger.pending_count(),
|
|
dropped_count=logger.dropped_count(),
|
|
last_error=logger.last_error(),
|
|
flush_policy=logger.flush_policy(),
|
|
)
|
|
```
|
|
|
|
In this example, callers still use the direct constructor while making each diagnostic 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 one live logger instance, `AsyncLogger::state()` is the simpler API.
|
|
|
|
- If callers manually combine a runtime snapshot, counters, or flush policy that do not actually belong together, the constructor still accepts that synthetic snapshot.
|
|
|
|
- If callers want the current backend-derived runtime pair instead of a synthetic one, they must pass `async_runtime_state()` explicitly or use `AsyncLogger::state()`.
|
|
|
|
- This constructor does not apply cleanup semantics such as clearing `last_error` on restart or draining pending records; callers must provide the phase and counters exactly as they want them represented.
|
|
|
|
### Notes
|
|
|
|
1. Use this helper when code should construct an `AsyncLoggerState` value explicitly.
|
|
|
|
2. Pair it with `async_logger_state_to_json(...)` or `stringify_async_logger_state(...)` when the snapshot should be exported.
|
|
|
|
3. Prefer `AsyncLogger::state()` when the goal is to report the actual current state of one live logger instance.
|