systems.thoughtfull.amalgam — systems.thoughtfull/amalgam 2.8.1

component clj

(component object & {:keys [start stop type]})

Make a component that from an object by extending component/Lifecycle via metadata.

The object must take matadata, and generally it is best as a map so it can be configured before starting(see configure). The started component (returned from start) must also take metadata.

The start and stop functions are optional, and if they are not given, then they default to no-ops.

If a type is given, it will be set as the object's type (i.e. the type key of its metadata).

After this component has been started, stopping it resets it back to object. In other words,

(let [c (amalgam/component ...)]
  (assert (identical? c (component/stop (component/start c)))))

• start (optional) — a single argument function taking the object and returning a started component, which must be able to take metadata.
• stop (optional) — a single argument function taking the started component and releasing resources. stop is side-effecting and its return value is ignored.
• type (optional) — a symbol to set as the objects type (i.e. in the :type key of its metadata).

Example:

(defn temp-file
  [& {:as opts :keys [path]}]
  (amalgam/component opts
    :start (fn [this] (assoc this :file (io/file (:path this))))
    :stop (fn [this] (io/delete-file (:file this) true))))
(def my-system (component/system-map :scratch-file (temp-file :path "/tmp/scratch")))

configure clj

(configure component config)

(configure component config merge-fn)

Recursively merge config map into component using merge-fns as necessary. Maps are recursively merged. Sets, vectors and lists are non-recursively concatenated.

This behavior can be overridden with merge-fns, which should match the structure of config and value. A merge function takes two arguments: the current value, and the configured value (respectively) and should return the final, resolved value.

Example:

user> (amalgam/configure {:a [1] :b {:c [2]}}
        {:a [10] :b {:c [20] :d 30}}
        {:b {:c amalgam/overwrite}})
{:a [1 10], :b {:c [20], :d 30}}

data-source clj

(data-source & {:keys [make-data-source-fn login-timeout-duration log-writer]})

Make a new DataSourceComponent wrapping a javax.sql.DataSource.

If the wrapped data source implements java.io.AutoCloseable or java.io.Closeable, then when the component is stopped it will close the data source. If the wrapped data source does not implement either interface, then stop will not attempt to close it.

• make-data-source-fn — a function that takes the DataSourceComponent as an argument and creates a DataSource for wrapping. Any options necessary for constructing a DataSource should be taken from the DataSourceComponent.
• login-timeout-duration (optional) — the maximum java.time.Duration to wait while attempting to connect to a database. A value of zero specifies that the timeout is the default system timeout if there is one; otherwise, it specifies that there is no timeout. When a DataSource object is created, the login timeout is initially zero.
• log-writer (optional) — a java.io.PrintWriter to set as the log writer for this data source, defaults to nil which disables logging.

Any additional options are passed along to the DataSourceComponent and then to make-data-source-fn when the component is started.

See javax.sql.DataSource

fixed-delay-scheduled-task clj

(fixed-delay-scheduled-task &
                            {:systems.thoughtfull.amalgam/keys
                               [task delay-duration initial-delay-duration
                                scheduled-executor-service]})

Make a new fixed delay ScheduledTaskComponent wrapping a ScheduledFuture.

• :task — a no argument function to run as a scheduled task.
• :delay-duration — java.time.Duration from the end of one run to the start of the next
• :initial-delay-duration (optional) — java.time.Duration to wait before the first run of task, defaults to 0
• :scheduled-executor-service (optional) — ScheduledExecutorService to use to schedule task. If not specified then a single thread scheduled-thread-pool component is started when this component is started and stopped when this component is stopped.

See java.util.concurrent.ScheduledThreadPoolExecutor

fixed-rate-scheduled-task clj

(fixed-rate-scheduled-task &
                           {:keys [task period-duration initial-delay-duration
                                   scheduled-executor-service]})

Make a new fixed rate ScheduledTaskComponent wrapping a ScheduledFuture.

