Liking cljdoc? Tell your friends :D

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.
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.
raw docstring

absentclj/s

source

active-ctxclj/s

(active-ctx captured)

Use the currently evaluating descendant context for an interpreted closure. Unrelated SCI contexts cannot capture one another accidentally.

Use the currently evaluating descendant context for an interpreted closure.
Unrelated SCI contexts cannot capture one another accidentally.
sourceraw docstring

active-world-stateclj/s

(active-world-state)
source

alter-namespace-meta!clj/s

(alter-namespace-meta! handle fallback f args)
(alter-namespace-meta! handle fallback f args mirror)
source

alter-type-data!clj/s

(alter-type-data! handle fallback f args)
(alter-type-data! handle fallback f args mirror)
source

alter-var-meta!clj/s

(alter-var-meta! handle fallback f args)
(alter-var-meta! handle fallback f args mirror)
source

alter-var-watches!clj/s

(alter-var-watches! handle fallback f args)
source

assert-open!clj/s

(assert-open! world)
source

attach-managed-owner!clj/s

(attach-managed-owner! registry managed-index owner)

Attach weak ownership after constructing a self-described handle. The owner is never retained strongly by the lineage registry.

Attach weak ownership after constructing a self-described handle. The
owner is never retained strongly by the lineage registry.
sourceraw docstring

binding-scopeclj/s

(binding-scope)

Return the currently executing world for dynamic-binding isolation. Nil denotes a host binding established outside managed SCI evaluation.

Return the currently executing world for dynamic-binding isolation. Nil
denotes a host binding established outside managed SCI evaluation.
sourceraw docstring

call-admittedclj/s

(call-admitted ctx f)

Run f, an evaluation of ctx that may enter its world several times (one eval-string*), as one evaluation: admitted while the world is open, it finishes even if the world is retired meanwhile.

Run `f`, an evaluation of `ctx` that may enter its world several times
(one eval-string*), as one evaluation: admitted while the world is open,
it finishes even if the world is retired meanwhile.
sourceraw docstring

call-with-contextclj/s

(call-with-context ctx f)

Run f with ctx installed as both SCI's dynamic context and active world. This is the host invocation boundary for interpreted values that outlive the top-level evaluation which produced them.

Run `f` with `ctx` installed as both SCI's dynamic context and active world.
This is the host invocation boundary for interpreted values that outlive the
top-level evaluation which produced them.
sourceraw docstring

call-with-var-contextclj/s

(call-with-var-context handle f)

Run f in the active related world for handle, or in the Var's stable home world when invoked directly by the host. Shared built-in Vars have no home and retain their direct compatibility behavior.

Run `f` in the active related world for `handle`, or in the Var's stable
home world when invoked directly by the host. Shared built-in Vars have no
home and retain their direct compatibility behavior.
sourceraw docstring

compare-and-set-tracked!clj/s

(compare-and-set-tracked! handle expected new validate! notify!)
source

current-worldclj/s

(current-world)
source

fork-recovery?clj/s

(fork-recovery? error)

Whether a failure retains an unpublished fork target for cleanup retry.

Whether a failure retains an unpublished fork target for cleanup retry.
sourceraw docstring

fork-worldclj/s

(fork-world world fork-value snapshot-value snapshot-var-meta)
(fork-world world
            fork-value
            snapshot-value
            snapshot-var-meta
            in-source
            snapshot-extra)

Fork world. The copy section excludes the source's slot writers and publications (never its evaluations, which may include the caller's own): it realizes a primary, copies the cells and the lazy realization caches and calls snapshot-extra (the namespace environment), so all of them are cut at one point. Host fork processing of the unpublished target runs afterwards. in-source runs a thunk with the source's context bound (primary realization reads host objects through it). Returns [target-world extra].

