nl.jomco.resources — nl.jomco/with-resources 0.1.2

close-on-shutdown! clj

(close-on-shutdown! resource)

Register a shutdown hook that will close the resource.

When the JVM is shut down, the resource's close method will be called.

Returns resource with an additional close function that will remove the shutdown hook. This means the following will work and clean up the hook if the JVM was not shut down during the with-resources call:

(with-resources [r (close-on-shutdown! (open-some-resource))]
  (do-some-long-running-thing-with r))

See also closeable, defresource.

closeable clj

(closeable x)

(closeable x close-fn)

Returns x with an nl.jomco.resources/close function added.

Result is a resource. x must be a clojure object that supports metadata. When x is closed, close-fn will be called with x as its only argument. If x already provides a close function, it will be called after close-fn.

If close-fn is not provided, identity will be used as close-fn.

(with-resources [x (closeable {:my "object") cleanup-object)]
   ...)

defresource clj macro

(defresource symbol doc-string? init-resource?)

Creates and interns a global var that will hold a resource.

defresource is intended for REPL use. Like clojure.core/def; var will be named by symbol. If init-resource is provided, it is evaluated and the root-binding of the var is set to the result. A doc-string may be provided.

Registers a shutdown hook to close the resource, with close-on-shutdown!.

If var already holds a resource, it will be closed before evaluating init-resource and assigning the new resource. This will also unregister the shutdown hook for the previous resource.

(defresource my-db
   "A database connection"
   (init-db ...))

mk-system clj macro

(mk-system bindings & body)

Bind opened resources to symbols in order of appearance.

If an exception is raised, ensures that opened resources are closed in reverse order and re-raises the exception.

The result of the evaluation -- a system, which can be any clojure IObj, normally a clojure collection -- is wrapped in a closeable that will close all bound resources, so that when the returned object is closed, all the bound resources are closed in reverse order of binding.

To provide access to the bound resources, it is recommeneded to return the resources in a system map or record:

(mk-system [db (open-db ...) ;; initialize resources
            h  (create-handler db) ;; pass dependencies
            s  (run-server handler)]
  ;; return map of sub-resources to use as the system
  {:db db
    :handler h
    :server s})

If no body is provided, a map is returned with key-value pairs generated from bindings:

(mk-system [db (open-db ...) ;; initialize resources
            h  (create-handler db) ;; pass dependencies
            s  (run-server handler)])
;; => {:db .. :h ... :s ..}

Resource clj protocol

Protocol defining a closeable resource.

Resources are opened items that must be closed. Any java.lang.AutoCloseable (including java.io.Closeable) is a resource.

Components that are started and should be stopped can extend Resource (via metadata or using extend-protocol) to implement the close method.

close clj

(close resource)

Close resource.

wait-until-interrupted clj

(wait-until-interrupted)

Block the current thread until it's interrupted.

If the thread is interrupted, returns true. Clears the interrupted status of the thread.

with-resources clj macro

(with-resources bindings & body)

bindings => [name init ...]

Evaluates body in a try expression with names bound to the values of the inits, and a finally clause that calls Resource protocol's (close name) on each name in reverse order.

This is equivalent to clojure's with-open, but allows objects to specify close behaviour via Resource protocol.

Like with-open, when exceptions are thrown during closing, the last thrown exception is raised from with-resources.

with-resources does not close bindings when the JVM is shut down. See close-on-shutdown!.