Asynchronous programming through ports and channels.

Documentation needs more work.

Primary

<!

Available since version 1.0 (view source)

Usage:
  • (<! port)

Type signature:
  • (ISourcePort) → (Maybe PortVal)

Takes a value from source port and returns it. Will return nil if port is closed. Will park if nothing is available. Must be called inside a (go …​) block.

See also: take!, <!!, go, ISourcePort, put!, close!

<!!

Available since version 1.0 (view source)

Usage:
  • (<!! port)

Type signature:
  • (ISourcePort) → (Maybe PortVal)

Takes a value from source port and returns it. Will return nil if port is closed. Will block current thread if nothing is available.

>!

Available since version 1.0 (view source)

Usage:
  • (>! port val)

Type signature:
  • (ITargetPort ⨯ PortVal) → (NotPrimitive Boolean+)

Puts a non-nil val into target port. Will park if no buffer space is available. Must be called inside a (go …​) block. Returns true unless port is already closed.

nil values are not allowed. Use encode-nil to pass nil values.

>!!

Available since version 1.0 (view source)

Usage:
  • (>!! port val)

Type signature:
  • (ITargetPort ⨯ PortVal) → Boolean+

Puts a non-nil val into target port. Will block if no buffer space is available. Returns true unless port is already closed.

nil values are not allowed. Use encode-nil to pass nil values.

alt!

Available since version 1.0 (view source)

MACRO (alt! & clauses)

Makes a single choice between one of several channel operations, as if by alts!, returning the value of the result expr corresponding to the operation completed. Must be called inside a (go …​) block.

Each clause takes the form of:

  • channel-op[s] result-expr

where channel-ops is one of:

  • take-port - a single port to take

  • [take-port | [put-port put-val] …​] - a vector of ports as per alts!

  • :default | :priority - an option for alts!

and result-expr is either a list beginning with a vector, whereupon that vector will be treated as a binding for the [val port] return of the operation, else any other expression.

Usage example
(alt!
  [c t] ([val ch] (foo ch val))
  x ([v] v)
  [[out val]] :wrote
  :default 42)

Each option may appear at most once. The choice and parking characteristics are those of alts!.

See also: alts!!, alt!!, alts!

alt!!

Available since version 1.0 (view source)

MACRO (alt!! & clauses)

Like alt!, except as if by alts!!, will block until completed, and not intended for use in (go …​) blocks.

See also: alts!!, alts!, alt!

alts!

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (alts! ports & {:as opts})

Type signature:
  • ([(U ISourcePort [ITargetPort PortVal])] ⨯ Any) → [Any Any]

Completes at most one of several channel operations. Must be called inside a (go …​) block. ports is a vector of channel endpoints, which can be either a channel to take from or a vector of [channel-to-put-to val-to-put], in any combination. Takes will be made as if by <!, and puts will be made as if by >!.

Unless the :priority option is true, if more than one port operation is ready a non-deterministic choice will be made.

If no operation is ready and a :default value is supplied, [default-val :default] will be returned, otherwise alts! will park until the first operation to become ready completes.

Returns [val port] of the completed operation, where val is the value taken for takes, and nil for puts.

opts are passed as :key val …​ Supported options:

  • :default val - the value to use if none of the operations are immediately ready

  • :priority true - (default nil) when true, the operations will be tried in order.

there is no guarantee that the port exps or val exprs will be used, nor in what order should they be, so they should not be depended upon for side effects.

See also: alts!!, alt!!, alt!

alts!!

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (alts!! ports & {:as opts})

Type signature:
  • ([(U ISourcePort [ITargetPort PortVal])] ⨯ Any) → [Any Any]

Like alts!, except takes will be made as if by <!!, and puts will be made as if by >!!, will block until completed, and not intended for use in (go …​) blocks.

See also: alts!, alt!!, alt!

close!

Available since version 1.0 (view source)

