Module Core_kernel__.Bus

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.

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.

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.

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 time proportional to the number of callbacks.

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.

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.

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.

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 time proportional to the number of callbacks.