• :task — a no argument function to run as a scheduled task.
• :period-duration — java.time.Duration from the start of one run to the start of the next
• :initial-delay-duration (optional) — java.time.Duration to wait before the first run of task, defaults to 0
• :scheduled-executor-service (optional) — ScheduledExecutorService to use to schedule task. If not specified then a single thread scheduled-thread-pool component is started when this component is started and stopped when this component is stopped.

See java.util.concurrent.ScheduledThreadPoolExecutor

function clj macro

(function & fn-tail)

A macro taking a fn-tail and making a component that collects its configuration and dependencies into a map and when started passes them as the first argument to a function made from the fn-tail.

Example:

user> (def f (component/using (amalgam/function [deps c] (assoc deps :c c)) [:a :b]))
#'user/f
user> (def system (-> (component/system-map :f f :a 1 :b 2) component/start))
#'user/system
user> ((:f system) 3)
{:a 1, :b 2, :c 3}

function* clj

(function* f)

A component that collects its configuration and dependencies into a map and when started passes them as the first argument to the given function.

Example:

user> (defn do-something [deps c] (assoc deps :c c))
#'user/do-something
user> (def f (component/using (amalgam/function* do-something) [:a :b]))
#'user/f
user> (def system (-> (component/system-map :f f :a 1 :b 2) component/start))
#'user/system
user> ((:f system) 3)
{:a 1, :b 2, :c 3}

make-component-fn clj deprecated

(make-component-fn & {:keys [start stop]})

Make a component constructor that takes options as keyword args and returns a component.

After this component has been started, stopping it resets it back to the options map. In other words,

(let [make-component (make-component-fn ...)
      c (make-component ...)]
  (assert (identical? c (component/stop (component/start c)))))

• start — (optional) a single argument function taking the options and returning a new instance of the component. The return value of start should be able to take metadata.
• stop — (optional) a single argument function taking the component and releasing resources. stop is side-effecting and its return value is ignored.

Example:

(def temp-file
  (amalgam/make-component-fn
    :start (fn [this] (assoc this :file (io/file (:path this))))
    :stop (fn [this] (io/delete-file (:file this) true))))
(def my-system (component/system-map :scratch-file (temp-file :path "/tmp/scratch")))

overwrite clj

(overwrite _v c)

Resolve current and configuration values by always taking the configuration value.

run-system clj

(run-system make-system read-config)

(run-system make-system read-config merge-fns)

Start a configured system, run it, and register a JVM shutdown hook to stop the system. Blocks until the system stop.

• make-system — no argument function returning a new system
• read-config — no argument function returning the configuration map. The configuration map should mirror the structure of the system.
• merge-fns (optional) — map mirroring the structure of both the system and configuration maps that contains merge functions to resolve a final value from the current value and configured value.

See configure start-system

scheduled-thread-pool clj

(scheduled-thread-pool &
                       {:keys [core-pool-size thread-factory
                               rejected-execution-handler remove-on-cancel?
                               continue-existing-periodic-tasks-after-shutdown?
                               execute-existing-delayed-tasks-after-shutdown?
                               convey-bindings? termination-wait-duration]})

Make a new scheduled thread pool. An unstarted scheduled thread pool is a record that collects configuration (see configure). Once started, it becomes a subclass of java.util.concurrent.ScheduledThreadPoolExecutor that also implements com.stuartsierra.component.Lifecycle.

Wher the scheduled thread pool is stopped, it reverts back to the configuration record. It can be started again with the same (or modified) configuration.

Calling stop on the configuration record or start on the scheduled thread pool is idempotent, i.e., they return this unmodified.