Usage:
  • (close! port)

Type signature:
  • (ICloseablePort) → nil

Closes port. The port will no longer accept any puts (they will be ignored). Data in the port remains available for taking, until exhausted, after which takes will return nil. If there are any pending takes, they will be dispatched with nil. Closing a closed port is a no-op. Returns nil.

go

Available since version 1.0 (view source)

MACRO (go & body)

Asynchronously executes the body, returning immediately to the calling thread. Additionally, any visible calls to <!,>! and alt!/alts! channel operations within the body will block (if necessary) by 'parking' the calling thread rather than tying up an OS thread, Upon completion of the operation, the body will be resumed.

Returns a source port which will receive the result of the body when completed.

See also: go-loop, thread, thread-call

go-loop

Available since version 1.0 (view source)

MACRO (go-loop bindings & body)

Like (go (loop …​))

See also: go, thread, thread-call

put!

Available since version 1.0 (view source)

Usage:
  • (put! port val)

  • (put! port val fn1)

  • (put! port val fn1 always-dispatch?)

Type signatures:
  • (ITargetPort ⨯ PortVal) → Any

  • (ITargetPort ⨯ PortVal ⨯ (Fn [Any Boolean+])) → Any

  • (ITargetPort ⨯ PortVal ⨯ (Fn [Any Boolean+]) ⨯ Boolean+) → Any

Asynchronously puts a non-nil value into target port, calling fn1 (if supplied) when complete, passing false iff port is already closed. If always-dispatch? (default false) is false, and the put is immediately accepted, will call fn1 on calling thread. Returns true unless port is already closed.

nil values are not allowed. Use encode-nil to pass nil values.

take!

Available since version 1.0 (view source)

Usage:
  • (take! port fn1)

  • (take! port fn1 always-dispatch?)

Type signatures:
  • (ISourcePort ⨯ (Fn [Any (Maybe PortVal)])) → nil

  • (ISourcePort ⨯ (Fn [Any (Maybe PortVal)]) ⨯ Boolean+) → nil

Asynchronously takes a value from source port, passing it to fn1. Will pass nil if closed. If always-dispatch? (default false) is false, and value is immediately available, will call fn1 on calling thread. Returns nil.

See also: <!!, <!, ISourcePort, put!, close!

thread

Available since version 1.0 (view source)

MACRO (thread & body)

Executes the body in another thread, returning immediately to the calling thread. Returns a source port which will receive the result of the body when completed.

thread-call

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (thread-call f)

Type signature:
  • ((Fn [Any])) → ISourcePort

Executes f in another thread, returning immediately to the calling thread. Returns a source port which will receive the result of calling f when completed.

Ports

Master

Available since version 1.0 (view source)

not referred automatically

TYPE

A master port type. Will close automatically when garbage collected.

PortVal

Available since version 1.0 (view source)

VAR of type Signature

A type signature for values that can be processed by a port.

See also: <!!, <!, >!!, >!, put!, take!

chan

Available since version 1.0 (view source)

Usage:
  • (chan)

  • (chan buf-or-n)

  • (chan buf-or-n xform)

  • (chan buf-or-n xform exception-handler)

Type signatures:
  • () → (I ISourcePort ITargetPort ICloseablePort)

  • ((U Integer+ IMutableCollection)) → (I ISourcePort ITargetPort ICloseablePort)

  • ((U Integer+ IMutableCollection) ⨯ Any) → (I ISourcePort ITargetPort ICloseablePort)

  • ((U Integer+ IMutableCollection) ⨯ Any ⨯ (Fn [Any IException])) → (I ISourcePort ITargetPort ICloseablePort)

Creates a channel with an optional buffer, an optional transducer, and an optional exception-handler. If buf-or-n is a number, will create and use a fixed buffer of that size.

ex-handler must be a function of one argument. If an exception occurs during transformation it will be called with the IException as an argument, and any non-nil return value will be placed in the channel.