Fork `world`. The copy section excludes the source's slot writers and
publications (never its evaluations, which may include the caller's own):
it realizes a primary, copies the cells and the lazy realization caches
and calls `snapshot-extra` (the namespace environment), so all of them are
cut at one point. Host fork processing of the unpublished target runs
afterwards. `in-source` runs a thunk with the source's context bound
(primary realization reads host objects through it). Returns
[target-world extra].
sourceraw docstring

IForkableWorldCacheclj/sprotocol

-fork-world-cache!clj/s

(-fork-world-cache! owner source target)

Copy an existing source realization into the unpublished target without invoking deferred computation. Missing source state remains missing. Called inside the fork's copy section: it must not block or run user code.

Copy an existing source realization into the unpublished target without
invoking deferred computation. Missing source state remains missing.
Called inside the fork's copy section: it must not block or run user
code.
source

IRetainedWorldCacheclj/sprotocol

-world-cache-entryclj/s

(-world-cache-entry owner world)

This owner's realization for world, or nil. Retirement keeps it in the retired world itself, so evaluations still running there find it after the owner released it.

This owner's realization for `world`, or nil. Retirement keeps it in the
retired world itself, so evaluations still running there find it after
the owner released it.
source

IWorldCacheclj/sprotocol

-retire-world-cache!clj/s

(-retire-world-cache! owner world)

Release this managed owner's cache for one retired world. This internal hook only removes private cache entries: no user callbacks or I/O. It must be idempotent so failed retirement can be retried.

Release this managed owner's cache for one retired world.
This internal hook only removes private cache entries: no user callbacks
or I/O. It must be idempotent so failed retirement can be retried.
source

IWorldTrackedclj/sprotocol

-mark-world-tracked!clj/s

(-mark-world-tracked! handle home-ctx)

-world-home-ctxclj/s

(-world-home-ctx handle)

-world-tracked?clj/s

(-world-tracked? handle)
source

managed-assoc!clj/s

(managed-assoc! home registry slot k value)

Associate one key in a managed persistent-map slot without the generic callback/validation path. Used by mutable SCI deftype fields.

Associate one key in a managed persistent-map slot without the generic
callback/validation path. Used by mutable SCI deftype fields.
sourceraw docstring

managed-compare-and-set!clj/s

(managed-compare-and-set! home registry slot expected new validate! notify!)
(managed-compare-and-set! home
                          registry
                          slot
                          expected
                          new
                          validate!
                          notify!
                          coordination)
(managed-compare-and-set! home
                          registry
                          slot
                          expected
                          new
                          validate!
                          notify!
                          coordination
                          validation-current?)
source

managed-reset!clj/s

(managed-reset! home registry slot new validate! notify!)
(managed-reset! home registry slot new validate! notify! coordination)
(managed-reset! home
                registry
                slot
                new
                validate!
                notify!
                coordination
                validation-current?)
source

managed-swap!clj/s

(managed-swap! home registry slot f args validate! notify!)
(managed-swap! home registry slot f args validate! notify! coordination)
(managed-swap! home
               registry
               slot
               f
               args
               validate!
               notify!
               coordination
               validation-current?)

CAS a directly described slot. The logical fallback represents a slot allocated in another branch but not yet realized in the selected world.

CAS a directly described slot. The logical fallback represents a slot
allocated in another branch but not yet realized in the selected world.
sourceraw docstring

managed-update-control-with-value!clj/s

(managed-update-control-with-value! home
                                    registry
                                    value-slot
                                    control-slot
                                    coordination
                                    validate-value!
                                    update-control)

Atomically validate the selected value and update a related control slot. coordination must be the same stable handle used by value commits.

Atomically validate the selected value and update a related control slot.
`coordination` must be the same stable handle used by value commits.
sourceraw docstring

managed-valueclj/s

(managed-value home registry slot)

Read a self-described managed slot in the active related world, falling back to the owner's creation world outside managed evaluation.

Read a self-described managed slot in the active related world, falling
back to the owner's creation world outside managed evaluation.
sourceraw docstring

managed-value-inclj/s

(managed-value-in world home slot)

Read a managed slot from an already selected world.

Read a managed slot from an already selected world.
sourceraw docstring

mutable-primary-world?clj/s

(mutable-primary-world?)
source

mutable-primary-write!clj/s

(mutable-primary-write! handle value write-root!)

Write value to the host object of handle (a volatile) in a still-mutable primary world: (write-root! value) inside one slot section, so the first fork's realization (which holds the section exclusively) reads the root before or after the write, never in between related writes. If the realization happened meanwhile, the write takes the realized path: slot first, then the root mirrored from it.

Write `value` to the host object of `handle` (a volatile) in a
still-mutable primary world: `(write-root! value)` inside one slot
section, so the first fork's realization (which holds the section
exclusively) reads the root before or after the write, never in between
related writes. If the realization happened meanwhile, the write takes the
realized path: slot first, then the root mirrored from it.
sourceraw docstring

namespace-metaclj/s

(namespace-meta handle fallback)
source

new-worldclj/s

(new-world)
source

primary-world?clj/s

(primary-world?)
source

publishingclj/s

(publishing f)

publishing-in the world of SCI's current context, or plain (f) outside a forkable context.

`publishing-in` the world of SCI's current context, or plain `(f)` outside
a forkable context.
sourceraw docstring

