sys-ext.core — rs.shaffe/sys-ext 0.3.0

call clj

(call f & args)

Returns a component that calls (apply f args) when started.

The behaviour when receiving a start signal more than once depends on the return value. If the last return value was nil, then f will be called again. Otherwise, f will not be called. It's recommended to return an empty map rather than nil so that start signals are idempotent.

Always becomes nil when stopped.

expand-inline-defs clj

(expand-inline-defs system)

Expands inline component definitions into full definitions. Replaces the inline definitions with references to the full definitions.

Inline component definitions are maps with a :donut.system/start key which are inside of another component's :donut.system/config map.

first-cycle clj

(first-cycle system)

Returns the first cycle discovered in the system, or nil if there are no cycles.

The returned path can be passed directly to sys-ext.graph/cycle-error.

inline-defs clj

(inline-defs component-def)

Returns a seq of inline component definitions found inside of a given component definition.

Inline component definitions are maps with a :donut.system/start key which are inside of another component's :donut.system/config map.

merge clj

(merge & ms)

Returns a component that merges ms when started.

Differs from [[clojure.core/merge]] by always returning a map and never nil. This makes it easy to distinguish between a started but empty component and a component that was not yet started.

Always becomes nil when stopped.

remove-dead-refs clj

(remove-dead-refs {:as system :donut.system/keys [defs]})

Removes weak-refs and weak-local-refs if the components they reference are not needed by the system's selected component ids. Removed refs are replaced with nil. See [[donut.system/select-components]].

This is intended to be used after calling [[donut.system/select-components]] or select-targets.

This is useful in the case that one component has a side effect that a second component wants to wait for, but the second component can start without the first component. For example, you could have one component that updates a database schema and another component that retrieves some data from the database. When the schema needs to be updated, the first component can be selected by [[donut.system/select-components]] and the second component will wait for it to complete. But when the schema does not need to be updated and the first component is not selected, the second component can still start up without it.

select-targets clj

(select-targets {:as system :donut.system/keys [defs]}
                group-names
                &
                {:keys [target-component-name throw-on-missing-target?]
                 :or {target-component-name :target
                      throw-on-missing-target? true}})

Returns the system with each target-component-name in each group in group-names selected.

Note that if nothing is selected, [[donut.system]] will behave as if all components are selected. You can check whether (::ds/selected-component-ids system) is empty to determine if this is the case.

Example: (select-targets system [:nrepl :http-server]) would select the [:nrepl :target] and [:http-server :target] components. Then calls to [[donut.system/signal]] will only send signals to those components and their dependencies. This can be useful to start a subset of components.

Options:

target-component-name Default: :target The name of the component to select in each group.

throw-on-missing-target? Default: true If true and a target component is not found in one of the groups, a [[clojure.lang.ExceptionInfo]] is thrown. If false, a missing target is simply ignored.

weak-local-ref clj

(weak-local-ref ks-or-ref)

A [[donut.system/local-ref]] that can be replaced by nil if the referenced component is not selected. See [[transform-weak-refs]] for details.

[[ks-or-ref]] may be either an existing ref or a vector of keys to pass to [[donut.system/local-ref]]. Both local and non-local refs are accepted.

weak-ref clj

(weak-ref ks-or-ref)

A [[donut.system/ref]] that can be replaced by nil if the referenced component is not selected. See [[transform-weak-refs]] for details.

[[ks-or-ref]] may be either an existing ref or a vector of keys to pass to [[donut.system/ref]].

weak-ref-kw clj

Indicates weak-ref status when present in the metadata of a [[donut.system/ref]].

weak-ref? clj

(weak-ref? ref)

Returns true if [[ref]] is a weak-ref or weak-local-ref.