diff --git a/src/moira/log/event_emitter.cljs b/src/moira/log/event_emitter.cljs index 0d56436..b2f00f6 100644 --- a/src/moira/log/event_emitter.cljs +++ b/src/moira/log/event_emitter.cljs @@ -1,14 +1,41 @@ (ns moira.log.event-emitter + "Create the Application Log, a central hub for propagating Application + Events." + (:require [moira.event :as event])) (defprotocol Listenable - (emit [this e]) - (listen [this f] [this k f]) - (unlisten [this] [this f] [this k f])) + "Provide means to subscribe to or unsubscribe from events of a specific + type." + + (emit [this e] + "Dispatch event `e` to all listeners. + + `:type` should be defined as keyword.") + + (listen [this f] [this k f] + "Register `f` to be notified about events of type `k`. + + If `k` is not given trigger `f` on all events.") + + (unlisten [this] [this f] [this k f] + "Unregister `f` to no longer be triggered on events of type `k`. + + If `k` is not given unregister `f` from all events. If both `k` and `f` are + not specified unregister all handlers from all events.")) (defprotocol Resumable - (pause [this]) - (resume [this])) + "Pause dispatching events and buffer events to notify handlers on resume." + + (pause [this] + "Pause dispatching of Application Events. + + Buffer events for later dispatch.") + + (resume [this] + "Resume dispatching of Application Events. + + All buffered events are triggered first and in order.")) (def ^:private empty-registry {::any []}) @@ -27,7 +54,16 @@ (fire event registry) (finally (resume this)))) -(deftype EventEmitter [factory !registry !buffer !paused?] +(deftype + ^{:doc + "Produce Application Events and propagate them to registered listeners. + + Dispatching of events can be paused and resumed."} + + EventEmitter + + [factory !registry !buffer !paused?] + Listenable (emit [this e] (let [e* (event/->event factory e)] @@ -55,7 +91,11 @@ (vswap! !buffer pop)) (vreset! !paused? false))) -(defn create [] +(defn create + "Create [[EventEmitter]] instance to serve as Application Log." + + [] + (->EventEmitter (event/factory) (volatile! empty-registry) (volatile! #queue [])