Liking cljdoc? Tell your friends :D

sci.impl.async-macro

Transforms async function bodies with await into Promise .then chains.

Supports await in:

  • let bindings: (let [x (await p)] ...)
  • do forms: (do (await p) ...)
  • arbitrary expressions: (inc (await p))
  • macros like -> are expanded first

Example: (defn ^:async foo [] (let [x (await (js/Promise.resolve 1))] (inc x)))

Transforms to: (defn foo [] (.then (js/Promise.resolve 1) (fn [x] (inc x))))

Transforms async function bodies with await into Promise .then chains.

Supports await in:
- let bindings: (let [x (await p)] ...)
- do forms: (do (await p) ...)
- arbitrary expressions: (inc (await p))
- macros like -> are expanded first

Example:
  (defn ^:async foo []
    (let [x (await (js/Promise.resolve 1))]
      (inc x)))

Transforms to:
  (defn foo []
    (.then (js/Promise.resolve 1) (fn [x] (inc x))))
raw docstring

sci.impl.world

Dense, fork-local runtime state for SCI contexts.

Stable handles are assigned integer slots once per context lineage. A world stores slot values densely; a fork copies that array. Mutable primitives CAS only their own slot, so unrelated atoms never contend on a shared world root.

Locking (JVM). Evaluation takes no world lock and reads slots lock-free.

  • slot-gate (read): every slot write, together with the host-object mirror of a primary world (Var root/meta, Namespace meta, Type data, volatile) and a lazy realization step. No user code runs inside.
  • publish-gate (read): a publication of several slot writes that must appear together, e.g. a def's value and metadata. No user code runs inside: Var watch notifications are deferred until it ends, and the namespace-environment atom (whose watches and validator are user code) is never updated inside.
  • A fork takes both write locks only for the copy: primary realization, the cells, the lazy realization caches and the namespace environment. It excludes writers for that copy and never waits for an evaluation.
  • A resize takes slot-gate exclusively for the array copy. A fork is therefore a cut between individual publications. Every publication makes its result reachable last: slots are written before an environment mapping or slot value refers to the handle.

Copy-section audit (JVM). Everything that runs while a fork holds the source's publish-gate and slot-gate write locks follows one rule: no user (interpreted) code, and it waits only on leaf locks, which are never held while waiting for another lock or for user code. The participants:

  • Primary snapshot (realize-primary!): reads Var roots and metadata, namespace metadata, Type data and SCI volatile/ref roots through fork's snapshot fns; plain field reads.
  • Stock cache hooks (IForkableWorldCache of SCI's lazy caches): copy an existing realization in short map sections; they never realize a lazy value or take its realization monitor. The owner index is a WeakHashMap under its own monitor (leaf); owners hash by identity.
  • Trusted-Future check (sci.fork/trusted-future?): isDone only on exact FutureTask / CompletableFuture or a clojure.core/future wrapper around one (a volatile read); the wrapper's delegate is read reflectively, its Field cached in a ConcurrentHashMap (leaf bin locks, class reflection).
  • SCI's own copiers (copy-cells!), installed only by SCI and the host (install-var-fork-fns!), never from Var metadata or any evaluation: fork-loaded-libs (operand: the built-in *loaded-libs* root, a ref / atom only SCI's add-loaded-lib updates with conj; the JVM deref may wait for that commit's ref lock), the CLJS fork-type-data (operand: the type's JS prototype, which only SCI sets: interpreted alter-meta! and -create-type cannot replace it) and the ClojureDart method table (identity). Var copiers installed through :fork-fns are host code with the same rule.
  • The namespace environment snapshot: a deref of the env atom.
  • Retirement (retire-world!) is not inside a copy: it takes the slot read lock, so it waits for a copy in progress (and a copy for it); its cache hooks (IWorldCache) only drop private entries.
  • Failed-copy cleanup retires the unpublished target after the source's locks are released.
  • Host IForkableWorldCache / IWorldCache implementations are trusted host code under the same rule. The locks are blocking and non-fair: waiting under them is acyclic, but has no time bound. A fork's copy waits for in-flight slot writes and publications (which run no user code), and they wait for the copy.
