boot.pod

Namespace containing functions and vars related to pods, dependencies, jar files, and classloaders.

`add-classpath`

(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`

(add-dependencies env)

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

`add-dependencies-in`

(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`

(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!`

(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`

(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`

(apply-global-exclusions excl deps)

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

`call-in*`

(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`

(caller-namespace)

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

`canonical-coord`

(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 always fully qualified.

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

`classloader-hierarchy`

(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`

(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`

(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`

(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`

(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`

(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`

(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`

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

`default-dependencies`

(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?`

(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`

(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`

(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`

(destroy-pod pod)

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

`env`

This pod's boot environment.

`eval-fn-call`

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

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

`eval-in*`

(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`

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

FIXME: document this

`eval-in-caller`

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

FIXME: document this

`extract-ids`

(extract-ids sym)

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

`first-wins-merger`

(first-wins-merger prev _ out)

Writes the InputStream prev to the OutputStream out.

`get-classpath`

(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`

(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`

(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`

(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*`

(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*`

Memoized version of jar-entries*.

`jars-dep-graph`

(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`

(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`

(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`

(make-pod) (make-pod {:keys [directories dependencies], :as env})

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

`map->coord`

(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?`

(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`

(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`

(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`

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

`pod-name`

(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`

(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`

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

`pom-properties`

(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`

(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`

(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`

(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`

(require-in pod ns)

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

`resolve-dependencies`

(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`

(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`

(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`

(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`

(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`

(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`

(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
ame collisions among items on the classpath. In most circumstances, the
irst of the returned sequence will be the same as what clojure.java.io/resource
eturns.

`seal-app-classloader`

(seal-app-classloader)

Implements the DynamicClasspath protocol to the AppClassLoader class such
that instances of this class will refuse attempts at runtime modification
by libraries that do so via dynapath[1]. The system class loader is of the
type AppClassLoader.

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 properly[2].

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

[1]: https://github.com/tobias/dynapath
[2]: https://github.com/clojure-emacs/cider-nrepl/blob/36333cae25fd510747321f86e2f0369fcb7b4afd/README.md#with-jboss-asjboss-eapwildfly

`send!`

(send! form)

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

`set-data!`

(set-data! x)

FIXME: document this

`set-pod-id!`

(set-pod-id! x)

FIXME: document this

`set-pods!`

(set-pods! x)

FIXME: document this

`set-this-pod!`

(set-this-pod! x)

FIXME: document this

`set-worker-pod!`

(set-worker-pod! x)

FIXME: document this

`shutdown-hooks`

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`

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

`standard-jar-mergers`

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`

A WeakReference to this pod's shim instance.

`unpack-jar`

(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`

(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 ~ (unqupte) 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`

(with-call-worker expr)

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

`with-eval-in`

(with-eval-in pod & body)

Given a pod and an expr, evaluates expr in the pod and returns the result
to the caller. The expr may be a template containing the ~ (unqupte) 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-eval-worker`

(with-eval-worker & body)

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

`with-invoke-in`

(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`

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

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

`with-pod`

(with-pod pod & body)

FIXME: document this

`with-worker`

(with-worker & body)

FIXME: document this

`worker-pod`

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!