publishing-inclj/s

(publishing-in world f)

Run f as one publication in world: a fork's copy observes all of its writes or none. f must not run user code; callbacks it triggers through run-after-publication! run after the publication, in order.

Run `f` as one publication in `world`: a fork's copy observes all of its
writes or none. `f` must not run user code; callbacks it triggers through
`run-after-publication!` run after the publication, in order.
sourceraw docstring

read-worldclj/s

(read-world world primary?)
source

recover-failed-fork!clj/s

(recover-failed-fork! error)

Retry cleanup of the unpublished target retained by a failed SCI fork. Never re-executes the fork or changes its source. A subsequent cleanup failure retains the same target and original failure for another retry.

Retry cleanup of the unpublished target retained by a failed SCI fork.
Never re-executes the fork or changes its source. A subsequent cleanup
failure retains the same target and original failure for another retry.
sourceraw docstring

register!clj/s

(register! handle value)
(register! handle value value-fork-fn)
source

register-managed!clj/s

(register-managed! kind values fork-indexes)

Allocate dense slots whose owner carries the returned descriptor directly. Managed descriptors contain no owner reference, so an unreachable SCI ref is not retained by the lineage registry. fork-indexes names values that need host Forkable/:fork-fn processing when a child world is copied.

Allocate dense slots whose owner carries the returned descriptor directly.
Managed descriptors contain no owner reference, so an unreachable SCI ref is
not retained by the lineage registry. `fork-indexes` names values that need
host `Forkable`/`:fork-fn` processing when a child world is copied.
sourceraw docstring

register-namespace!clj/s

(register-namespace! handle m)
source

register-type!clj/s

(register-type! handle data)
(register-type! handle data value-fork-fn)
source

register-var!clj/s

(register-var! handle value m)
(register-var! handle value m watches)
(register-var! handle value m watches mirror-root)

Write a Var's value and metadata (and watches) in one slot section. mirror-root, when given, writes the primary world's Var root in that same section (see mirror!).

Write a Var's value and metadata (and watches) in one slot section.
`mirror-root`, when given, writes the primary world's Var root in that
same section (see `mirror!`).
sourceraw docstring

register-world-cache!clj/s

(register-world-cache! owner)

Register an identity-based internal owner of fork-local realizations. The lineage index retains the owner weakly and does not allocate dense slots. Owners must implement both cache protocols and must not use content-based hashing/equality (in particular, the owner is not a sequence view).

Register an identity-based internal owner of fork-local realizations. The
lineage index retains the owner weakly and does not allocate dense slots.
Owners must implement both cache protocols and must not use content-based
hashing/equality (in particular, the owner is not a sequence view).
sourceraw docstring

registered?clj/s

(registered? world handle)
source

reset-namespace-meta!clj/s

(reset-namespace-meta! handle m)
(reset-namespace-meta! handle m mirror)
source

reset-tracked!clj/s

(reset-tracked! handle new validate! notify!)
source

reset-type-data!clj/s

(reset-type-data! handle data)
(reset-type-data! handle data mirror)
source

reset-value!clj/s

(reset-value! handle value)
(reset-value! handle value mirror)

Reset a tracked slot; mirror (optional) writes the primary world's host object in the same slot section.

Reset a tracked slot; `mirror` (optional) writes the primary world's host
object in the same slot section.
sourceraw docstring

reset-var-meta!clj/s

(reset-var-meta! handle m)
(reset-var-meta! handle m mirror)
source

retire-world!clj/s

(retire-world! world)

Retire one interpreter world now. New evaluations and forks are refused; evaluations already running in it finish against it. Managed cache owners release their world-specific state (the world keeps what running evaluations still need). When no evaluation is in the world, now or once the last one leaves, its cells and retained caches are cleared; the small closed world remains for Vars whose home it is, which then refuse access. This does not close foreign host resources or retire sibling worlds. Safe to repeat after a failed cache cleanup.

Retire one interpreter world now. New evaluations and forks are refused;
evaluations already running in it finish against it. Managed cache owners
release their world-specific state (the world keeps what running
evaluations still need). When no evaluation is in the world, now or once
the last one leaves, its cells and retained caches are cleared; the small
closed world remains for Vars whose home it is, which then refuse access.
This does not close foreign host resources or retire sibling worlds. Safe
to repeat after a failed cache cleanup.
sourceraw docstring

retired-cache-entryclj/s

(retired-cache-entry world owner)

The realization owner held for the retired world when it was retired, or nil. Evaluations still running in a retired world read their caches here after the owners released them.

