File-sink-async
Create an AsyncFileSink from Nanaloveyuki/BitLogger/src-async in an async context. The sync root package intentionally does not expose this constructor or depend on the host async filesystem. The constructor opens the file with the native moonbitlang/async/fs interface and keeps the same rotation, policy, and failure-counter surface as file_sink(...).
Interface
pub async fn file_sink_async(
path : String,
append~ : Bool = true,
auto_flush~ : Bool = true,
rotation~ : FileRotation? = None,
formatter~ : RecordFormatter = fn(rec) { format_text(rec) },
) -> AsyncFileSink {}input
path : String- Destination file path.append : Bool- Whether writes append rather than truncate on the first open.auto_flush : Bool- Whether each async write requests an async file sync.rotation : FileRotation?- Optional size-based rotation policy.formatter : RecordFormatter- Formatter used to render each record.
output
AsyncFileSink- A file sink ready for async logging and explicit async writes.
Explanation
- Use this constructor when the caller is already running inside an async event loop; it opens through the async filesystem backend.
Sink::write_async(...)andflush_async()use async filesystem operations. The synchronouswrite(...)andflush()methods remain synchronous operations over the shared file state; they do not turn the rootFileSinkAPI into an async API.- Rotation and file maintenance performed by the async write path use the async filesystem backend.
- On non-native targets, the sink follows the existing unavailable-backend behavior.
Deferred open
Config-built async loggers (build_async_logger(...) and its application/library/parse variants) create their file sink with a deferred handle and wrap it in AsyncRuntimeSink. The descriptor is acquired by the first async write:
- A deferred handle starts uninitialized and
file_available()reportstrue, because the path is not yet known to be unusable. - The first async write performs the async open. If that open fails,
open_failuresis incremented, the unusable handle is cleared sofile_available()becomesfalse, and the write itself is also counted inwrite_failures. flush_async()on a deferred handle that was never written succeeds without touching the filesystem; it reportsfalseand incrementsflush_failuresonce the handle is unavailable.
Reopen
AsyncFileSink::reopen* are synchronous control operations over the shared file state. They install a deferred handle, so the file is reopened by the next async write rather than by the reopen call itself. This keeps the control surface identical to the root FileSink without turning reopen into an async API.
How to Use
let sink = file_sink_async("app.log", auto_flush=false)
let logger = async_logger(sink)Error Case
- If the initial async open fails, the returned sink is unavailable and increments
open_failures(). - Later async writes record write and rotation failures through the existing sink counters.
Notes
Use
file_sink(...)for synchronous construction outside an async event loop.Pair this API with
native_files_supported()when code must also compile for non-native targets.