naloveyuki/BitLogger
1
0
Fork 0
mirror of https://github.com/Nanaloveyuki/BitLogger.git synced 2026-05-30 15:42:25 +00:00
Code Issues Packages Projects Releases Wiki Activity

📝 Add async logger lifecycle API docs

Browse Source
This commit is contained in:
Nanaloveyuki
2026-05-12 13:55:05 +08:00
parent f172305453
commit dad55a241f
10 changed files with 757 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/async-logger-close.md
+75
View File
@@ -0,0 +1,75 @@
---
name: async-logger-close
group: api
category: async
update-time: 20260512
description: Close the async logger queue and optionally clear pending records immediately.
key-word:
- async
- logger
- lifecycle
- public
---
## Async-logger-close
Close the async logger queue and stop treating the logger as an active enqueue target. This API is the low-level lifecycle close primitive behind shutdown flows.
### Interface
```moonbit
pub fn[S] AsyncLogger::close(self : AsyncLogger[S], clear? : Bool = false) -> Unit {}
```
#### input
- `self : AsyncLogger[S]` - Async logger that should be closed.
- `clear : Bool` - Whether pending records should be abandoned immediately instead of being left for drain behavior.
#### output
- `Unit` - No return value. The logger lifecycle state is updated in place.
### Explanation
Detailed rules explaining key parameters and behaviors
- `close(...)` marks the logger as closed immediately.
- `clear=false` closes the queue without explicitly abandoning pending records in the helper itself.
- `clear=true` counts pending records as dropped and resets `pending_count` to `0` before closing the queue.
- This helper does not itself wait for the worker to finish.
### How to Use
Here are some specific examples provided.
#### When Need Immediate Queue Closure
When teardown should stop normal enqueue activity right away:
```moonbit
logger.close()
```
In this example, the logger enters closed state immediately.
#### When Need To Abandon Backlog Explicitly
When pending records should be discarded during fast shutdown:
```moonbit
logger.close(clear=true)
```
In this example, queued backlog is counted as dropped instead of waiting for further drain.
### Error Case
e.g.:
- If `clear=true`, pending records are intentionally discarded and contribute to `dropped_count()`.
- If callers need graceful waiting for drain completion, `shutdown()` is usually the better API.
### Notes
1. This is a low-level lifecycle helper; prefer `shutdown()` for normal graceful teardown.
2. Use `clear=true` only when backlog loss is an acceptable shutdown tradeoff.
docs/api/async-logger-dropped-count.md
+77
View File
@@ -0,0 +1,77 @@
---
name: async-logger-dropped-count
group: api
category: async
update-time: 20260512
description: Read the number of records dropped by the async logger because of overflow or queue clearing.
key-word:
- async
- logger
- queue
- public
---
## Async-logger-dropped-count
Read the cumulative number of records dropped by an async logger. This metric is useful when overflow policy or forced shutdown behavior may discard queued data.
### Interface
```moonbit
pub fn[S] AsyncLogger::dropped_count(self : AsyncLogger[S]) -> Int {}
```
#### input
- `self : AsyncLogger[S]` - Async logger whose dropped-record counter should be inspected.
#### output
- `Int` - Number of records dropped so far.
### Explanation
Detailed rules explaining key parameters and behaviors
- The counter increases when overflow policy discards records.
- The counter can also increase when `close(clear=true)` or `shutdown(clear=true)` abandons queued records.
- This is a cumulative counter for the lifetime of the logger value.
- Use this helper when you need a focused loss metric rather than a full `state()` snapshot.
### How to Use
Here are some specific examples provided.
#### When Need To Detect Loss Under Pressure
When queue overflow may discard records:
```moonbit
if logger.dropped_count() > 0 {
println("async log loss detected")
}
```
In this example, the code checks whether the async logger has already discarded records.
#### When Validate Shutdown Behavior In Tests
When a test intentionally clears the queue:
```moonbit
logger.close(clear=true)
ignore(logger.dropped_count())
```
In this example, the drop counter helps confirm that abandoned backlog was tracked.
### Error Case
e.g.:
- If no records have been dropped, the method simply returns `0`.
- If callers need to know why records were lost, they must interpret this metric together with overflow policy and shutdown behavior.
### Notes
1. This helper reports record loss only; it does not explain the full logger state.
2. Pair it with `pending_count()` or `state()` when investigating backlog pressure.
docs/api/async-logger-flush-policy.md
+74
View File
@@ -0,0 +1,74 @@
---
name: async-logger-flush-policy
group: api
category: async
update-time: 20260512
description: Read the async logger flush policy currently governing batch and shutdown flushing behavior.
key-word:
- async
- logger
- flush
- public
---
## Async-logger-flush-policy
Read the async logger flush policy. This helper exposes which flush mode currently controls batch and shutdown behavior.
### Interface
```moonbit
pub fn[S] AsyncLogger::flush_policy(self : AsyncLogger[S]) -> AsyncFlushPolicy {}
```
#### input
- `self : AsyncLogger[S]` - Async logger whose flush policy should be inspected.
#### output
- `AsyncFlushPolicy` - Current flush policy used by the async worker logic.
### Explanation
Detailed rules explaining key parameters and behaviors
- The returned value reflects the policy captured when the async logger was created.
- `Batch` causes explicit flush calls after worker batch processing.
- `Shutdown` causes explicit flush calls at worker shutdown.
- `Never` leaves flushing entirely to sink behavior or external control.
### How to Use
Here are some specific examples provided.
#### When Need To Inspect Runtime Flush Semantics
When diagnostics should show how the worker flushes:
```moonbit
ignore(logger.flush_policy())
```
In this example, the configured flush mode is exposed directly from the logger.
#### When Export Async Runtime Metadata
When code should include flush behavior in custom state reporting:
```moonbit
let flush = logger.flush_policy()
```
In this example, flush behavior can be surfaced without reading the full snapshot.
### Error Case
e.g.:
- This helper does not expose a normal runtime error path; it returns the configured policy.
- If callers need the policy together with backlog and failure state, `state()` is usually the better API.
### Notes
1. This helper exposes configuration-driven runtime behavior, not dynamic worker health.
2. Use `state()` when you want flush policy packaged with the rest of async logger diagnostics.
docs/api/async-logger-has-failed.md
+76
View File
@@ -0,0 +1,76 @@
---
name: async-logger-has-failed
group: api
category: async
update-time: 20260512
description: Read whether the async logger worker has encountered a failure during queue drain.
key-word:
- async
- logger
- failure
- public
---
## Async-logger-has-failed
Read whether the async logger worker has encountered a failure. This helper is a compact health signal for async delivery problems.
### Interface
```moonbit
pub fn[S] AsyncLogger::has_failed(self : AsyncLogger[S]) -> Bool {}
```
#### input
- `self : AsyncLogger[S]` - Async logger whose failure flag should be inspected.
#### output
- `Bool` - Whether the worker has failed.
### Explanation
Detailed rules explaining key parameters and behaviors
- `run()` clears previous failure state at startup.
- If the worker loop raises an error, the logger records that failure and exposes it through this flag.
- This helper is intentionally compact and should usually be paired with `last_error()` for details.
- Failure state is about runtime drain execution, not whether records were dropped due to overflow policy.
### How to Use
Here are some specific examples provided.
#### When Need A Fast Failure Signal
When runtime diagnostics should branch on worker health:
```moonbit
if logger.has_failed() {
println(logger.last_error())
}
```
In this example, the code checks failure state first, then reads the error detail.
#### When Inspect Async Runtime State In Tests
When a test needs to confirm that drain execution stayed healthy:
```moonbit
ignore(logger.has_failed())
```
In this example, the helper exposes a simple pass-fail runtime indicator.
### Error Case
e.g.:
- If `has_failed()` is `false`, queue pressure or dropped records may still exist for non-failure reasons.
- If `has_failed()` is `true`, callers should inspect `last_error()` or `state()` for more context.
### Notes
1. This helper reports worker failure, not general queue stress.
2. Pair it with `last_error()` when you need actionable detail.
docs/api/async-logger-is-closed.md
+77
View File
@@ -0,0 +1,77 @@
---
name: async-logger-is-closed
group: api
category: async
update-time: 20260512
description: Read whether the async logger has been closed and should no longer accept normal new queue traffic.
key-word:
- async
- logger
- lifecycle
- public
---
## Async-logger-is-closed
Read whether the async logger has been closed. This helper is useful for lifecycle checks around shutdown and queue finalization.
### Interface
```moonbit
pub fn[S] AsyncLogger::is_closed(self : AsyncLogger[S]) -> Bool {}
```
#### input
- `self : AsyncLogger[S]` - Async logger whose closure state should be inspected.
#### output
- `Bool` - Whether the logger has already been closed.
### Explanation
Detailed rules explaining key parameters and behaviors
- `close(...)` sets the closed state immediately.
- `shutdown(...)` also results in a closed logger by the end of its lifecycle flow.
- A closed logger should no longer be treated as a normal active enqueue target.
- This helper reflects lifecycle state only and does not indicate whether the worker is still draining.
### How to Use
Here are some specific examples provided.
#### When Guard Late-stage Logging
When code should avoid treating a logger as fully active during teardown:
```moonbit
if logger.is_closed() {
println("logger already closed")
}
```
In this example, teardown logic can branch on the closure state.
#### When Verify Shutdown Progress
When tests or diagnostics want to inspect lifecycle state:
```moonbit
logger.close()
ignore(logger.is_closed())
```
In this example, the helper confirms that close state was entered.
### Error Case
e.g.:
- If `is_closed()` returns `true`, pending records may still exist until drain or clear behavior completes.
- If callers need to know whether the worker is still active, they should also inspect `is_running()`.
### Notes
1. Closed state and running state are related but not identical.
2. Use this helper when lifecycle control matters more than queue counters.
docs/api/async-logger-is-running.md
+76
View File
@@ -0,0 +1,76 @@
---
name: async-logger-is-running
group: api
category: async
update-time: 20260512
description: Read whether the async logger worker is currently running and draining the queue.
key-word:
- async
- logger
- lifecycle
- public
---
## Async-logger-is-running
Read whether the async logger worker is currently active. This helper is useful for runtime diagnostics and shutdown coordination.
### Interface
```moonbit
pub fn[S] AsyncLogger::is_running(self : AsyncLogger[S]) -> Bool {}
```
#### input
- `self : AsyncLogger[S]` - Async logger whose worker state should be inspected.
#### output
- `Bool` - Whether the async worker loop is currently running.
### Explanation
Detailed rules explaining key parameters and behaviors
- `run()` sets the running state while the worker loop is active.
- The flag is cleared when the worker exits normally or after failure handling finishes.
- A logger may be closed while still running briefly during final drain or shutdown processing.
- This helper focuses on worker activity rather than queue size or failure details.
### How to Use
Here are some specific examples provided.
#### When Need Worker Activity Diagnostics
When runtime output should show whether the worker loop is active:
```moonbit
println(logger.is_running().to_string())
```
In this example, diagnostics can distinguish an idle configured logger from one with an active worker.
#### When Coordinate Shutdown Waiting
When code should poll worker completion explicitly:
```moonbit
while logger.is_running() {
@async.pause()
}
```
In this example, callers watch the worker lifecycle directly.
### Error Case
e.g.:
- If `is_running()` is `false`, pending records may still exist if the worker was never started or has already failed.
- If callers need a one-shot lifecycle flow, `shutdown()` is usually better than manual polling.
### Notes
1. Use this helper for worker activity checks, not as a complete health signal.
2. Pair it with `has_failed()` or `state()` when diagnosing stalled pipelines.
docs/api/async-logger-last-error.md
+76
View File
@@ -0,0 +1,76 @@
---
name: async-logger-last-error
group: api
category: async
update-time: 20260512
description: Read the last error recorded by the async logger worker during runtime failure handling.
key-word:
- async
- logger
- failure
- public
---
## Async-logger-last-error
Read the last error string recorded by the async logger worker. This helper gives the textual detail behind `has_failed()`.
### Interface
```moonbit
pub fn[S] AsyncLogger::last_error(self : AsyncLogger[S]) -> String {}
```
#### input
- `self : AsyncLogger[S]` - Async logger whose last worker error should be inspected.
#### output
- `String` - Last recorded worker error message, or an empty string if no error was recorded.
### Explanation
Detailed rules explaining key parameters and behaviors
- `run()` resets the stored error string when the worker starts.
- If the worker loop fails, the error text is captured from the raised exception.
- An empty string normally means no failure has been recorded.
- This helper reports worker execution errors, not ordinary overflow or backpressure conditions.
### How to Use
Here are some specific examples provided.
#### When Need Failure Detail In Diagnostics
When a compact error message should be surfaced to operators:
```moonbit
if logger.has_failed() {
println(logger.last_error())
}
```
In this example, the error string is only read when failure is present.
#### When Export Full Async State
When custom diagnostics want to include the last error field directly:
```moonbit
let err = logger.last_error()
```
In this example, the helper provides the textual failure detail without building a full snapshot.
### Error Case
e.g.:
- If no runtime failure has occurred, the method returns an empty string.
- If callers need broader context than just the error text, they should use `state()`.
### Notes
1. Read this helper together with `has_failed()` when interpreting worker health.
2. The stored value is a diagnostic string, not a typed error object.
docs/api/async-logger-pending-count.md
+76
View File
@@ -0,0 +1,76 @@
---
name: async-logger-pending-count
group: api
category: async
update-time: 20260512
description: Read the current number of queued records that have not yet been drained by the async logger worker.
key-word:
- async
- logger
- queue
- public
---
## Async-logger-pending-count
Read the current number of queued records that are still waiting to be processed. This API is the most direct backlog metric for an async logger instance.
### Interface
```moonbit
pub fn[S] AsyncLogger::pending_count(self : AsyncLogger[S]) -> Int {}
```
#### input
- `self : AsyncLogger[S]` - Async logger whose current backlog should be inspected.
#### output
- `Int` - Current number of pending records still in the async pipeline.
### Explanation
Detailed rules explaining key parameters and behaviors
- The count increases when records are accepted into the queue.
- The count decreases as the worker drains records.
- This is a point-in-time metric and may change immediately after it is read.
- Use this helper when a single backlog number is enough and a full `state()` snapshot is unnecessary.
### How to Use
Here are some specific examples provided.
#### When Need A Fast Backlog Check
When code should observe queue pressure directly:
```moonbit
let pending = logger.pending_count()
```
In this example, callers get the current queue backlog without building a full diagnostics snapshot.
#### When Wait For Near-idle Conditions
When operators or tests want to inspect drain progress:
```moonbit
if logger.pending_count() == 0 {
println("queue idle")
}
```
In this example, the queue backlog is checked directly.
### Error Case
e.g.:
- If the worker is not running, `pending_count()` may stay above `0` until records are drained or cleared.
- If the queue is empty, the method simply returns `0`.
### Notes
1. Use `state()` when you also need dropped counts, failure state, or runtime mode.
2. This helper is useful for lightweight health checks and tests.
docs/api/async-logger-shutdown.md
+75
View File
@@ -0,0 +1,75 @@
---
name: async-logger-shutdown
group: api
category: async
update-time: 20260512
description: Gracefully stop an async logger by waiting for idle or clearing queued work, then waiting for the worker to finish.
key-word:
- async
- logger
- lifecycle
- public
---
## Async-logger-shutdown
Gracefully stop an async logger. This is the main high-level shutdown API for async logging because it coordinates drain behavior, closure, and worker completion.
### Interface
```moonbit
pub async fn[S] AsyncLogger::shutdown(self : AsyncLogger[S], clear? : Bool = false) -> Unit {}
```
#### input
- `self : AsyncLogger[S]` - Async logger that should be shut down.
- `clear : Bool` - Whether pending records should be abandoned immediately instead of waiting for idle first.
#### output
- `Unit` - No return value. The method completes after shutdown coordination finishes.
### Explanation
Detailed rules explaining key parameters and behaviors
- `clear=false` first waits for idle, then closes the logger.
- If backlog still remains after waiting, shutdown falls back to `close(clear=true)`.
- `clear=true` immediately closes and abandons pending records.
- The method waits until `is_running()` becomes `false` before returning.
### How to Use
Here are some specific examples provided.
#### When Need Graceful Service Shutdown
When a service should stop logging only after queued records are drained:
```moonbit
await logger.shutdown()
```
In this example, the logger waits for normal drain behavior before final closure.
#### When Need Fast Shutdown Under Pressure
When teardown should prefer speed over preserving backlog:
```moonbit
await logger.shutdown(clear=true)
```
In this example, pending work is abandoned intentionally so shutdown can complete sooner.
### Error Case
e.g.:
- If `clear=true`, pending records are intentionally dropped rather than drained.
- If callers skip `shutdown()` and only inspect flags manually, it is easier to leave the worker lifecycle in an unclear state.
### Notes
1. Prefer this API over raw `close()` in normal application shutdown paths.
2. Choose `clear=true` only when loss of queued records is acceptable.
docs/api/async-logger-wait-idle.md
+75
View File
@@ -0,0 +1,75 @@
---
name: async-logger-wait-idle
group: api
category: async
update-time: 20260512
description: Wait until the async logger backlog drains to zero or a worker failure interrupts normal progress.
key-word:
- async
- logger
- queue
- public
---
## Async-logger-wait-idle
Wait until the async logger backlog drains to zero. This helper is useful when callers want to observe idle state without fully shutting down the logger.
### Interface
```moonbit
pub async fn[S] AsyncLogger::wait_idle(self : AsyncLogger[S]) -> Unit {}
```
#### input
- `self : AsyncLogger[S]` - Async logger whose backlog should be waited on.
#### output
- `Unit` - No return value. The method completes when the logger becomes idle or failure prevents normal progress.
### Explanation
Detailed rules explaining key parameters and behaviors
- The helper keeps yielding while `pending_count() > 0`.
- If `has_failed()` becomes `true`, waiting stops early instead of looping forever.
- This API does not close the logger or stop the worker.
- It is narrower than `shutdown()` and is useful when the logger should continue to be used later.
### How to Use
Here are some specific examples provided.
#### When Need A Drain Barrier Without Shutdown
When code should wait for queued work to flush before continuing:
```moonbit
await logger.wait_idle()
```
In this example, the caller waits for backlog drain but leaves the logger usable afterward.
#### When Need Phase Boundaries In Tests
When a test wants to ensure earlier async logs were processed:
```moonbit
await logger.wait_idle()
println("phase complete")
```
In this example, the wait acts as a barrier between test phases.
### Error Case
e.g.:
- If the worker has failed, `wait_idle()` stops waiting even if pending records remain.
- If the worker was never started, pending records may not drain and callers should not expect idle progress automatically.
### Notes
1. Use this helper when you want a drain barrier without closing the logger.
2. Prefer `shutdown()` when lifecycle completion matters more than continued reuse.