The realization `owner` held for the retired `world` when it was retired,
or nil. Evaluations still running in a retired world read their caches
here after the owners released them.
sourceraw docstring

run-after-publication!clj/s

(run-after-publication! thunk)

Run thunk now, or after the publication this thread is inside ends. Used for user callbacks (watches) triggered by a published write.

Run `thunk` now, or after the publication this thread is inside ends.
Used for user callbacks (watches) triggered by a published write.
sourceraw docstring

selected-worldclj/s

(selected-world)

The actual selected world, including the target selected during copying.

The actual selected world, including the target selected during copying.
sourceraw docstring

slot-ofclj/s

(slot-of world handle)

Return the value slot assigned to handle, or nil when it is not registered in this lineage. Intended for analyzer-time resolution.

Return the value slot assigned to `handle`, or nil when it is not registered
in this lineage. Intended for analyzer-time resolution.
sourceraw docstring

swap-value!clj/s

(swap-value! handle f args validate! notify!)

Atomically update one tracked slot. Unrelated SCI atoms do not contend and cannot cause f to be retried. f and validate! run outside every lock.

Atomically update one tracked slot. Unrelated SCI atoms do not contend and
cannot cause `f` to be retried. `f` and `validate!` run outside every lock.
sourceraw docstring

sync-primary-root!clj/s

(sync-primary-root! handle read-root)

After a root write to handle that ran user code (a host atom's swap!) in a primary world: once that world is realized, make its slot agree with the current root (read-root). Each syncing writer re-reads the root after writing the slot, so the last one leaves them equal. The root write itself precedes this section; no JVM/CLJS path tracks a host atom.

After a root write to `handle` that ran user code (a host atom's swap!)
in a primary world: once that world is realized, make its slot agree with
the current root (`read-root`). Each syncing writer re-reads the root after
writing the slot, so the last one leaves them equal. The root write itself
precedes this section; no JVM/CLJS path tracks a host atom.
sourceraw docstring

tracked?clj/s

(tracked? handle)
source

type-dataclj/s

(type-data handle fallback)
source

valueclj/s

(value handle fallback)
source

var-metaclj/s

(var-meta handle fallback)

A Var's metadata in its selected world. Unlike its value, metadata without a realization there falls back to the Var's own field (name, namespace), so printing a retired world's Var still works.

A Var's metadata in its selected world. Unlike its value, metadata without
a realization there falls back to the Var's own field (name, namespace),
so printing a retired world's Var still works.
sourceraw docstring

var-valueclj/s

(var-value handle fallback)

Primary contexts retain their direct Var realization. Descendants resolve the stable Var handle through its dense lineage slot.

Primary contexts retain their direct Var realization. Descendants resolve
the stable Var handle through its dense lineage slot.
sourceraw docstring

var-value-atclj/s

(var-value-at slot fallback)

Read a Var through a slot already resolved by the analyzer: its value in the active world, absent when that world has no realization of it (the caller then reads the Var fully, which consults its home), or fallback outside a forked world.

Read a Var through a slot already resolved by the analyzer: its value in
the active world, `absent` when that world has no realization of it (the
caller then reads the Var fully, which consults its home), or `fallback`
outside a forked world.
sourceraw docstring

var-watchesclj/s

(var-watches handle fallback)
source

with-active-worldclj/s

(with-active-world ctx f)

Run f with the context's world installed. Evaluation takes no world lock: a fork excludes only slot writers, for its copy, and a retirement only refuses new entries.

Run `f` with the context's world installed. Evaluation takes no world
lock: a fork excludes only slot writers, for its copy, and a retirement
only refuses new entries.
sourceraw docstring

with-handle-lockclj/s

(with-handle-lock handle f)
source

with-selected-slot-sectionclj/s

(with-selected-slot-section f)

Run f (no user code) as one slot write of the selected world, so a fork's copy sees it entirely or not at all. Used for lazy realization steps.

Run `f` (no user code) as one slot write of the selected world, so a fork's
copy sees it entirely or not at all. Used for lazy realization steps.
sourceraw docstring

world-cache-ownersclj/s

(world-cache-owners)
(world-cache-owners world)

An eager strong snapshot of currently live cache owners in a lineage. Inspection also removes dead weak entries. Closed worlds retain their registry until cleanup succeeds, so retirement may call this function.

An eager strong snapshot of currently live cache owners in a lineage.
Inspection also removes dead weak entries. Closed worlds retain their
registry until cleanup succeeds, so retirement may call this function.
sourceraw 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