Dense, fork-local runtime state for SCI contexts.

Stable handles are assigned integer slots once per context lineage. A world
stores slot values densely; a fork copies that array. Mutable primitives CAS
only their own slot, so unrelated atoms never contend on a shared world root.

Locking (JVM). Evaluation takes no world lock and reads slots lock-free.
- `slot-gate` (read): every slot write, together with the host-object
  mirror of a primary world (Var root/meta, Namespace meta, Type data,
  volatile) and a lazy realization step. No user code runs inside.
- `publish-gate` (read): a publication of several slot writes that must
  appear together, e.g. a def's value and metadata. No user code runs
  inside: Var watch notifications are deferred until it ends, and the
  namespace-environment atom (whose watches and validator are user code)
  is never updated inside.
- A fork takes both write locks only for the copy: primary realization, the
  cells, the lazy realization caches and the namespace environment. It
  excludes writers for that copy and never waits for an evaluation.
- A resize takes `slot-gate` exclusively for the array copy.
A fork is therefore a cut between individual publications. Every
publication makes its result reachable last: slots are written before an
environment mapping or slot value refers to the handle.

Copy-section audit (JVM). Everything that runs while a fork holds the
source's `publish-gate` and `slot-gate` write locks follows one rule: no
user (interpreted) code, and it waits only on leaf locks, which are never
held while waiting for another lock or for user code. The participants:
- Primary snapshot (`realize-primary!`): reads Var roots and metadata,
  namespace metadata, Type data and SCI volatile/ref roots through `fork`'s
  snapshot fns; plain field reads.
- Stock cache hooks (`IForkableWorldCache` of SCI's lazy caches): copy an
  existing realization in short map sections; they never realize a lazy
  value or take its realization monitor. The owner index is a WeakHashMap
  under its own monitor (leaf); owners hash by identity.
- Trusted-Future check (`sci.fork/trusted-future?`): `isDone` only on exact
  FutureTask / CompletableFuture or a `clojure.core/future` wrapper around
  one (a volatile read); the wrapper's delegate is read reflectively, its
  Field cached in a ConcurrentHashMap (leaf bin locks, class reflection).
- SCI's own copiers (`copy-cells!`), installed only by SCI and the host
  (`install-var-fork-fns!`), never from Var metadata or any evaluation:
  `fork-loaded-libs` (operand: the built-in `*loaded-libs*` root, a ref /
  atom only SCI's `add-loaded-lib` updates with `conj`; the JVM deref may
  wait for that commit's ref lock), the CLJS `fork-type-data` (operand: the
  type's JS prototype, which only SCI sets: interpreted `alter-meta!` and
  `-create-type` cannot replace it) and the ClojureDart method table
  (`identity`). Var copiers installed through `:fork-fns` are host code
  with the same rule.
- The namespace environment snapshot: a deref of the env atom.
- Retirement (`retire-world!`) is not inside a copy: it takes the slot
  read lock, so it waits for a copy in progress (and a copy for it); its
  cache hooks (`IWorldCache`) only drop private entries.
- Failed-copy cleanup retires the unpublished target after the source's
  locks are released.
- Host `IForkableWorldCache` / `IWorldCache` implementations are trusted
  host code under the same rule.
The locks are blocking and non-fair: waiting under them is acyclic, but
has no time bound. A fork's copy waits for in-flight slot writes and
publications (which run no user code), and they wait for the copy.
raw docstring

cljdoc builds & hosts documentation for Clojure/Script libraries

Keyboard shortcuts
Ctrl+kJump to recent docs
←Move to previous article
→Move to next article
Ctrl+/Jump to the search field
× close