tur/image
application image dumps via serializable continuations.
Since: Phase AI (application-image-dumps-plan)
image/build-stamp
(image/build-stamp :)
SHA-256 (32 bytes) of the running executable.
A malloc'd 32-byte buffer (caller frees with image/free-stamp) as an int pointer, or 0 if the executable image could not be read.
Since: Phase AI
image/free-stamp
(image/free-stamp [p : int] :)
free a build stamp returned by image/build-stamp.
image/exists?
(image/exists? [path : cstr] :)
1 if a readable file exists at path, else 0.
image/hook-registry
(image/hook-registry [op : int arg : int] :)
backing store for reload/finalize hooks (internal).
image/register-reload-hook!
(image/register-reload-hook! [^fat f : (fn [])
install a hook run on warm start before resume.
| f | a zero-arg hook (fn [] int); the return value is ignored |
The number of reload hooks registered so far.
Since: Phase AI (AI5.1)
image/run-reload-hooks
(image/run-reload-hooks :)
invoke every registered reload hook in order.
Since: Phase AI (AI5.1)
image/register-finalize-hook!
(image/register-finalize-hook! [^fat f : (fn [])
install a hook run just before a save.
| f | a zero-arg hook (fn [] int); the return value is ignored |
The number of finalize hooks registered so far.
Since: Phase AI (AI5.3)
image/run-finalize-hooks
(image/run-finalize-hooks :)
invoke every registered finalize hook in order.
Since: Phase AI (AI5.3)
defimage-reload-hook
(defimage-reload-hook [name body])
define a named reload hook function.
(defimage-reload-hook reopen-log
(do (reopen-the-log!) 0))
;; ... in main, before with-image-cache-after-init:
(image/register-reload-hook! reopen-log)
Since: Phase AI (AI5.1)
defimage-finalize-hook
(defimage-finalize-hook [name body])
define a named finalize hook function.
Since: Phase AI (AI5.3)
image/global-registry
(image/global-registry [op : int name : cstr ser : int deser : int bytes ptr<void>] :)
backing store for image globals (internal).
image/free-bytes
(image/free-bytes [b ptr<void>] :)
free a bytes value returned by image/snapshot-globals.
image/bytes-null?
(image/bytes-null? [b ptr<void>] :)
true when a bytes/blob value is NULL.
image/register-global!
(image/register-global! [name : cstr ^fat ser : (fn [] ptr<void>))
register a global's ser/deser pair by name.
| name | the global's name, the key the image section is matched on | |
| ser | (fn [] ptr<void>): the global's current value as Serializable bytes | |
| deser | (fn [ptr<void>] int): overwrite the global from Serializable bytes |
The number of globals registered so far.
Since: Phase AI (AI3.2)
image/null-bytes
(image/null-bytes :)
the NULL bytes value (internal).
image/global-count
(image/global-count :)
how many image globals are registered.
Since: Phase AI (AI3.2)
image/snapshot-globals
(image/snapshot-globals :)
serialise every registered global into one bytes value.
Since: Phase AI (AI3.3)
image/bytes-of
(image/bytes-of [p : int] :)
reinterpret an int carrier as a bytes value (internal).
image/restore-globals!
(image/restore-globals! [bytes ptr<void>] :)
overwrite registered globals from a globals section.
| bytes | a globals section as written by image/snapshot-globals (NULL is a no-op) |
The number of globals restored.
Since: Phase AI (AI3.3)
defimage-global
(defimage-global [name ty init])
declare a mutable global that rides in the image.
(defimage-global counter :int 0)
(defn do-init [] : int (do (set! counter 42) 0))
(defn main [] : int
(do (image/track-globals! counter)
(with-image-cache-after-init "app.img" do-init do-loop)))
;; a warm start sees counter = 42, not 0
Since: Phase AI (AI3.2)
image/track-globals!
(image/track-globals! [& names])
register the named image globals (call at the top of main).
Since: Phase AI (AI3.2)
image/write-image-file!
(image/write-image-file! [path : cstr k ptr<void> stamp : int globals ptr<void>] :)
frame continuation k (+ globals) and write to path.
| path | destination path | |
| k | the serial-continuation handle from serial-shift | |
| stamp | 32-byte build stamp pointer (image/build-stamp), or 0 to zero-fill | |
| globals | a globals section from image/snapshot-globals, or NULL for none |
1 on success, 0 on failure (nil k, unwritable path, short write).
Since: Phase AI (AI3.3)
image/save-cont-to-file!
(image/save-cont-to-file! [path : cstr k ptr<void> stamp : int] :)
serialise continuation k and write it to path.
| path | destination path | |
| k | the serial-continuation handle from serial-shift | |
| stamp | 32-byte build stamp pointer (image/build-stamp), or 0 to zero-fill |
1 on success, 0 on failure (nil k, unwritable path, short write).
Since: Phase AI
image/loadable?
(image/loadable? [path : cstr stamp : int] :)
1 if path is a structurally valid image for `stamp`.
Since: Phase AI
image/read-image-file
(image/read-image-file [path : cstr stamp : int] :)
read + validate an image into a blob (internal).
Since: Phase AI (AI3.3)
image/blob-globals
(image/blob-globals [blob ptr<void>] :)
the globals section inside a read blob (internal).
image/blob-resume!
(image/blob-resume! [blob ptr<void> v : int] :)
deserialise the blob's continuation and resume it on v.
image/load-resume-file!
(image/load-resume-file! [path : cstr stamp : int v : int] :)
read + validate an image and resume it on v.
| path | source path | |
| stamp | 32-byte build-stamp pointer to enforce, or 0 to skip the check | |
| v | the value to resume the captured continuation with |
The resumed continuation's value on success (control transfers into the captured tail), or 0 on any validation/I-O failure (no resume occurs).
Since: Phase AI
save-image!
(save-image! [path : cstr] :)
capture the current continuation and write it to path.
Since: Phase AI
load-image!
(load-image! [path : cstr] :)
read an image and resume the continuation it holds.
Since: Phase AI
with-image-cache-after-init
(with-image-cache-after-init [path init loop])
the primary warm-start combinator (AIQ1).
| path | image cache path | |
| init | a fn [] run only on cold start (expensive setup) | |
| loop | a fn [] run on both paths (the steady-state work) | |
| This is a macro, not a function: `init` and `loop` are spliced as call | ||
| targets so the captured continuation tail `(loop)` is a call to a *named* | ||
| top-level function. The serial-shift collector reconstructs frames by | ||
| stable name, so the tail cannot be a heap closure -- it must be a named | ||
| (serializable) continuation. Pass top-level `defn` names for init and loop. | ||
| For a *cross-process* warm start to resume correctly, loop must reduce to a | ||
| serializable continuation (named frames, int/cstr/Serializable envs) -- the | ||
| same constraint Serializable continuations impose on serial-shift. |
Since: Phase AI
with-image-cache
(with-image-cache [path : cstr ^fat body : (fn [])
single-body warm-start wrapper.
Since: Phase AI