mirror of
https://github.com/Nanaloveyuki/BitLogger.git
synced 2026-07-24 00:42:18 +00:00
📝 document file sink policy accessors
This commit is contained in:
Nanaloveyuki
@@ -0,0 +1,75 @@
|
||||
---
|
||||
name: file-sink-append-mode
|
||||
group: api
|
||||
category: sink
|
||||
update-time: 20260613
|
||||
description: Read the current append-mode policy used by a FileSink.
|
||||
key-word:
|
||||
- file
|
||||
- sink
|
||||
- append
|
||||
- public
|
||||
---
|
||||
|
||||
## File-sink-append-mode
|
||||
|
||||
Read the current append-mode policy used by a `FileSink`. This helper exposes whether future reopen behavior is currently append-oriented for the concrete sink value.
|
||||
|
||||
### Interface
|
||||
|
||||
```moonbit
|
||||
pub fn FileSink::append_mode(self : FileSink) -> Bool {
|
||||
```
|
||||
|
||||
#### input
|
||||
|
||||
- `self : FileSink` - File sink whose current append-mode policy should be inspected.
|
||||
|
||||
#### output
|
||||
|
||||
- `Bool` - Current append-mode policy for the sink.
|
||||
|
||||
### Explanation
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- This method reads the sink's current runtime append policy.
|
||||
- The value affects later `reopen(...)` behavior.
|
||||
- It does not report whether a file is currently writable or available.
|
||||
- This helper does not mutate sink state.
|
||||
|
||||
### How to Use
|
||||
|
||||
Here are some specific examples provided.
|
||||
|
||||
#### When Need Direct Append-policy Visibility
|
||||
|
||||
When diagnostics should show how future reopen behavior is configured:
|
||||
```moonbit
|
||||
let append = sink.append_mode()
|
||||
```
|
||||
|
||||
In this example, the concrete file sink exposes its current append policy directly.
|
||||
|
||||
#### When Validate Policy Updates
|
||||
|
||||
When a setter call should be observed immediately:
|
||||
```moonbit
|
||||
sink.set_append_mode(true)
|
||||
ignore(sink.append_mode())
|
||||
```
|
||||
|
||||
In this example, callers verify the updated append-mode policy on the sink itself.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
- If callers need the full current file policy rather than just append mode, `policy()` is the better API.
|
||||
|
||||
- This helper alone does not prove the sink is currently open; use `is_available()` for that.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper when append policy is the only file setting you need to inspect.
|
||||
|
||||
2. Pair it with reopen helpers when debugging direct file-sink behavior.
|
||||
@@ -0,0 +1,75 @@
|
||||
---
|
||||
name: file-sink-auto-flush-enabled
|
||||
group: api
|
||||
category: sink
|
||||
update-time: 20260613
|
||||
description: Read whether auto-flush is currently enabled on a FileSink.
|
||||
key-word:
|
||||
- file
|
||||
- sink
|
||||
- flush
|
||||
- public
|
||||
---
|
||||
|
||||
## File-sink-auto-flush-enabled
|
||||
|
||||
Read whether auto-flush is currently enabled on a `FileSink`. This helper exposes one important direct durability policy flag on the concrete sink.
|
||||
|
||||
### Interface
|
||||
|
||||
```moonbit
|
||||
pub fn FileSink::auto_flush_enabled(self : FileSink) -> Bool {
|
||||
```
|
||||
|
||||
#### input
|
||||
|
||||
- `self : FileSink` - File sink whose auto-flush policy should be inspected.
|
||||
|
||||
#### output
|
||||
|
||||
- `Bool` - Whether auto-flush is currently enabled.
|
||||
|
||||
### Explanation
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- This method reads the sink's current runtime auto-flush policy.
|
||||
- It exposes policy state only and does not force any flush action.
|
||||
- Auto-flush affects whether writes attempt a flush after each rendered record.
|
||||
- This helper does not mutate sink state.
|
||||
|
||||
### How to Use
|
||||
|
||||
Here are some specific examples provided.
|
||||
|
||||
#### When Need Direct Durability Visibility
|
||||
|
||||
When diagnostics should expose whether each write auto-flushes:
|
||||
```moonbit
|
||||
let enabled = sink.auto_flush_enabled()
|
||||
```
|
||||
|
||||
In this example, direct file durability policy is surfaced from the sink itself.
|
||||
|
||||
#### When Validate Policy Updates
|
||||
|
||||
When code should observe auto-flush after a setter call:
|
||||
```moonbit
|
||||
sink.set_auto_flush(true)
|
||||
ignore(sink.auto_flush_enabled())
|
||||
```
|
||||
|
||||
In this example, callers verify the updated policy on the concrete file sink.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
- If callers need to actually flush the file, `flush()` is the operational API.
|
||||
|
||||
- This helper does not say whether the sink is open or whether prior flushes succeeded.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper to inspect direct sink durability policy.
|
||||
|
||||
2. It complements `set_auto_flush(...)` rather than replacing real flush actions.
|
||||
@@ -0,0 +1,74 @@
|
||||
---
|
||||
name: file-sink-path
|
||||
group: api
|
||||
category: sink
|
||||
update-time: 20260613
|
||||
description: Read the configured file path used by a FileSink.
|
||||
key-word:
|
||||
- file
|
||||
- sink
|
||||
- path
|
||||
- public
|
||||
---
|
||||
|
||||
## File-sink-path
|
||||
|
||||
Read the configured file path used by a `FileSink`. This helper is useful for diagnostics, support output, and confirming which concrete file destination a sink is managing.
|
||||
|
||||
### Interface
|
||||
|
||||
```moonbit
|
||||
pub fn FileSink::path(self : FileSink) -> String {
|
||||
```
|
||||
|
||||
#### input
|
||||
|
||||
- `self : FileSink` - File sink whose path should be inspected.
|
||||
|
||||
#### output
|
||||
|
||||
- `String` - Configured file path for the sink.
|
||||
|
||||
### Explanation
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- This method returns the sink's stored file path directly.
|
||||
- The path value is observation-only and does not imply current availability.
|
||||
- Closing and reopening the sink do not change this stored path.
|
||||
- This helper does not mutate sink state.
|
||||
|
||||
### How to Use
|
||||
|
||||
Here are some specific examples provided.
|
||||
|
||||
#### When Need Direct Path Diagnostics
|
||||
|
||||
When diagnostics should show which file a concrete sink is managing:
|
||||
```moonbit
|
||||
println(sink.path())
|
||||
```
|
||||
|
||||
In this example, operators can verify the direct file destination without reading broader runtime state.
|
||||
|
||||
#### When Build Support Output
|
||||
|
||||
When application state dumps should include the configured sink path:
|
||||
```moonbit
|
||||
let path = sink.path()
|
||||
```
|
||||
|
||||
In this example, the path can be surfaced without reading policy or failure counters.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
- If callers need to know whether the path is currently backed by an open handle, `is_available()` is the better API.
|
||||
|
||||
- This helper returns the configured path even if open or reopen attempts have failed.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper for direct file-destination visibility.
|
||||
|
||||
2. It is a simple observation API and does not inspect wider sink health.
|
||||
@@ -0,0 +1,75 @@
|
||||
---
|
||||
name: file-sink-rotation-enabled
|
||||
group: api
|
||||
category: sink
|
||||
update-time: 20260613
|
||||
description: Read whether a FileSink currently has rotation configured.
|
||||
key-word:
|
||||
- file
|
||||
- sink
|
||||
- rotation
|
||||
- public
|
||||
---
|
||||
|
||||
## File-sink-rotation-enabled
|
||||
|
||||
Read whether a `FileSink` currently has rotation configured. This helper is the quickest direct check for whether size-based file rotation is active on the sink.
|
||||
|
||||
### Interface
|
||||
|
||||
```moonbit
|
||||
pub fn FileSink::rotation_enabled(self : FileSink) -> Bool {
|
||||
```
|
||||
|
||||
#### input
|
||||
|
||||
- `self : FileSink` - File sink whose current rotation setting should be inspected.
|
||||
|
||||
#### output
|
||||
|
||||
- `Bool` - Whether the sink currently has a `Some(FileRotation)` policy.
|
||||
|
||||
### Explanation
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- This method reports whether `self.rotation` is currently set.
|
||||
- It is a lightweight boolean companion to `rotation_config()`.
|
||||
- The result describes current policy state, not whether a rotation just happened successfully.
|
||||
- This helper does not mutate sink state.
|
||||
|
||||
### How to Use
|
||||
|
||||
Here are some specific examples provided.
|
||||
|
||||
#### When Need A Simple Rotation-policy Check
|
||||
|
||||
When diagnostics should show whether direct file rotation is enabled:
|
||||
```moonbit
|
||||
let enabled = sink.rotation_enabled()
|
||||
```
|
||||
|
||||
In this example, callers can branch on whether rotation policy is currently present.
|
||||
|
||||
#### When Validate Rotation Policy Changes
|
||||
|
||||
When code should confirm that a policy update took effect:
|
||||
```moonbit
|
||||
sink.set_rotation(Some(file_rotation(1024, max_backups=3)))
|
||||
ignore(sink.rotation_enabled())
|
||||
```
|
||||
|
||||
In this example, the boolean result reflects whether the sink now carries rotation config.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
- If callers need the actual `FileRotation` value, `rotation_config()` is the better API.
|
||||
|
||||
- This helper does not report past rotation failures; use `rotation_failures()` or `state()` for that.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper for quick rotation-policy visibility.
|
||||
|
||||
2. It is a lighter-weight companion to reading the full rotation config.
|
||||
@@ -142,6 +142,10 @@ BitLogger API navigation.
|
||||
- [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-append-mode.md](./file-sink-append-mode.md)
|
||||
- [file-sink-path.md](./file-sink-path.md)
|
||||
- [file-sink-auto-flush-enabled.md](./file-sink-auto-flush-enabled.md)
|
||||
- [file-sink-rotation-enabled.md](./file-sink-rotation-enabled.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