systems.thoughtfull.desiderata — systems.thoughtfull/desiderata 2.2.0

attempt clj

(attempt f retry? delay-fn)

Call f repeatedly with delays between each attempt until it succeeds or all attempts are exhausted.

• f — a function of no arguments to be called repeatedly.
• retry? — a function of two arguments, result and exception (respectively), either one or the other but not both will be non-nil. Result will be non-nil if an exception did not occur and exception will be non-nil if an exception did occur.
• delay-fn — a function of a single argument, the index of the last attempt, returning a java.time.Duration to delay before the next attempt or nil if attempts are exhausted. After the first attempt the argument will be 0 and the delay returned will be used before the first retry. After the first retry the argument will be 1 and the delay returned will be used before the second retry, etc.

Example:

user> (defn http-get
        "Simulate HTTP request"
        []
        (println (java.util.Date.))
        {:status 503})
#'user/http-get
user> (defn http-retry?
        "Retry certain exceptions and HTTP status codes."
        [result exception]
        (or (contains? #{503 504} (:status result))
            (contains? #{java.net.ConnectException} (class exception))))
#'user/http-retry?
user> (desiderata/attempt http-get
        http-retry?
        (-> (desiderata/exponential-backoff (java.time.Duration/ofSeconds 2))
          (desiderata/max-attempts 5)))
#inst "2025-07-27T10:07:44.600-00:00"
#inst "2025-07-27T10:07:46.601-00:00"
#inst "2025-07-27T10:07:50.602-00:00"
#inst "2025-07-27T10:07:58.603-00:00"
#inst "2025-07-27T10:08:14.604-00:00"
{:status 503}

See exponential-backoff, linear-backoff, fixed-delay, max-attempts, max-duration

defrecord clj macro

(defrecord name docstring? [& fields] & opts+specs)

Drop-in replacement for clojure.core/defrecord with extra functionality. See clojure.core/defrecord for details about core functionality.

As a relatively minor addition the factory function takes keyword arguments. Another somewhat minor addition, metadata on the name symbol is propagated to the factory functions. There are three other additions: a docstring, default values, and an initializer.

A docstring, if given, is appended to the docstring for both the factory and positional factory functions.

Example:

user> (desiderata/defrecord Widget
"A widget for frobbing gizmos.

width and height are in metric."
[width height])
user.Widget

user> (doc map->Widget)
-------------------------
user/map->Widget
([& {:keys [width height]}])
  Factory function for class user.Widget, taking a map of keywords to field values.

  A widget for frobbing gizmos.

  width and height are in metric.
nil

The :systems.thoughtfull.desiderata/defaults option can be given with a hash map to supply defaults. The hash map supplies default values for the declared fields (and extra non-field keys and values). Any values given as arguments to the factory or positional factory functions override these defaults.

Example:

user> (desiderata/defrecord Gizmo
[name]
::desiderata/defaults
{:name "Gizmo"
 :color :blue})
user.Gizmo

user> (->Gizmo "the Great")
{:name "the Great", :color :blue}

user> (map->Gizmo :texture :bumpy)
{:name "Gizmo", :color :blue, :texture :bumpy}

If a method with the same name as the defrecord is defined, it is used to as an initializer. After the record is constructed by the factory or positional factory function, it is given to the initializer and the result is returned from the factory or positional factory function. If the initializer does not return an instance of the type, an IllegalStateException is thrown.

Example:

user> (desiderata/defrecord Company
[debt equity]
(Company
  [this]
  (assoc this :gearing-ratio (/ debt equity))))
user.Company

user> (->Company 100 1000)
{:debt 100, :equity 1000, :gearing-ratio 1/10}

• name — name of the type
• docstring (optional) — appended to the docstrings of the factory and positional factory functions
• fields — names of the fields of the type
• opts+specs (optional) — options, interfaces, and methods

See clojure.core/defrecord

exponential-backoff clj

(exponential-backoff initial-duration)

Returns a function for use as delay-fn with attempt. The delay between each attempt will double.

fixed-delay clj

(fixed-delay fixed-duration)

Returns a function for use as delay-fn with attempt. The delay between each attempt will remain fixed at fixed-duration.

linear-backoff clj

(linear-backoff initial-duration incremental-duration)

Returns a function for use as delay-fn with attempt. The delay between each attempt will increase by incremental-duration.

max-attempts clj

(max-attempts delay-fn max-attempts)

Returns a function modifying delay-fn to end attempts after max-attempts have occured.

max-duration clj

(max-duration delay-fn max-duration)

Returns a function modifying delay-fn so the returned duration (if any) is never greater than max-duration.

set-default-uncaught-exception-handler-fn! clj

(set-default-uncaught-exception-handler-fn! uncaught-exception-handler-fn)

Set default Thread.UncaughtExceptionHandler to uncaught-exception-handler-fn after adapting it using uncaught-exception-handler. uncaught-exception-handler-fn should be a function of two arguments (thread and throwable). If uncaught-exception-handler-fn is nil, then the default uncaught exception handler is cleared.

• uncaught-exception-handler-fn — function of two arguments (thread and throwable) to set as the default Thread.UncaughtExceptionHandler after adapting it using uncaught-exception-handler. Returns nil if uncaught-exception-handler-fn is nil.

See Thread/setDefaultUncaughtExceptionHandler, Thread.UncaughtExceptionHandler

thread-factory clj

(thread-factory &
                {:keys [name convey-bindings? priority daemon?
                        uncaught-exception-handler-fn
                        inherit-inheritable-thread-locals?]})

Create java.util.concurrent.ThreadFactory.

• name (optional) — prefix for thread names, e.g., a name of "widget-pool" will create threads named "widget-pool-thread-N" where N increments each time a thread is created. If name is not given, it defaults to "pool-M" where M is incremented for each new thread factory.
• convey-bindings? (optional) — if true convey to created threads the bindings established when the thread factory was created, defaults to false.
• priority (optional) — initial thread priority for created threads, defaults to Thread/NORMAL_PRIORITY.
• daemon? (optional) — if true threads should be marked as daemon threads, defaults to false.
• uncaught-exception-handler-fn (optional) — function to set as a Thread.UncaughtExceptionHandler after adapting with uncaught-exception-handler. Bindings established when the thread factory is created are conveyed to uncaught-exception-handler-fn.
• inherit-inheritable-thread-locals? (optional) — if true, then new threads inherit initial values for InheritableThreadLocal from constructing thread, defaults to true. See java.util.Thread/new.

See java.util.concurrent.ThreadFactory, Thread.UncaughtExceptionHandler

uncaught-exception-handler clj

(uncaught-exception-handler uncaught-exception-handler-fn)

Adapt uncaught-exception-handler-fn to a Thread.UncaughtExceptionHandler. uncaught-exception-handler-fn should be a function of two arguments (thread and throwable). Returns nil if uncaught-exception-handler-fn is nil.

• uncaught-exception-handler-fn — function of two arguments (thread and throwable) to adapt as a Thread.UncaughtExceptionHandler. Returns nil if uncaught-exception-handler-fn is nil.

See Thread.UncaughtExceptionHandler