If a transducer is supplied a buffer must be specified.

close-only

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (close-only port)

Type signature:
  • (ICloseablePort) → ICloseablePort

Returns a close-only port from given closeable port.

See also: closeable-port?, close!

closeable-port?

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (closeable-port? x)

Type signature: Predicate

Returns true if object x satisfies ICloseablePort protocol, false otherwise.

master

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (master channel)

Type signature:
  • ((I IOpenAware ICloseablePort ITargetPort)) → (I IOpenAware ICloseablePort ITargetPort)

Returns a closeable target port from a given channel. Port automatically closes when finalized.

master?

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (master? x)

Type signature: Predicate

Returns true if object x is an instance of Master type, false otherwise.

promise-chan

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (promise-chan)

  • (promise-chan xform)

  • (promise-chan xform exception-handler)

Type signatures:
  • () → (I ISourcePort ITargetPort ICloseablePort)

  • (Any) → (I ISourcePort ITargetPort ICloseablePort)

  • (Any ⨯ (Fn [Any IException])) → (I ISourcePort ITargetPort ICloseablePort)

Creates a promise channel with an optional transducer xform, and an optional exception-handler. A promise channel can take exactly one value that consumers will receive. Once set, puts complete but val is dropped (no transfer). Consumers will block until either a value is placed in the channel or the channel is closed.

source

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (source channel)

Type signature:
  • ((I IOpenAware ISourcePort)) → (I IOpenAware ISourcePort)

Returns a source port from a given channel.

source-port?

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (source-port? x)

Type signature: Predicate

Returns true if object x satisfies ISourcePort protocol, false otherwise.

target

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (target channel)

Type signature:
  • ((I IOpenAware ITargetPort)) → (I IOpenAware ITargetPort)

Returns a target port from a given channel (or master port).

target-port?

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (target-port? x)

Type signature: Predicate

Returns true if object x satisfies ITargetPort protocol, false otherwise.

timeout

Available since version 1.0 (view source)

Usage:
  • (timeout duration)

Type signature:
  • ((U Integer+ IDuration)) → ISourcePort

Returns a source port that will close after duration.

Operations

into!

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (into! coll port)

Type signature:
  • (IRed ⨯ ISourcePort) → ISourcePort

Returns a source port containing the single (collection) result of the items taken from the port conjoined to the supplied coll. port must close before into! produces a result.

See also: to-chan, onto-chan!, reduce!

map!

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (map! mapf ports)

  • (map! mapf ports buf-or-n)

Type signatures:
  • (AnyFn ⨯ [ISourcePort]) → ISourcePort

  • (AnyFn ⨯ [ISourcePort] ⨯ (U Integer+ IMutableCollection)) → ISourcePort

Takes a function mapf and a collection of source ports, and returns a source port which contains the values produced by applying mapf to the set of first items taken from each source port, followed by applying mapf to the set of second items from each port, until any one of the ports is closed, at which point the output port will be closed.

The returned port will be unbuffered by default, or a buf-or-n can be supplied

merge!

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (merge! ports)

  • (merge! ports buf-or-n)

Type signatures:
  • ([ISourcePort]) → ISourcePort

  • ([ISourcePort] ⨯ (U Integer+ IMutableCollection)) → ISourcePort

Takes a collection of source ports and returns a source port which contains all values taken from them. The returned channel will be unbuffered by default, or a buf-or-n can be supplied. The port will close after all the source ports have closed.

See also: pipe!

onto-chan!

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (onto-chan! port coll)

  • (onto-chan! port coll keep-open?)

Type signatures:
  • (ITargetPort ⨯ IRed) → ISourcePort

  • (ITargetPort ⨯ IRed ⨯ Boolean+) → ISourcePort

Puts the contents of coll into the supplied target port.

Returns a source port which will close after the items are copied.

By default the port will be closed after the items are copied, but can be determined by the keep-open? parameter.

