mirror of
https://github.com/Nanaloveyuki/BitLogger.git
synced 2026-07-24 00:42:18 +00:00
📝 document file sink reopen methods
This commit is contained in:
Nanaloveyuki
@@ -0,0 +1,74 @@
|
||||
---
|
||||
name: file-sink-reopen-append
|
||||
group: api
|
||||
category: sink
|
||||
update-time: 20260613
|
||||
description: Reopen a FileSink in append mode.
|
||||
key-word:
|
||||
- file
|
||||
- sink
|
||||
- reopen
|
||||
- public
|
||||
---
|
||||
|
||||
## File-sink-reopen-append
|
||||
|
||||
Reopen a `FileSink` in append mode. This helper is the explicit append-oriented recovery shortcut on the direct sink.
|
||||
|
||||
### Interface
|
||||
|
||||
```moonbit
|
||||
pub fn FileSink::reopen_append(self : FileSink) -> Bool {
|
||||
```
|
||||
|
||||
#### input
|
||||
|
||||
- `self : FileSink` - File sink that should be reopened in append mode.
|
||||
|
||||
#### output
|
||||
|
||||
- `Bool` - Whether reopen succeeded.
|
||||
|
||||
### Explanation
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- This helper is a specialized shortcut over `reopen(append=Some(true))`.
|
||||
- Reopen behavior is fixed to append mode.
|
||||
- The stored append policy is updated to `true` as part of the reopen path.
|
||||
- On failure, the sink remains unavailable and `open_failures` is incremented.
|
||||
|
||||
### How to Use
|
||||
|
||||
Here are some specific examples provided.
|
||||
|
||||
#### When Need Append-preserving Recovery
|
||||
|
||||
When file logging should continue appending after a reopen:
|
||||
```moonbit
|
||||
ignore(sink.reopen_append())
|
||||
```
|
||||
|
||||
In this example, reopen behavior is fixed to append mode.
|
||||
|
||||
#### When Want An Explicit Append Shortcut
|
||||
|
||||
When code should avoid manually setting append overrides:
|
||||
```moonbit
|
||||
let ok = sink.reopen_append()
|
||||
```
|
||||
|
||||
In this example, the call site states append intent directly.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
- If callers need truncate behavior instead, `reopen_truncate()` is the correct API.
|
||||
|
||||
- If reopen fails, the helper returns `false` and the sink stays unavailable.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper for explicit append-mode reopen flows.
|
||||
|
||||
2. It is especially useful after transient file availability issues.
|
||||
@@ -0,0 +1,74 @@
|
||||
---
|
||||
name: file-sink-reopen-truncate
|
||||
group: api
|
||||
category: sink
|
||||
update-time: 20260613
|
||||
description: Reopen a FileSink in truncate mode.
|
||||
key-word:
|
||||
- file
|
||||
- sink
|
||||
- reopen
|
||||
- public
|
||||
---
|
||||
|
||||
## File-sink-reopen-truncate
|
||||
|
||||
Reopen a `FileSink` in truncate mode. This helper is the explicit truncate-oriented recovery or reset shortcut on the direct sink.
|
||||
|
||||
### Interface
|
||||
|
||||
```moonbit
|
||||
pub fn FileSink::reopen_truncate(self : FileSink) -> Bool {
|
||||
```
|
||||
|
||||
#### input
|
||||
|
||||
- `self : FileSink` - File sink that should be reopened in truncate mode.
|
||||
|
||||
#### output
|
||||
|
||||
- `Bool` - Whether reopen succeeded.
|
||||
|
||||
### Explanation
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- This helper is a specialized shortcut over `reopen(append=Some(false))`.
|
||||
- Reopen behavior is fixed to truncate mode.
|
||||
- The stored append policy is updated to `false` as part of the reopen path.
|
||||
- On failure, the sink remains unavailable and `open_failures` is incremented.
|
||||
|
||||
### How to Use
|
||||
|
||||
Here are some specific examples provided.
|
||||
|
||||
#### When Need A Fresh Output File
|
||||
|
||||
When a direct runtime file should be reopened from an empty state:
|
||||
```moonbit
|
||||
ignore(sink.reopen_truncate())
|
||||
```
|
||||
|
||||
In this example, reopen behavior truncates the file before future writes continue.
|
||||
|
||||
#### When Want An Explicit Truncate Shortcut
|
||||
|
||||
When code should make destructive reopen intent obvious:
|
||||
```moonbit
|
||||
let ok = sink.reopen_truncate()
|
||||
```
|
||||
|
||||
In this example, the call site expresses reset-style reopen behavior directly.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
- If callers want to preserve existing file content, `reopen_append()` is the correct API.
|
||||
|
||||
- If reopen fails, the helper returns `false` and the sink stays unavailable.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper when starting from a fresh file is intentional.
|
||||
|
||||
2. Truncate-mode reopen is a stronger action than generic reopen recovery.
|
||||
@@ -0,0 +1,74 @@
|
||||
---
|
||||
name: file-sink-reopen-with-current-policy
|
||||
group: api
|
||||
category: sink
|
||||
update-time: 20260613
|
||||
description: Reopen a FileSink using its currently stored runtime policy.
|
||||
key-word:
|
||||
- file
|
||||
- sink
|
||||
- reopen
|
||||
- public
|
||||
---
|
||||
|
||||
## File-sink-reopen-with-current-policy
|
||||
|
||||
Reopen a `FileSink` using the currently stored runtime policy. This helper is useful when direct recovery should happen without supplying a one-off append override.
|
||||
|
||||
### Interface
|
||||
|
||||
```moonbit
|
||||
pub fn FileSink::reopen_with_current_policy(self : FileSink) -> Bool {
|
||||
```
|
||||
|
||||
#### input
|
||||
|
||||
- `self : FileSink` - File sink that should be reopened with current policy.
|
||||
|
||||
#### output
|
||||
|
||||
- `Bool` - Whether reopen succeeded.
|
||||
|
||||
### Explanation
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- This helper reuses the sink's currently stored append policy.
|
||||
- It differs from `reopen(...)` because it does not accept a per-call append override.
|
||||
- Existing handle state is handled through the underlying `reopen(...)` behavior.
|
||||
- On failure, the sink remains unavailable and `open_failures` is updated by the reopen path.
|
||||
|
||||
### How to Use
|
||||
|
||||
Here are some specific examples provided.
|
||||
|
||||
#### When Need Policy-preserving Recovery
|
||||
|
||||
When a file sink should be reopened without changing runtime append behavior:
|
||||
```moonbit
|
||||
ignore(sink.reopen_with_current_policy())
|
||||
```
|
||||
|
||||
In this example, recovery reuses the runtime policy already stored on the sink.
|
||||
|
||||
#### When Separate Recovery From Policy Mutation
|
||||
|
||||
When append mode should be controlled elsewhere:
|
||||
```moonbit
|
||||
let ok = sink.reopen_with_current_policy()
|
||||
```
|
||||
|
||||
In this example, reopen is explicit while policy mutation stays separate.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
- If callers want to change append behavior during reopen, `reopen(...)`, `reopen_append()`, or `reopen_truncate()` are better APIs.
|
||||
|
||||
- This helper still depends on the underlying file backend being able to reopen the path successfully.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper when recovery should respect the currently stored runtime policy.
|
||||
|
||||
2. It is clearer than passing no override through a more general reopen API.
|
||||
@@ -0,0 +1,75 @@
|
||||
---
|
||||
name: file-sink-reopen
|
||||
group: api
|
||||
category: sink
|
||||
update-time: 20260613
|
||||
description: Reopen a FileSink with an optional append-mode override.
|
||||
key-word:
|
||||
- file
|
||||
- sink
|
||||
- reopen
|
||||
- public
|
||||
---
|
||||
|
||||
## File-sink-reopen
|
||||
|
||||
Reopen a `FileSink`. This helper is useful for direct recovery flows after file unavailability or after file policy changes.
|
||||
|
||||
### Interface
|
||||
|
||||
```moonbit
|
||||
pub fn FileSink::reopen(self : FileSink, append~ : Bool? = None) -> Bool {
|
||||
```
|
||||
|
||||
#### input
|
||||
|
||||
- `self : FileSink` - File sink that should be reopened.
|
||||
- `append : Bool?` - Optional append-mode override used for reopen behavior.
|
||||
|
||||
#### output
|
||||
|
||||
- `Bool` - Whether reopen succeeded.
|
||||
|
||||
### Explanation
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- `append=None` preserves the sink's current append policy.
|
||||
- `Some(true/false)` overrides append mode for this reopen and updates the stored append policy.
|
||||
- If a handle is currently open, the method closes it before attempting reopen.
|
||||
- On reopen failure, `open_failures` is incremented and the sink remains unavailable.
|
||||
|
||||
### How to Use
|
||||
|
||||
Here are some specific examples provided.
|
||||
|
||||
#### When Need Recovery After File Failure
|
||||
|
||||
When direct file logging code should attempt to restore sink availability:
|
||||
```moonbit
|
||||
ignore(sink.reopen())
|
||||
```
|
||||
|
||||
In this example, the sink tries to reopen using its current append policy.
|
||||
|
||||
#### When Need Explicit Append-mode Reopen
|
||||
|
||||
When recovery should choose append or truncate behavior explicitly:
|
||||
```moonbit
|
||||
let ok = sink.reopen(append=Some(true))
|
||||
```
|
||||
|
||||
In this example, reopen behavior is directed by the call site.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
- If reopen fails, the method returns `false` and increments `open_failures()`.
|
||||
|
||||
- If callers only need the current configured policy with no one-off override, `reopen_with_current_policy()` may be the clearer API.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper for direct recovery flows.
|
||||
|
||||
2. Pair it with `is_available()` and failure counters when diagnosing reopen behavior.
|
||||
@@ -154,6 +154,10 @@ BitLogger API navigation.
|
||||
- [file-sink-default-policy.md](./file-sink-default-policy.md)
|
||||
- [file-sink-policy-matches-default.md](./file-sink-policy-matches-default.md)
|
||||
- [file-sink-state-method.md](./file-sink-state-method.md)
|
||||
- [file-sink-reopen.md](./file-sink-reopen.md)
|
||||
- [file-sink-reopen-with-current-policy.md](./file-sink-reopen-with-current-policy.md)
|
||||
- [file-sink-reopen-append.md](./file-sink-reopen-append.md)
|
||||
- [file-sink-reopen-truncate.md](./file-sink-reopen-truncate.md)
|
||||
- [file-sink-type.md](./file-sink-type.md)
|
||||
- [native-files-supported.md](./native-files-supported.md)
|
||||
- [file-rotation.md](./file-rotation.md)
|
||||
|
||||
Reference in New Issue
Block a user