Design

The following diagram shows an overview of Init's design:

Component

Metadata describing a building block of the software system.

A component is a map containing the following keys:

• :name - Required. The component's name
• :tags - Optional. Set of additional tags
• :deps - Optional. Sequence of dependencies
• :start-fn - Required. The component's start function
• :stop-fn - Optional. The component's stop function

Init supports deriving component maps from var metadata.

Name

Uniquely identifies the component. A name is a namespace-qualified keyword or symbol. Every name is also a tag.

Tag

Organize components. Tags are namespace-qualified keywords or symbols, or classes.

Tags can further be organized using the global hierarchy using derive.

A component is said to provide a tag, when its name or one of its tags is-a given tag, as determined by isa?.

Configuration

A collection of components, describing a system.

A configuration is a map of component names to components.

Discovery

The process of obtaining a configuration.

There are many options for discovering components, ranging from building a configuration map manually to automated classpath scanning. The result, however, is always a configuration map.

Selector

Criteria to select components in a configuration. A selector is a tag, or a collection of tags.

A components matches a selector if it provides all tags in the selector.

Dependency

A selector specifying a component or set of components that a given component depends on.

In addition to being a selector, a dependency defines if a referenced component is required or optional, and whether an unambiguous match is required.

If a dependency is a set of tags, it is considered optional and ambiguous, meaning that the component will receive zero or more matches.

If a dependency is a single tag or a sequence of tags, it requires a unique match, and dependency resolution will fail if no matching component exists in the configuration, or multiple candidates match the selector.

Graph

A data structure derived from a configuration, containing resolved component dependencies. Graphs are directed and acyclic (DAG).

Validation

The process of building a graph from a configuration, by resolving dependencies and validating their requirements.

Instance

A concrete instance of a component. Instances can be any values, mutable or immutable, including nil.

Start function

A function returning a component's instance, with the help of any instances from its dependencies.

Start functions need to accept a sequence of collections: For every dependency, a collection of instances of all matching components.

Init supports building start functions from inject specifications.

System

A map of names to instances.

Start

The process of starting a system from a graph, by invoking each component's start function in dependency order.

Stop function

A function taking an instance and performing any shutdown or cleanup required. A stop function's return value is ignored.

Stop

The process of stopping a system by invoking each component's stop function in reverse dependency order.