See also: to-chan, into!

pipe!

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (pipe! from to)

  • (pipe! from to keep-open?)

Type signatures:
  • (ISourcePort ⨯ ITargetPort) → ISourcePort

  • (ISourcePort ⨯ ITargetPort ⨯ Boolean+) → ISourcePort

Takes items from the from source port and supplies them to the to target port. By default, the to port will be closed when the from port closes, but can be determined by the keep-open? parameter.

See also: pipeline!

pipeline!

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (pipeline! n to xform from)

  • (pipeline! n to xform from keep-open?)

  • (pipeline! n to xform from keep-open? ex-handler)

Type signatures:
  • (Integer+ ⨯ ITargetPort ⨯ Any ⨯ ISourcePort) → ISourcePort

  • (Integer+ ⨯ ITargetPort ⨯ Any ⨯ ISourcePort ⨯ Boolean+) → ISourcePort

  • (Integer+ ⨯ ITargetPort ⨯ Any ⨯ ISourcePort ⨯ Boolean+ ⨯ AnyFn) → ISourcePort

Takes items from the from source port and supplies them to the to target port, subject to the transducer xform, with parallelism n. Because it is parallel, the transducer will be applied independently to each item, not across items, and may produce zero or more outputs per input. Outputs will be returned in order relative to the inputs. By default, the to port will be closed when the from port closes, but can be determined by the keep-open? parameter. Will stop consuming the from port if the to port closes.

This function should be used for computational parallelism. If you have multiple blocking operations to put in flight, use pipeline-blocking! instead. If you have multiple asynchronous operations to put in flight, use pipeline-async! instead.

pipeline-async!

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (pipeline-async! n to af from)

  • (pipeline-async! n to af from keep-open?)

Type signatures:
  • (Integer+ ⨯ ITargetPort ⨯ AnyFn ⨯ ISourcePort) → ISourcePort

  • (Integer+ ⨯ ITargetPort ⨯ AnyFn ⨯ ISourcePort ⨯ Boolean+) → ISourcePort

Takes items from the from source port and supplies them to the to target port, subject to the async function af, with parallelism n. af must be a function of two arguments, the first an input value and the second a target port on which to place the result(s). af must close the port before returning.

The presumption is that af will return immediately, having launched some asynchronous operation (i.e. in another thread) whose completion/callback will manipulate the result port. Outputs will be returned in order relative to the inputs. By default, the to port will be closed when the from port closes, but can be determined by the keep-open? parameter. Will stop consuming the from port if the to port closes.

pipeline-blocking!

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (pipeline-blocking! n to xform from)

  • (pipeline-blocking! n to xform from keep-open?)

  • (pipeline-blocking! n to xform from keep-open? ex-handler)

Type signatures:
  • (Integer+ ⨯ ITargetPort ⨯ Any ⨯ ISourcePort) → ISourcePort

  • (Integer+ ⨯ ITargetPort ⨯ Any ⨯ ISourcePort ⨯ Boolean+) → ISourcePort

  • (Integer+ ⨯ ITargetPort ⨯ Any ⨯ ISourcePort ⨯ Boolean+ ⨯ AnyFn) → ISourcePort

Like pipeline!, but for blocking operations.

reduce!

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (reduce! reducef init port)

Type signature:
  • ((Fn [Any Any Any]) ⨯ Any ⨯ ISourcePort) → ISourcePort

Returns a source port containing the single result of applying reducef to init and the first item from the port, then applying reducef to that result and the 2nd item, etc. reducef should be a function of 2 arguments. If the port closes without yielding items, returns init and reducef is not called.

port must close before reduce produces a result.

See also: into!

split!

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (split! pred port)

  • (split! pred port t-buf-or-n f-buf-or-n)

