package eio
Install
Dune Dependency
Authors
Maintainers
Sources
sha256=390f7814507b8133d6c25e3a67a742d731c7ca66252b287b1fb0e3ad4d10eecc
sha512=9c0c9088b178df9799aaae9deb803a802228f1329cbe452479c90e80a13985d9c364ea86ee14e4e759133940f9f6065c7e8ece509d176fb1e347c5320f00a494
doc/eio/Eio/Switch/index.html
Module Eio.SwitchSource
Grouping fibers and other resources so they can be turned off together.
Many resources in Eio (such as fibers and file handles) require a switch to be provided when they are created. The resource cannot outlive its switch.
If a function wants to create such resources, and was not passed a switch as an argument, it will need to create a switch using run. This doesn't return until all resources attached to it have been freed, preventing the function from leaking resources.
Any function creating resources that outlive it needs to be given a switch by its caller.
Each switch includes its own Cancel.t context. Calling fail cancels all fibers attached to the switch and, once they have exited, reports the error.
Note: this concept is known as a "nursery" or "bundle" in some other systems.
Example:
Switch.run (fun sw ->
let flow = Dir.open_in ~sw dir "myfile.txt" in
...
);
(* [flow] will have been closed by this point *)A switch contains a group of fibers and other resources (such as open file handles).
Switch creation
run fn runs fn with a fresh switch (initially on).
When fn finishes, run waits for all fibers registered with the switch to finish, and then releases all attached resources.
If fail is called, run will re-raise the exception (after everything is cleaned up). If fn raises an exception, it is passed to fail.
run_protected fn is like run but ignores cancellation requests from the parent context.
Cancellation and failure
get_error t is like check t except that it returns the exception instead of raising it. If t is finished, this returns (rather than raising) the Invalid_argument exception too.
fail t ex adds ex to t's set of failures and ensures that the switch's cancellation context is cancelled, to encourage all fibers to exit as soon as possible.
fail returns immediately, without waiting for the shutdown actions to complete. The exception will be raised later by run, and run's caller is responsible for handling it. Exn.combine is used to avoid duplicate or unnecessary exceptions.
Cleaning up resources
It is possible to attach clean-up hooks to a switch. Once all fibers within the switch have finished, these hooks are called. For example, when a file is opened it will register a release hook to close it.
Functions that create such resources will take a switch argument and call these functions for you. You usually don't need to call these directly.
on_release t fn registers fn to be called once t's main function has returned and all fibers have finished.
If fn raises an exception, it is passed to fail.
Release handlers are run in LIFO order, in series.
Note that fn is called within a Cancel.protect, since aborting clean-up actions is usually a bad idea and the switch may have been cancelled by the time it runs.
A handle for removing a clean-up callback.
Like on_release, but the handler can be removed later.
For example, opening a file will call on_release_cancellable to ensure the file is closed later. However, if the file is manually closed before that, it will use remove_hook to remove the hook, which is no longer needed.
remove_hook h removes a previously-added hook. If the hook has already been removed, this does nothing.