diff --git a/docs/api/file-sink-available.md b/docs/api/file-sink-available.md new file mode 100644 index 0000000..1bb4095 --- /dev/null +++ b/docs/api/file-sink-available.md @@ -0,0 +1,76 @@ +--- +name: file-sink-available +group: api +category: sink +update-time: 20260613 +description: Read whether a FileSink currently has an available underlying file handle. +key-word: + - file + - sink + - available + - public +--- + +## File-sink-available + +Read whether a `FileSink` currently has an available underlying file handle. This helper is useful for runtime diagnostics and for deciding whether reopen or fallback behavior is needed. + +### Interface + +```moonbit +pub fn FileSink::is_available(self : FileSink) -> Bool { +``` + +#### input + +- `self : FileSink` - File sink whose current availability should be inspected. + +#### output + +- `Bool` - Whether the sink currently holds an active file handle. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This method reports whether `self.handle` is currently `Some(_)`. +- A sink can become unavailable after open failure or after an explicit `close()`. +- This helper does not mutate sink state. +- It is the direct `FileSink` counterpart to configured-logger file availability checks. + +### How to Use + +Here are some specific examples provided. + +#### When Need Direct Sink Health Checks + +When code works with a concrete file sink and should verify handle readiness: +```moonbit +if !sink.is_available() { + println("file sink unavailable") +} +``` + +In this example, the caller can detect whether the sink currently has an active file handle. + +#### When Gate Recovery Or Reopen Logic + +When a reopen step should only run after loss of availability: +```moonbit +let ok = sink.is_available() +``` + +In this example, the boolean result can drive later recovery behavior. + +### Error Case + +e.g.: +- If the sink failed to open initially, this method returns `false`. + +- If callers need failure counters or a richer state snapshot rather than a yes-or-no result, `state()` is the better API. + +### Notes + +1. Use this helper for lightweight file sink health checks. + +2. Pair it with `reopen(...)`, `state()`, or failure-counter APIs when diagnosing file sink problems. diff --git a/docs/api/file-sink-close.md b/docs/api/file-sink-close.md new file mode 100644 index 0000000..6d66785 --- /dev/null +++ b/docs/api/file-sink-close.md @@ -0,0 +1,74 @@ +--- +name: file-sink-close +group: api +category: sink +update-time: 20260613 +description: Close a FileSink and drop its current file handle. +key-word: + - file + - sink + - close + - public +--- + +## File-sink-close + +Close a `FileSink` and drop its current file handle. This helper is the direct file-sink shutdown surface when code manages a concrete `FileSink` value. + +### Interface + +```moonbit +pub fn FileSink::close(self : FileSink) -> Bool { +``` + +#### input + +- `self : FileSink` - File sink to close. + +#### output + +- `Bool` - Whether closing the current handle succeeded. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- If the sink currently has no file handle, the method returns `false`. +- When a handle exists, the method attempts to close it and then sets the stored handle to `None`. +- After a successful or failed close attempt on an existing handle, the sink becomes unavailable until reopened. +- This helper does not automatically reopen the sink. + +### How to Use + +Here are some specific examples provided. + +#### When Need Direct File Teardown + +When code owns a concrete file sink and wants to release its file handle explicitly: +```moonbit +ignore(sink.close()) +``` + +In this example, the sink closes its current file handle directly. + +#### When Need To Check Close Outcome Before Reopen + +When code should observe whether a shutdown step succeeded: +```moonbit +let closed = sink.close() +``` + +In this example, the result can be used before a later `reopen(...)` step. + +### Error Case + +e.g.: +- If the sink is already unavailable, the method returns `false`. + +- If callers only want to inspect whether the sink still has a handle, `is_available()` is the simpler API. + +### Notes + +1. This method changes sink availability by clearing the current handle. + +2. It is commonly paired with `reopen(...)` when file lifecycle should be controlled explicitly. diff --git a/docs/api/file-sink-flush.md b/docs/api/file-sink-flush.md new file mode 100644 index 0000000..c259f94 --- /dev/null +++ b/docs/api/file-sink-flush.md @@ -0,0 +1,74 @@ +--- +name: file-sink-flush +group: api +category: sink +update-time: 20260613 +description: Flush a FileSink when it currently has an available file handle. +key-word: + - file + - sink + - flush + - public +--- + +## File-sink-flush + +Flush a `FileSink` directly. This helper is the concrete file-sink flush surface when code is working with a `FileSink` value instead of a configured runtime wrapper. + +### Interface + +```moonbit +pub fn FileSink::flush(self : FileSink) -> Bool { +``` + +#### input + +- `self : FileSink` - File sink to flush. + +#### output + +- `Bool` - Whether the flush operation succeeded. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- If the sink currently has no file handle, the method returns `false`. +- On flush failure, `flush_failures` is incremented. +- On success, failure counters are left unchanged. +- This helper does not reopen the sink automatically. + +### How to Use + +Here are some specific examples provided. + +#### When Need Explicit File Durability Steps + +When a concrete file sink should flush buffered file output explicitly: +```moonbit +ignore(sink.flush()) +``` + +In this example, the caller requests a direct file flush on the sink value itself. + +#### When Need A Flush Success Flag + +When code should branch on the outcome of a direct file flush: +```moonbit +let ok = sink.flush() +``` + +In this example, the result tells the caller whether the current flush succeeded. + +### Error Case + +e.g.: +- If the sink is unavailable, the method returns `false`. + +- If repeated flush failures matter operationally, inspect `flush_failures()` or `state()` instead of ignoring the result forever. + +### Notes + +1. Prefer this helper when you are working with a `FileSink` directly rather than through `ConfiguredLogger`. + +2. This method is narrower than automatic per-write flushing controlled by `auto_flush` policy. diff --git a/docs/api/index.md b/docs/api/index.md index 1753282..476d16e 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -139,6 +139,9 @@ BitLogger API navigation. - [patch-sink.md](./patch-sink.md) - [patch-sink-type.md](./patch-sink-type.md) - [file-sink.md](./file-sink.md) +- [file-sink-available.md](./file-sink-available.md) +- [file-sink-flush.md](./file-sink-flush.md) +- [file-sink-close.md](./file-sink-close.md) - [file-sink-type.md](./file-sink-type.md) - [native-files-supported.md](./native-files-supported.md) - [file-rotation.md](./file-rotation.md)