Type signatures:
  • (Predicate ⨯ ISourcePort) → [ISourcePort ISourcePort]

  • (Predicate ⨯ ISourcePort ⨯ (U Integer+ IMutableCollection) ⨯ (U Integer+ IMutableCollection)) → [ISourcePort ISourcePort]

Takes a pred and a source port and returns a vector of two source ports, the first of which will contain the values for which the predicate pred returned true, the second those for which it returned false.

The out ports will be unbuffered by default, or two buf-or-ns can be supplied. The ports will close after the port has closed.

take-n!

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (take-n! n port)

  • (take-n! n port buf-or-n)

Type signatures:
  • (Integer+ ⨯ ISourcePort) → ISourcePort

  • (Integer+ ⨯ ISourcePort ⨯ (U Integer+ IMutableCollection)) → ISourcePort

Returns a source port that will return, at most, n items from port. After n items have been returned, or port has been closed, the returned port will close.

The output port is unbuffered by default, unless buf-or-n is given.

See also: pipe!

to-chan

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (to-chan coll)

Type signature:
  • (IRed) → ISourcePort

Creates and returns a source port which contains the contents of coll, closing when exhausted.

See also: onto-chan, into!

Mult

In this section: mult! mult? tap! untap! untap-all!

mult!

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (mult! port)

Type signature:
  • (ISourcePort) → IMult

Creates and returns a mult(iple) of the supplied port. Ports containing copies of the port can be created with tap!, and detached with untap!.

Each item is distributed to all taps in parallel and synchronously, i.e. each tap must accept before the next item is distributed. Use buffering/windowing to prevent slow taps from holding up the mult.

Items received when there are no taps get dropped.

If a tap put throws an exception, it will be removed from the mult.

See also: mult?, tap!, untap!, untap-all!

mult?

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (mult? x)

Type signature: Predicate

Returns true if object x satisfies IMult protocol, false otherwise.

See also: IMult, mult!, tap!, untap!

tap!

Available since version 1.0 (view source)

Usage:
  • (tap! mult port)

  • (tap! mult port keep-open?)

Type signatures:
  • (IMult ⨯ ITargetPort) → nil

  • (IMult ⨯ ITargetPort ⨯ Boolean+) → nil

Copies the mult source onto the supplied target port.

By default the port will be closed when the source closes, but can be determined by the keep-open? parameter.

See also: mult?, mult!, untap!, untap-all!

untap!

Available since version 1.0 (view source)

Usage:
  • (untap! mult port)

Type signature:
  • (IMult ⨯ ITargetPort) → nil

Disconnects a target port from a mult.

See also: mult?, mult!, tap!, untap-all!

untap-all!

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (untap-all! mult)

Type signature:
  • (IMult) → nil

Disconnects all target ports from a mult.

See also: mult?, mult!, untap!, tap!

Mix

In this section: Mix admix! mix toggle! unmix! unmix-all!

Mix

Available since version 1.0 (view source)

not referred automatically

VAR of type Signature

A type signature for Mix object.

See also: mix

admix!

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (admix! mix port)

Type signature:
  • (Mix ⨯ ISourcePort) → nil

Adds source port as an input to the mix.

See also: Mix, mix!, unmix!, unmix-all!, toggle!

mix

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (mix out)

Type signature:
  • (ITargetPort) → Mix

Creates and returns a mix of one or more input ports which will be put on the supplied out target port. Input sources can be added to the mix with admix!, and removed with unmix!. A mix supports soloing, muting and pausing multiple inputs atomically using toggle!, and can solo using either muting or pausing as determined by :solo-mode value in the configuration.

Each port can have zero or more boolean modes set via toggle!:

  • :solo - when true, only this (ond other soloed) port(s) will appear in the mix output port. :mute and :pause states of soloed ports are ignored. If :solo-mode is :mute, non-soloed ports are muted, if :pause, non-soloed ports are paused.

  • :mute - muted ports will have their contents consumed but not included in the mix

  • :pause - paused ports will not have their contents consumed (and thus also not included in the mix)

