From afce0c7ce239dd4f3cb04a4d61299b7eb949be6e Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sat, 13 Jun 2026 22:26:05 +0800 Subject: [PATCH] :memo: document file sink reopen methods --- docs/api/file-sink-reopen-append.md | 74 ++++++++++++++++++ docs/api/file-sink-reopen-truncate.md | 74 ++++++++++++++++++ .../file-sink-reopen-with-current-policy.md | 74 ++++++++++++++++++ docs/api/file-sink-reopen.md | 75 +++++++++++++++++++ docs/api/index.md | 4 + 5 files changed, 301 insertions(+) create mode 100644 docs/api/file-sink-reopen-append.md create mode 100644 docs/api/file-sink-reopen-truncate.md create mode 100644 docs/api/file-sink-reopen-with-current-policy.md create mode 100644 docs/api/file-sink-reopen.md diff --git a/docs/api/file-sink-reopen-append.md b/docs/api/file-sink-reopen-append.md new file mode 100644 index 0000000..6a6a292 --- /dev/null +++ b/docs/api/file-sink-reopen-append.md @@ -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. diff --git a/docs/api/file-sink-reopen-truncate.md b/docs/api/file-sink-reopen-truncate.md new file mode 100644 index 0000000..6c9f339 --- /dev/null +++ b/docs/api/file-sink-reopen-truncate.md @@ -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. diff --git a/docs/api/file-sink-reopen-with-current-policy.md b/docs/api/file-sink-reopen-with-current-policy.md new file mode 100644 index 0000000..6959445 --- /dev/null +++ b/docs/api/file-sink-reopen-with-current-policy.md @@ -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. diff --git a/docs/api/file-sink-reopen.md b/docs/api/file-sink-reopen.md new file mode 100644 index 0000000..0cd7b2f --- /dev/null +++ b/docs/api/file-sink-reopen.md @@ -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. diff --git a/docs/api/index.md b/docs/api/index.md index 3eebef9..fcaf72f 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -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)