matthiasn.systems-toolbox.component.msg-handling — matthiasn/systems-toolbox 0.6.40

add-to-msg-seq clj/s

(add-to-msg-seq msg-meta cmp-id in-out)

Function for adding the current component ID to the sequence that the message has traversed thus far. The specified component IDs is either added when the cmp-seq is empty in the case of an initial send or when the message is received by a component. This avoids recording component IDs multiple times.

default-state-pub-handler clj/s

(default-state-pub-handler {:keys [observed msg-payload observed-xform]})

Default handler function, can be replaced by a more application-specific handler function, for example for resetting local component state when user is not logged in.

make-chan-w-buf clj/s

(make-chan-w-buf config)

Create a channel with a buffer of the specified size and type.

make-put-fn clj/s

(make-put-fn {:keys [cmp-id put-chan cfg firehose-chan system-info]})

The put-fn is used inside each component for emitting messages to the outside world, from the component's point of view. All the component needs to know is the type of the message. Messages are vectors of two elements, where the first one is the type as a namespaced keyword and the second one is the message payload, like this: [:some/msg-type {:some "data"}] Message payloads are typically maps or vectors, but they can also be strings, primitive types, or nil. As long as they are local, they can even be any type, e.g. a channel, but once we want messages to traverse some message transport (WebSockets, some message queue), the types need to be limited to what EDN or Transit can serialize. Note that on component startup, this channel is not wired anywhere until the 'system-ready-fn' (below) is called, which pipes this channel into the actual out-chan. Thus, components should not try call more messages than fit in the buffer before the entire system is up.

mk-handler-return-fn clj/s

(mk-handler-return-fn {:keys [state-reset-fn cfg put-fn cmp-id] :as cmp-map}
                      in-chan
                      msg-type
                      msg-meta)

Returns function for handling the return value of a handler function. This returned map can contain :new-state, :emit-msg and :send-to-self keys.

msg-handler-loop clj/s

(msg-handler-loop cmp-map chan-key)

Constructs a map with a channel for the provided channel keyword, with the buffer configured according to cfg for the channel keyword. Then starts loop for taking messages off the returned channel and calling the provided handler-fn with the msg. Uses return value from handler function to change state and emit messages if the respective keys :new-state and :emit-msg exist. Thus, the handler function can be free from side effects. For backwards compatibility, it is also possible interact with the put-fn and the cmp-state atom directly, in which case the handler function itself would produce side effects. This, however, makes such handler functions somewhat more difficult to test.

put-msg clj/s

(put-msg channel msg)

On the JVM, always uses the blocking operation for putting messages on a channel, as otherwise the system easily blows up when there are more than 1024 pending put operations. On the ClojureScript side, there is no equivalent of the blocking put, so the asynchronous operation will have to do. But then, more than 1024 pending operations in the browser wouldn't happen often, if ever.

send-msg clj/s

(send-msg cmp msg)

(send-msg cmp msg blocking?)

Sends message to the specified component. By default, calls to this function will block when no buffer space is available. Asynchronous handling is also possible (JVM only), however the implications should be understood, such as that core.async will throw an exception when there are more than 1024 pending operations. Under most circumstances, blocking seems like the safer bet. Note that, unless specified otherwise, the buffer for a component's in-chan is of size one, see 'component-defaults'.

send-msgs clj/s

(send-msgs cmp msgs)

Sends multiple messages to a component. Takes the component itself plus a sequence with messages to send to the component. Does not close the :in-chan of the component.