package picos_std
Install
Dune Dependency
Authors
Maintainers
Sources
sha256=3f5a08199cf65c2dae2f7d68f3877178f1da8eabf5376e15114e5a8958087dfa
sha512=ad24910c47ce614268c4268874bb918da7f8b5f03b3ad706bbf30323635262e94ddab6be24eaebbca706bfa82c0a517d4272b396459e020c185942125c9bdb7b
doc/picos_std.event/Picos_std_event/Event/index.html
Module Picos_std_event.EventSource
First-class synchronous communication abstraction.
Events describe a thing that might happen in the future, or a concurrent offer or request that might be accepted or succeed, but is cancelable if some other event happens first.
See the Picos_io_select library for an example.
ℹ️ This module intentionally mimics the Event module provided by the OCaml POSIX threads library.
An event returning a value of type 'a.
always value returns an event that can always be committed to resulting in the given value.
Composing events
choose events return an event that offers all of the given events and then commits to at most one of them.
wrap event fn returns an event that acts as the given event and then applies the given function to the value in case the event is committed to.
map fn event is equivalent to wrap event fn.
guard thunk returns an event that, when synchronized, calls the thunk, and then behaves like the resulting event.
⚠️ Raising an exception from a guard thunk will result in raising that exception out of the sync. This may result in dropping the result of an event that committed just after the exception was raised. This means that you should treat an unexpected exception raised from sync as a fatal error.
Consuming events
sync event synchronizes on the given event.
Synchronizing on an event executes in three phases:
- In the first phase offers or requests are made to communicate.
- One of the offers or requests is committed to and all the other offers and requests are canceled.
- A final result is computed from the value produced by the event.
⚠️ sync event does not wait for the canceled concurrent requests to terminate. This means that you should arrange for guaranteed cleanup through other means such as the use of structured concurrency.
select events is equivalent to sync (choose events).
Primitive events
ℹ️ The Computation concept of Picos can be seen as a basic single-shot atomic event. This module builds on that concept to provide a composable API to concurrent services exposed through computations.
Represents a function that requests a concurrent service to update a computation.
ℹ️ The computation passed to a request may be completed by some other event at any point. All primitive requests should be implemented carefully to take that into account. If the computation is completed by some other event, then the request should be considered as canceled, take no effect, and not leak any resources.
⚠️ Raising an exception from a request function will result in raising that exception out of the sync. This may result in dropping the result of an event that committed just after the exception was raised. This means that you should treat an unexpected exception raised from sync as a fatal error. In addition, you should arrange for concurrent services to report unexpected errors independently of the computation being passed to the service.
from_request { request } creates an event from the request function.
from_computation source creates an event that can be committed to once the given source computation has completed.
ℹ️ Committing to some other event does not cancel the source computation.