mirror of
https://github.com/Nanaloveyuki/BitLogger.git
synced 2026-05-30 23:52:27 +00:00
Nanaloveyuki
76 lines
2.1 KiB
Markdown
76 lines
2.1 KiB
Markdown
---
|
|
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.
|