Bus is a publisher/subscriber system within the memory space of the program. A
bus has a mutable set of subscribers, which can be modified using
create returns a
Bus.Read_write.t, which you can use to
write value to the bus.
write calls the callbacks of all current subscribers before returning.
('callback, 'phantom) Bus.t,
'phantom is a read-write phantom type that
controls whether one can read values from or write values to the bus. The phantom
type states the capabilities one could ever have access to, not the capabilities that
are immediately available. In particular, if one wants to subscribe to a
Bus.Read_write.t, one must call
read_only on it in order to get a
Bus.Read_only.t that can be passed to
subscribe_exn. This is deliberate, and is
meant to avoid unintentional reads from code that should only be writing.
Callback_aritystates the type of callbacks stored in a bus.
create [%here] ArityN ~allow_subscription_after_first_write ~on_callback_raise,
[%here] is stored in the resulting bus, and contained in
%sexp_of: t, which can
help with debugging. If
allow_subscription_after_first_write is false, then
subscribe_exn will raise if it is called after
write has been called the first
time. If a callback raises,
on_callback_raise is called with an error containing
the exception. If
on_callback_raise raises, then the exception is raised to
write and the bus is closed.
close disallows future
writes -- once
close t is called, all further calls to
write t will raise.
close is idempotent. If
close is called from within a
callback, the current message will still be sent to all subscribed callbacks that
have not yet seen it before the close takes effect.
write calls all callbacks currently subscribed to the bus, with no guarantee on the
order in which they will be called.
write is fast and non-allocating, though the
callbacks themselves may allocate.
write t from within a callback on
t or if
is_closed t will raise.
subscribe_exn t [%here] ~f adds the callback
f to the set of
and returns a
Subscriber.t that can later be used to
stored in the
Subscriber.t, and contained in
%sexp_of: Subscriber.t, which can
help with debugging. If
subscribe_exn t is called by a callback in
t, i.e. during
write t, the subscription takes effect for the next
write, but does not affect the
subscribe_exn takes time proportional to the number of callbacks.
on_callback_raise is supplied, then it will be called by
raises; only if that subsequently raises will
on_callback_raise be called. If
on_callback_raise is not supplied, then
on_callback_raise will be called
unsubscribe t subscriber removes the callback corresponding to
unsubscribe never raises and is idempotent. As with
unsubscribe t during
write t takes effect after the current
unsubscribe takes time proportional to the number of