• :core-pool-size (optional) — number of threads to use to run scheduled tasks, defaults to 1
• :thread-factory (optional) — factory to use when executor creates a new thread, defaults to (Executors/defaultThreadFactory)
• :rejected-execution-handler (optional) — handler to use when execution is blocked because the thread and queue capacities are reached. The handler can be an instance of java.util.concurrent.RejectedExecutionHandler, a function of two arguments (a Runnable and a ThreadPoolExecutor), or one of :abort, :caller-runs, :discard-oldest, :discard, defaults to :abort.
• :remove-on-cancel? (optional) — if true immediately remove canceled tasks from the queue, otherwise wait until their delay elapses, defaults to false
• :continue-existing-periodic-tasks-after-shutdown? (optional) — if true continue executing existing periodic tasks even when this executor has been shutdown, otherwise immediately stop them, defaults to false
• :execute-existing-delayed-tasks-after-shutdown? (optional) — if true execute existing delayed tasks even when this executor has been shutdown, otherwise immediately cancel them, defaults to true
• :convey-bindings? (optional) — if true then convey thread local var bindings with tasks as they are submitted to the thread pool, defaults to true
• :termination-wait-duration (optional) — a java.time.Duration to wait for the thread pool to terminate when the component is stopped. A duration of zero means don't wait at all. If not specified, then wait indefinitely.

start-system clj

(start-system make-system read-config)

(start-system make-system read-config merge-fns)

Construct, configure, then start a system.

• make-system — no argument function returning a new system
• read-config — no argument function returning the configuration map. The configuration map should mirror the structure of the system.
• merge-fns (optional) — map mirroring the structure of both the system and configuration maps that contains merge functions to resolve a final value from the current value and configured value.

Example:

user> (amalgam/start-system #(component/system-map :component (map->Component {:foo :bar}))
        (constantly {:component {:foo :baz}})
        {:component {:foo amalgam/overwrite}})
{:component {:foo :baz}}

See configure

thread-pool clj

(thread-pool &
             {:keys [core-pool-size max-pool-size keep-alive-duration queue
                     thread-factory rejected-execution-handler convey-bindings?
                     termination-wait-duration]})

Make a new thread pool component. An unstarted thread pool component is a record that collects configuration (see configure). Once started, it becomes a subclass of java.util.concurrent.ThreadPoolExecutor that also implements com.stuartsierra.component.Lifecycle.

When the thread pool is stopped, it reverts back to the configuration record. It can be started again with the same (or modified) configuration.

Calling stop on the configuration record or start on the thread pool is idempotent, i.e., they return this unmodified.

• :core-pool-size (optional) — number of threads to keep in the pool, even if they are idle, defaults to 1
• :max-pool-size (optional) — maximum number of threads to allow in the pool, defaults to 1
• :keep-alive-duration (optional) — when the number of threads is greater than the core, the maximum java.time.Duration a thread waits for new tasks before terminating, defaults to 1 minute
• :queue (optional) — queue to use for holding tasks before they are executed, defaults to a java.util.concurrent.LinkedBlockingQueue with java.lang.Integer/MAX_VALUE capacity
• :thread-factory (optional) — factory to use when executor creates a new thread, defaults to (Executors/defaultThreadFactory)
• :rejected-execution-handler (optional) — handler to use when execution is blocked because the thread and queue capacities are reached. The handler can be an instance of java.util.concurrent.RejectedExecutionHandler, a function of two arguments (a Runnable and a ThreadPoolExecutor), or one of :abort, :caller-runs, :discard-oldest, :discard, defaults to :abort.
• :allow-core-thread-timeout? (optional) — if true then allow core threads to timeout and terminate if no tasks arrive within the keep alive time, otherwise core threads never terminate due to lack of incoming tasks, defaults to false
• :convey-bindings? (optional) — if true then convey thread local var bindings with tasks as they are submitted to the thread pool, defaults to true
• :termination-wait-duration (optional) — a java.time.Duration to wait for the thread pool to terminate when the component is stopped. A duration of zero means don't wait at all. If not specified, then wait indefinitely.

vector clj

(vector & dependency-keys)

A vector component that collects its dependencies into a vector.

Example:

user> (-> (component/system-map :v (amalgam/vector :a :b) :a 1 :b 2) component/start :v)
[1 2]