toggle!

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (toggle! mix state-map)

Type signature:
  • (Mix ⨯ {ISourcePort KeywordMap}) → nil

Atomically sets the state(s) of one or more ports in a mix. The state-map is a map of channels → channel-state-map.

A channel-state-map is a map of attrs → boolean, where attr is one or more of :mute, :pause or :solo. Any states supplied are merged with the current state.

Ports can be added to a mix via toggle!, which can be used to add ports in a particular (e.g. paused) state.

See also: Mix, admix!, unmix!, unmix-all!, mix!

unmix!

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (unmix! mix port)

Type signature:
  • (Mix ⨯ ISourcePort) → nil

Removes port as an input to the mix.

See also: Mix, admix!, mix!, unmix-all!, toggle!

unmix-all!

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (unmix-all! mix)

Type signature:
  • (Mix) → nil

Removes all inputs from the mix

See also: Mix, admix!, unmix!, mix!, toggle!

Pub

In this section: pub! pub? sub! unsub! unsub-all!

pub!

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (pub! port topic-fn)

  • (pub! port topic-fn buf-fn)

Type signatures:
  • (ISourcePort ⨯ (Fn [Any PortVal])) → IPub

  • (ISourcePort ⨯ (Fn [Any PortVal]) ⨯ (Fn [(U Integer+ IMutableCollection) Any])) → IPub

Creates and returns a pub(lication) of the supplied source port, partitioned into topics by the topic-fn. topic-fn will be applied to each value on the port and the result will determine the 'topic' on which that value will be put.

Ports can be subscribed to receive copies of topics using sub!, and unsubscribed using unsub!. Each topic will be handled by an internal mult on a dedicated channel. By default these internal channels are unbuffered, but a buf-fn can be supplied which, given a topic, creates a buffer with desired properties.

Each item is distributed to all subs in parallel and synchronously, i.e. each sub must accept before the next item is distributed. Use buffering/windowing to prevent slow subs from holding up the pub.

Items received when there are no matching subs get dropped.

If buf-fns are used then each topic is handled asynchronously, i.e. if a port is subscribed to more than one topic it should not expect them to be interleaved identically with the source.

See also: pub?, sub!, unsub!, unsub-all!

pub?

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (pub? x)

Type signature: Predicate

Returns true if object x satisfies IPub protocol, false otherwise.

See also: IPub, pub!, sub!

sub!

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (sub! pub topic port)

  • (sub! pub topic port keep-open?)

Type signatures:
  • (IPub ⨯ Any ⨯ ITargetPort) → nil

  • (IPub ⨯ Any ⨯ ITargetPort ⨯ Boolean+) → nil

Subscribes a port to a topic of a pub.

By default the port will be closed when the source closes, but can be determined by the keep-open? parameter.

See also: pub?, pub!, unsub!, unsub-all!

unsub!

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (unsub! pub topic port)

Type signature:
  • (IPub ⨯ Any ⨯ ITargetPort) → nil

Unsubscribes a port from a topic of a pub.

See also: pub?, sub!, pub!, unsub-all!

unsub-all!

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (unsub-all! pub)

  • (unsub-all! pub topic)

Type signatures:
  • (IPub) → nil

  • (IPub ⨯ Any) → nil

Unsubscribes all ports from a pub, or all ports subscribed to topic of a pub.

See also: pub?, sub!, unsub!, pub!

Other

default-port-executor

Available since version 1.0 (view source)

not referred automatically

VAR of type Var

Dynamic var holding default port executor.

Not yet fully integrated.

fn-handler

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (fn-handler f)

  • (fn-handler f blockable?)

Type signatures:
  • (AnyFn) → Any

  • (AnyFn ⨯ Boolean+) → Any

Returns a fn handler created from a given function f. Returned handler can be used as an arg in source/target ports' protocol methods.

Low level function.