module Callback_arity : sig ... end
Callback_arity
states the type of callbacks stored in a bus. Using Callback_arity
is an implementation technique that allows callbacks to be defined as ordinary n-ary curried functions (e.g., a1 -> a2 -> a3 -> r
), instead of forcing n-ary-variadic callbacks to use tuples (e.g., a1 * a2 * a3 -> r
). This also avoids extra allocation.
val sexp_of_t : ('callback -> Ppx_sexp_conv_lib.Sexp.t) -> ('phantom -> Ppx_sexp_conv_lib.Sexp.t) -> ('callback, 'phantom) t -> Ppx_sexp_conv_lib.Sexp.t
type ('callback, 'phantom) bus = ('callback, 'phantom) t
module Read_write : sig ... end
module Read_only : sig ... end
module On_subscription_after_first_write : sig ... end
val read_only : ('callback, _) t -> 'callback Read_only.t
val create : ?name:Info.t -> Source_code_position.t -> 'callback Callback_arity.t -> on_subscription_after_first_write:On_subscription_after_first_write.t -> on_callback_raise:(Error.t -> Base.Unit.t) -> 'callback Read_write.t
In create [%here] ArityN ~on_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 on_subscription_after_first_write
is Raise
, then subscribe_exn
will raise if it is called after write
has been called the first time. If on_subscription_after_first_write
is Allow_and_send_last_value
, then the bus will remember the last value written and will send it to new subscribers.
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.
val callback_arity : ('callback, _) t -> 'callback Callback_arity.t
val num_subscribers : (_, _) t -> Base.Int.t
val is_closed : (_, _) t -> Base.Bool.t
val close : 'callback Read_write.t -> Base.Unit.t
close
disallows future write
s -- 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.
val write : ('a -> Base.Unit.t) Read_write.t -> 'a -> Base.Unit.t
val write2 : ('a -> 'b -> Base.Unit.t) Read_write.t -> 'a -> 'b -> Base.Unit.t
val write3 : ('a -> 'b -> 'c -> Base.Unit.t) Read_write.t -> 'a -> 'b -> 'c -> Base.Unit.t
val write4 : ('a -> 'b -> 'c -> 'd -> Base.Unit.t) Read_write.t -> 'a -> 'b -> 'c -> 'd -> Base.Unit.t
module Subscriber : sig ... end
val subscribe_exn : ?extract_exn:Base.Bool.t -> ?on_callback_raise:(Error.t -> Base.Unit.t) -> ?on_close:(Base.Unit.t -> Base.Unit.t) -> ('callback, [> Core_kernel__Std_internal.read ]) t -> Source_code_position.t -> f:'callback -> 'callback Subscriber.t
subscribe_exn t [%here] ~f
adds the callback f
to the set of t
's subscribers, and returns a Subscriber.t
that can later be used to unsubscribe
. [%here]
is 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 current write
. subscribe_exn
takes amortized constant time.
If on_callback_raise
is supplied, then it will be called by write
whenever f
raises; only if that subsequently raises will t
's on_callback_raise
be called. If on_callback_raise
is not supplied, then t
's on_callback_raise
will be called whenever f
raises.
If on_callback_raise
is supplied and extract_exn
is set to true, then the error passed to the on_callback_raise
method will contain only the exception raised by f
without any additional information about the bus subscription or backtrace.
on_close
is called if you are still subscribed when Bus.close
is called.
val iter_exn : ('callback, [> Core_kernel__Std_internal.read ]) t -> Source_code_position.t -> f:'callback -> Base.Unit.t
iter_exn t [%here] ~f
is ignore (subscribe_exn t [%here] ~callback:f)
. This captures the common usage in which one never wants to unsubscribe from a bus.
module Fold_arity : sig ... end
val fold_exn : ('callback, [> Core_kernel__Std_internal.read ]) t -> Source_code_position.t -> ('callback, 'f, 's) Fold_arity.t -> init:'s -> f:'f -> Base.Unit.t
fold_exn t [%here] arity ~init ~f
folds over the bus events, threading a state value to every call. It is otherwise similar to iter_exn
.
val unsubscribe : ('callback, [> Core_kernel__Std_internal.read ]) t -> 'callback Subscriber.t -> Base.Unit.t
unsubscribe t subscriber
removes the callback corresponding to subscriber
from t
. unsubscribe
never raises and is idempotent. As with subscribe_exn
, unsubscribe t
during write t
takes effect after the current write
finishes. Also like subscribe_exn
, unsubscribe
takes amortized constant time.