boot.pod — boot/pod 2.8.0

add-classpath clj

(add-classpath jar-or-dir)

(add-classpath jar-or-dir classloader)

A corollary to the (deprecated) add-classpath in clojure.core. This implementation requires a java.io.File or String path to a jar file or directory, and will attempt to add that path to the right classloader (with the search rooted at the current thread's context classloader).

add-dependencies clj

(add-dependencies env)

Resolve dependencies specified in the boot environment env and add their jars to the classpath.

add-dependencies-in clj

(add-dependencies-in pod env)

Resolve dependencies specified in the boot environment env and add their jars to the classpath in the pod.

add-dependencies-worker clj

(add-dependencies-worker env)

Resolve dependencies specified in the boot environment env and add their jars to the classpath in the worker pod.

add-shutdown-hook! clj

(add-shutdown-hook! f)

Adds f to the global queue of shutdown hooks for this instance of boot. Note that boot may be running inside another instance of boot, so shutdown hooks must be handled carefully as the JVM will not necessarily exit when this boot instance is finished.

Functions added via add-shutdown-hook! will be processed at the correct time (i.e. when boot is finished in the case of nested instances of boot, or when the JVM exits otherwise).

apply-exclusions clj

(apply-exclusions excl [p v & opts :as dep])

Merges the seq of dependency ids excl into the :exclusions of the dependency vector dep, creating the :exclusions key and deduplicating as necessary.

apply-global-exclusions clj

(apply-global-exclusions excl deps)

Merges the seq of dependency ids excl into all dependency vectors in deps. See apply-exclusions.

call-in* clj

(call-in* expr)

(call-in* pod expr)

Low-level interface by which expressions are evaluated in other pods. The two-arity version is invoked in the caller with a pod instance and an expr form. The form is serialized and the one-arity version is invoked in the pod with the serialized expr, which is deserialized and evaluated. The result is then serialized and returned to the two-arity where it is deserialized and returned to the caller. The print-meta binding determines whether metadata is transmitted between pods.

The expr is expected to be of the form (f & args). It is evaluated in the pod by resolving f and applying it to args.

Note: Since forms must be serialized to pass from one pod to another it is not always appropriate to include metadata, as metadata may contain eg. File objects which are not printable/readable by Clojure.

caller-namespace clj/s macro

(caller-namespace)

When this macro is used in a function, it returns the namespace of the caller of the function.

canonical-coord clj

(canonical-coord [id & more :as coord])

Given a dependency coordinate of the form [id version ...], returns the canonical form, i.e. the id symbol is not fully qualified when the artifact and group ids are the same.

For example: (canonical-coord '[foo/foo "1.2.3"]) ;=> [foo "1.2.3"] (canonical-coord '[foo/bar "1.2.3"]) ;=> [foo/bar "1.2.3"]

canonical-id clj

(canonical-id id)

Given a project id symbol, returns the canonical form, with the group id as the namespace of the resulting symbol only if it's not the same as the artifact id.

Examples: (canonical-id 'foo) ;=> 'foo (canonical-id 'foo/foo) ;=> 'foo (canonical-id 'foo/bar) ;=> 'foo/bar

classloader-hierarchy clj

(classloader-hierarchy)

(classloader-hierarchy tip)

Returns a seq of classloaders, with the tip of the hierarchy first. Uses the current thread context ClassLoader as the tip ClassLoader if one is not provided.

classloader-resources clj

(classloader-resources resource-name)

(classloader-resources classloaders resource-name)

Returns a sequence of [classloader url-seq] pairs representing all of the resources of the specified name on the classpath of each classloader. If no classloaders are given, uses the classloader-heirarchy, in which case the order of pairs will be such that the first url mentioned will in most circumstances match what clojure.java.io/resource returns.

concat-merger clj

(concat-merger prev new out)

Reads the InputStreams prev and new as strings and appends new to prev, separated by a single newline character. The result is written to the OutputStream out.

coord->map clj

(coord->map [p v & more])

Returns the map representation for the given dependency vector. The map will include :project and :version keys in addition to any other keys in the dependency vector (eg., :scope, :exclusions, etc).

copy-dependency-jar-entries clj

(copy-dependency-jar-entries env outdir coord & regexes)

Resolve all dependencies and transitive dependencies of the dependency given by the dep vector coord (given the boot environment configuration env), and explode them into the outdir directory. The outdir directory will be created if necessary and last modified times of jar entries will be preserved. If the optional Patterns, regexes, are specified only entries whose paths match at least one regex will be extracted to outdir.

copy-resource clj

(copy-resource resource-path out-path)

Copies the contents of the classpath resource at resource-path to the path or File out-path on the filesystem, preserving last modified times when possible. The copy operation is not atomic.

copy-url clj

(copy-url url-str out-path & {:keys [cache] :or {cache true}})

Copies the URL constructed from url-str to the path or File out-path. When the :cache option is false caching of URLs is disabled.

data clj

Set by boot.App/newCore, may be a ConcurrentHashMap for sharing data between instances of Boot that are running inside of Boot.

default-dependencies clj

(default-dependencies deps {:keys [dependencies] :as env})

Adds default dependencies given by deps to the :dependencies in env, but favoring dependency versions in env over deps in case of conflict.

dependency-loaded? clj

(dependency-loaded? [project & _])

Given a dependency coordinate of the form [id version ...], returns a URL for the pom.properties file in the dependency jar, or nil if the dependency isn't on the classpath.

dependency-pom-properties clj

(dependency-pom-properties coord)

Given a dependency coordinate of the form [id version ...], returns a Properties object corresponding to the dependency jar's pom.properties file.

dependency-pom-properties-map clj

(dependency-pom-properties-map coord)

Given a dependency coordinate of the form [id version ...], returns a map of the contents of the jar's pom.properties file.

destroy-pod clj

(destroy-pod pod)

Closes open resources held by the pod, making the pod eligible for GC.

env clj

This pod's boot environment.

eval-fn-call clj

(eval-fn-call [f & args])

Given an expression of the form (f & args), resolves f and applies f to args.

eval-in* clj

(eval-in* expr)

(eval-in* pod expr)

Low-level interface by which expressions are evaluated in other pods. The two-arity version is invoked in the caller with a pod instance and an expr form. The form is serialized and the one-arity version is invoked in the pod with the serialized expr, which is deserialized and evaluated. The result is then serialized and returned to the two-arity where it is deserialized and returned to the caller. The print-meta binding determines whether metadata is transmitted between pods.

Unlike call-in*, expr can be any expression, without the restriction that it be of the form (f & args).

Note: Since forms must be serialized to pass from one pod to another it is not always appropriate to include metadata, as metadata may contain eg. File objects which are not printable/readable by Clojure.

eval-in-callee clj

(eval-in-callee caller-pod callee-pod expr)

Implementation detail. This is the callee side of the boot.pod/with-pod mechanism (i.e. this is the function that's called in the pod to perform the work).

eval-in-caller clj

(eval-in-caller caller-pod callee-pod expr)

Implementation detail. This is the caller side of the boot.pod/with-pod mechanism (i.e. this is the function that's called in the caller pod to send work to the callee pod so the callee pod can perform the work).

extend-addable-classloader clj

(extend-addable-classloader)

Opens up the class loader used to create the shim for modification. Once seal-app-classloader is called, this will be the highest class loader user code can modify.

This function is called during Boot's bootstrapping phase, and shouldn't be needed in client code under normal circumstances.

extract-ids clj

(extract-ids sym)

Given a dependency symbol sym, returns a vector of [group-id artifact-id].

first-wins-merger clj

(first-wins-merger prev _ out)

Writes the InputStream prev to the OutputStream out.

full-id clj

(full-id id)

Given a project id symbol, returns the fully qualified form, with the group id as the namespace of the resulting symbol and the artifact id as the name.

For example: (full-id 'foo) ;=> foo/foo (full-id 'foo/bar) ;=> foo/bar

get-classpath clj

(get-classpath)

(get-classpath classloaders)

Returns the effective classpath (i.e. not the value of (System/getProperty "java.class.path") as a seq of URL strings.

Produces the classpath from all classloaders by default, or from a collection of classloaders if provided. This allows you to easily look at subsets of the current classloader hierarchy, e.g.:

(get-classpath (drop 2 (classloader-hierarchy)))

get-pods clj

(get-pods name-or-pattern)

(get-pods name-or-pattern unique?)

Returns a seq of pod references whose names match name-or-pattern, which can be a string or a Pattern. Strings are matched by equality, and Patterns by re-find. The unique? option, if given, will cause an exception to be thrown unless exactly one pod matches.

into-merger clj

(into-merger prev new out)

Reads the InputStreams prev and new as EDN, uses clojure.core/into to merge the data from new into prev, and writes the result to the OutputStream out.

jar-entries clj

(jar-entries path-or-jarfile & {:keys [cache] :or {cache true}})

Given a path to a jar file, returns a list of [resource-path, resource-url] string pairs corresponding to all entries contained the jar contains.

jar-entries* clj

(jar-entries* path-or-jarfile)

Returns a vector containing vectors of the form [name url-string] for each entry in the jar path-or-jarfile, which can be a string or File.

jar-entries-memoized* clj

Memoized version of jar-entries*.

jars-dep-graph clj

(jars-dep-graph env)

Returns a dependency graph for all jar file dependencies specified in the boot environment map env, including transitive dependencies.

jars-in-dep-order clj

(jars-in-dep-order env)

Returns a seq of all jar file dependencies specified in the boot environment map env, including transitive dependencies, and in dependency order.

Dependency order means, eg. if jar B depends on jar A then jar A will appear before jar B in the returned list.

lifecycle-pool clj

(lifecycle-pool size create destroy & {:keys [priority]})

Creates a function implementing a lifecycle protocol on a pool of stateful objects. The pool will attempt to maintain at least size objects, creating new objects via the create function as needed. The objects are retired when no longer needed, using the given destroy function. The :priority option can be given to specify the priority of the worker thread (default NORM_PRIORITY).

The pool maintains a queue of objects with the head of the queue being the "current" object. The pool may be "refreshed": the current object is destroyed and the next object in the queue is promoted to current object.

The returned function accepts one argument, which can be :shutdown, :take, or :refresh, or no arguments.

none Returns the current object.

:shutdown Stop worker thread and destroy all objects in the pool.

:take Remove the current object from the pool and return it to the caller without destroying it. The next object in the pool will be promoted. Note that it is the responsibility of the caller to properly dispose of the returned object.

:refresh Destroy the current object and promote the next object.

make-pod clj

(make-pod)

(make-pod {:keys [directories dependencies] :as env} & {:keys [name data]})

Returns a newly constructed pod. A boot environment configuration map, env, may be given to initialize the pod with dependencies, directories, etc.

The :name option sets the name of the pod. Default uses the namespace of the caller as the pod's name.

The :data option sets the boot.pod/data object in the pod. The data object is used to coordinate different pods, for example the data object could be a BlockingQueue or ConcurrentHashMap shared with other pods. Default uses boot.pod/data from the current pod.

make-pod-cp clj

(make-pod-cp classpath & {:keys [name data]})

Returns a new pod with the given classpath. Classpath may be a collection of java.lang.String or java.io.File objects.

The :name and :data options are the same as for boot.pod/make-pod.

NB: The classpath must include Clojure (either clojure.jar or directories), but must not include Boot's pod.jar, Shimdandy's impl, or Dynapath. These are needed to bootstrap the pod, have no transitive dependencies, and are added automatically.

map->coord clj

(map->coord {:keys [project version] :as more})

Returns the dependency vector for the given map representation. The project and version will be taken from the values of the :project and :version keys and all other keys will be appended pairwise.

modifiable-classloader? clj

(modifiable-classloader? cl)

Returns true iff the given ClassLoader is of a type that satisfies the dynapath.dynamic-classpath/DynamicClasspath protocol, and it can be modified.

non-caching-url-input-stream clj

(non-caching-url-input-stream url-str)

Returns an InputStream from the URL constructed from url-str, with caching disabled. This is useful for example when accessing jar entries in jars that may change.

outdated clj

(outdated env & {:keys [snapshots]})

Returns a seq of dependency vectors corresponding to outdated dependencies in the dependency graph associated with the boot environment env. If the :snapshots option is given SNAPSHOT versions will be considered, otherwise only release versions will be considered.

pod-id clj

Each pod is numbered in the order in which it was created.

pod-name clj

(pod-name pod)

(pod-name pod new-name)

Returns pod's name if called with one argument, sets pod's name to new-name and returns new-name if called with two arguments.

pod-pool clj

(pod-pool env & {:keys [size init destroy]})

Creates a pod pool service. The service maintains a pool of prebuilt pods with a current active pod and a number of pods in reserve, warmed and ready to go (it takes ~2s to load clojure.core into a pod).

Pool Service API:

The pod-pool function returns a pod service instance, which is itself a Clojure function. The pod service function can be called with no arguments or with :refresh or :shutdown.

Calling the function with no arguments produces a reference to the current pod. Expressions can be evaluated in this pod via with-eval-in, etc.

Calling the function with the :refresh argument swaps out the current pod, destroys it, and promotes a pod from the reserve pool. A new pod is created asynchronously to replenish the reserve pool.

Calling the function with the :shutdown argument destroys all pods in the pool and shuts down the service.

Options:

:size The total number of pods to be maintained in the pool. Default size is 2. :init A function that is called when a new pod is created. Takes the new pod as an argument, is evaluated for side effects only. :destroy A function that is called when a pod is destroyed. Takes the pod to be destroyed as an argument, is evaluated for side effects before pod is destroyed.

pods clj

A WeakHashMap whose keys are all of the currently running pods.

pom-properties clj

(pom-properties jarpath)

Given a path or File jarpath, finds the jar's pom.properties file, reads it, and returns the loaded Properties object. An exception is thrown if multiple pom.properties files are present in the jar.

pom-properties-map clj

(pom-properties-map prop-or-jarpath)

Returns a map of the contents of the pom.properties pom-or-jarpath, where pom-or-jarpath is either a slurpable thing or a Properties object.

pom-xml clj

(pom-xml jarpath)

(pom-xml jarpath pompath)

Returns a the pom.xml contents as a string. If only jarpath is given the jar must contain exactly one pom.xml file. If pompath is a file that exists the contents of that file will be returned. Otherwise, pompath must be the resource path of the pom.xml file in the jar.

pom-xml-map clj

(pom-xml-map jarpath)

(pom-xml-map jarpath pompath)

Returns a map of pom data from the pom.xml in the jar specified jarpath, which can be a string or File. If pompath is not specified there must be exactly one pom.xml in the jar. Otherwise, the pom.xml will be extracted from the jar by the resource path specified by pompath.

require-in clj

(require-in pod ns)

Evaluates (require 'ns) in the pod. Avoid this function.

resolve-dependencies clj

(resolve-dependencies env)

Returns a seq of maps of the form {:jar <path> :dep <dependency vector>} corresponding to the fully resolved dependency graph as specified in the env, where env is the boot environment (see boot.core/get-env). The seq of dependencies includes all transitive dependencies.

resolve-dependency-jar clj

(resolve-dependency-jar env coord)

Returns the path to the jar file associated with the dependency specified by coord, given the boot environment configuration env.

resolve-dependency-jars clj

(resolve-dependency-jars env & [ignore-clj?])

Returns a seq of File objects corresponding to the jar files associated with the fully resolved dependency graph as specified in the env, where env is the boot environment (see boot.core/get-env). If ignore-clj? is specified Clojure will be excluded from the result (the clojure dependency is identified by the BOOT_CLOJURE_NAME environment setting, which defaults to org.clojure.clojure).

resolve-nontransitive-dependencies clj

(resolve-nontransitive-dependencies env dep)

Returns a seq of maps of the form {:jar <path> :dep <dependency vector>} for the dependencies of dep, excluding transitive dependencies (i.e. the dependencies of dep's dependencies).

resolve-release-versions clj

(resolve-release-versions env)

Given environment map env, replaces the versions of dependencies that are specified with the special Maven RELEASE version with the concrete versions of the resolved dependencies.

resource-last-modified clj

(resource-last-modified resource-path)

Returns the last modified time (long, milliseconds since epoch) of the classpath resource at resource-path. A result of 0 usually indicates that the modification time was not available for this resource.

resources clj

(resources resource-name)

(resources classloaders resource-name)

Returns a sequence of URLs representing all of the resources of the specified name on the effective classpath. This can be useful for finding name collisions among items on the classpath. In most circumstances, the first of the returned sequence will be the same as what clojure.java.io/resource returns.

seal-app-classloader clj

(seal-app-classloader)

Implements the DynamicClasspath protocol to the AppClassLoader and boot's ParentClassLoader classes such that instances of those classes will refuse attempts at runtime modification by libraries that do so via dynapath1. The system class loader is of the type AppClassLoader under Java < 9, and the top-level class loader used by boot is a ParentClassLoader.

The purpose of this is to ensure that Clojure libraries do not pollute the higher-level class loaders with classes and interfaces created dynamically in their Clojure runtime. This is essential for pods to work properly2.

This function is called during Boot's bootstrapping phase, and shouldn't be needed in client code under normal circumstances.

sealed-classloader-fns clj

send! clj

(send! form)

This is ALPHA status, it may change, be renamed, or removed.

set-data! clj

(set-data! x)

set-pod-id! clj

(set-pod-id! x)

set-pods! clj

(set-pods! x)

set-this-pod! clj

(set-this-pod! x)

set-worker-pod! clj

(set-worker-pod! x)

shutdown-hooks clj

Atom containing shutdown hooks to be performed at exit. This is used instead of Runtime.getRuntime().addShutdownHook() by boot so that these hooks can be called without exiting the JVM process, for example when boot is running in boot. See #'boot.pod/add-shutdown-hook! for more info.

standard-jar-exclusions clj

Entries matching these Patterns will not be extracted from jars when they are exploded during uberjar construction.

standard-jar-mergers clj

A vector containing vectors of the form [<path-matcher> <merger-fn>]. These pairs will be used to decide how to merge conflicting entries when exploding or creating jar files. See boot.task.built-in/uber for more info.

this-pod clj

A WeakReference to this pod's shim instance.

unpack-jar clj

(unpack-jar jar-path dest-dir & opts)

Explodes the jar identified by the string or File jar-path, copying all jar entries to the directory given by the string or File dest-dir. The directory will be created if it does not exist and jar entry modification times will be preserved. Files will not be written atomically.

with-call-in clj/s macro

(with-call-in pod expr)

Given a pod and an expr of the form (f & args), resolves f in the pod, applies it to args, and returns the result to the caller. The expr may be a template containing the ~ (unquote) and ~@ (unquote-splicing) reader macros. These will be evaluated in the calling scope and substituted in the template like the ` (syntax-quote) reader macro.

Note: Unlike syntax-quote, no name resolution is done on the template forms.

Note2: The macro returned value will be nil unless it is printable/readable. For instance, returning File objects will not work as they are not printable/readable by Clojure.

with-call-worker clj/s macro

(with-call-worker expr)

Like with-call-in, evaluating expr in the worker pod.

with-eval-in clj/s macro

(with-eval-in pod & body)

Given a pod and an expr, evaluates the body in the pod and returns the result to the caller. The body may be a template containing the ~ (unquote) and ~@ (unquote-splicing) reader macros. These will be evaluated in the calling scope and substituted in the template like the ` (syntax-quote) reader macro.

Note: Unlike syntax-quote, no name resolution is done on the template forms.

Note2: The macro returned value will be nil unless it is printable/readable. For instance, returning File objects will not work as they are not printable and readable by Clojure.

with-eval-worker clj/s macro

(with-eval-worker & body)

Like with-eval-in, evaluates the body in the worker pod.

with-invoke-in clj/s macro

(with-invoke-in pod [sym & args])

Given a pod, a fully-qualified symbol sym, and args which are Java objects, invokes the function denoted by sym with the given args. This is a low-level interface--args are not serialized before being passed to the pod and the result is not deserialized before being returned. Passing Clojure objects as arguments or returning Clojure objects from the pod will result in undefined behavior.

This macro correctly handles the case where pod is the current pod without thread binding issues: in this case the invocation will be done in another thread.

with-invoke-worker clj/s macro

(with-invoke-worker [sym & args])

Like with-invoke-in, invoking the function in the worker pod.

with-pod clj/s macro

(with-pod pod & body)

Like boot.pod/with-eval-in but with the ability to pass most types between the caller and the pod.

Supports the normal types that are recognized by the Clojure reader, plus functions, records, and all Java types. (The namespace in which the record type is defined must be on the classpath in the pod.)

with-worker clj/s macro

(with-worker & body)

Like with-pod, evaluates the body in the worker pod.

worker-pod clj

A reference to the boot worker pod. All pods share access to the worker pod singleton instance.