objection.core — riverford/objection 0.1.2-SNAPSHOT

Objection helps you manage graphs of stateful objects that acquire resources that are not managed by the garbage collector.

It is good for things like, connection pools, threads, thread pools, queues, channels etc.

Register objects and dependencies via register, construct.

Inspect objects with describe, id, data, id-seq, status.

Define singletons with defsingleton and resolve them with singleton.

alias clj/s

(alias x alias)

Aliases an object under the provided key, each alias can only be assigned to one object, so make sure it is unique.

Onced aliased the alias can be used interchangably with the object in objection functions on the object.

alter-data! clj/s

(alter-data! x f)

(alter-data! x f & args)

Applies f to the data for the object (i.e supplied under :data key on registry/construct). Saves and returns the new data.

construct clj/s macro

(construct opts & body)

Takes same opts as register, takes a body that constructs an object and returns it.

locks dependencies before running the body, so they cannot be stopped while this object is being constructed.

See-also: register

construct-call clj/s

(construct-call opts f)

data clj/s

(data x)

Returns the data associated with x, which can be a registered object, alias or id.

defsingleton clj/s macro

(defsingleton k opts? & body)

Defines a singleton that can be returned via (singleton k), if an instance already exists, it is returned - else the body is run to construct the instance.

If you would prefer to return an existing instance without the possibility of constructing the instance if it does not exist, use (object k).

Redefinition of a singleton will stop any existing instances.

Singletons are always implicitly registered after construction and they also receive an alias of the key used in the definition.

To introduce dependencies, stopfn, additional aliases etc, you can register or construct the object in the body of the singleton in the normal way.

Options:

:reload? (default true) If true will cause the singleton to restart on redefinition, otherwise a restart will require you to stop! any existing instance.

depend clj/s

(depend x dependency)

Makes x dependent on dependency, both can be registered object instances, aliases or ids. When you (stop! dependency) objection will make sure that x is stopped first.

dependencies clj/s

(dependencies x)

Returns the ids of dependencies of x.

dependents clj/s

(dependents x)

Returns the ids of the dependents of x.

depends? clj/s

(depends? x dependency)

Is x dependent on dependency?

describe clj/s

(describe x)

Returns information about x, which can be a registered object, alias or id.

IAutoStoppable clj/s≠ protocol

A protocol that can be extended to types in order to tell objection how to stop! them if a :stopfn is not provided on registry.

-stop! clj/s

(-stop! this)

Extend to types to provide a stop behaviour for objects of that type.

id clj/s

(id x)

Returns the id of the object if the object is registered.

You can pass the object instance, or an alias of the object.

id-seq clj/s

(id-seq)

Returns the seq of registered object ids.

need clj/s

(need x)

(need x error-message)

Tries to resolve x to a registered object, or singleton - throws an exception with the message if not possible.

object clj/s

(object x)

Returns a registered object, can pass either an id, id-prefix, alias or object instance.

put-singleton* clj/s

(put-singleton* k f meta)

register clj/s

(register obj)

(register obj opts)

Registers the object with objection and returns it, will assign it an id automatically.

An object can be practically anything, but would be expected to be something like a connection pool or a thread etc.

A registered object is kept alive by objection. Stop the object using the (stop! obj) function. Almost all objection functions can use the object itself, an id, id prefix or alias.

See-also: construct

Opts:

:name - a human friendly name to use for the object in display functions, doesn't have to be unique.

:aliases - a sequence of aliases to apply to the object, each alias can be used interchangeably with the object in objection functions.

:data - user supplied metadata about the object, retrieve later with (data obj).

:deps - a sequence of dependencies, supports passing objection ids, aliases or registered objects.

:stopfn - a function of the object that performs any shutdown logic. Alternatively implement IAutoStoppable for the type of the object.

rename! clj/s

(rename! x s)

Changes the :name of x to s. Then name is intended for display purposes only.

singleton clj/s

(singleton k)

Like (object k) but if a singleton is registered under the key k, it will be constructed if necessary in order to return the instance.

Singleton will always return an instance if one has been defined.

singleton-keys clj/s

(singleton-keys)

Returns the keys of each registered singleton.

status clj/s

(status)

Prints information about currently registered objects.

stop! clj/s

(stop! x)

(stop! x opts)

Runs the stopfn of x or the type specific AutoStoppable impl. e.g on AutoCloseable objects .close will be called.

Removes the object from the registry.

If an exception is thrown when stopping the object, it will remain in the registry, use the :force? option to unregister on error.

stop-all! clj/s

(stop-all!)

(stop-all! opts)

Stops all current registered objects. Options are the same as those accepted by 'stop!'.

undepend clj/s

(undepend x dependency)

Removes a dependency relationship between x and dependency, both of which can be registered object instances, aliases or ids.

with-open clj/s macro

(with-open binding & body)

Like clojure.core/with-open but works registered objects, calling their stop functions instead of .close.