This is the journal Reference Manual, version 0.1.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Dec 15 06:31:11 2024 GMT+0.
The main system appears first, followed by any subsystem dependency.
journalA library built around explicit execution traces for logging, tracing, testing and persistence.
Gábor Melis <mega@retes.hu>
(GIT https://github.com/melisgl/journal.git)
MIT, see COPYING.
0.1.0
alexandria (system).
bordeaux-threads (system).
local-time (system).
mgl-pax (system).
trivial-features (system).
trivial-garbage (system).
osicat (system)., for feature (:not (:or :abcl :allegro :sbcl :cmucl))
sb-posix (system)., for feature :sbcl
src (module).
Modules are listed depth-first from the system components tree.
journal/srcjournal (system).
package.lisp (file).
interrupt.lisp (file).
journal.lisp (file).
doc.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
journal/journal.asdjournal/src/package.lispjournal/src/interrupt.lispjournal/src/journal.lispjournal/src/doc.lispjournal/src/interrupt.lisppackage.lisp (file).
src (module).
*with-interrupts-available* (special variable).
*without-interrupts-available* (special variable).
async-signal-safe (macro).
unwind-protect* (macro).
with-interrupts (macro).
without-interrupts (macro).
journal/src/journal.lispinterrupt.lisp (file).
src (module).
*force-insertable* (special variable).
*trace-depth* (special variable).
*trace-journal* (special variable).
*trace-out-name* (special variable).
*trace-pretty* (special variable).
*trace-real-time* (special variable).
*trace-run-time* (special variable).
*trace-thread* (special variable).
*trace-time* (special variable).
bundle (class).
checked (macro).
close-streamlet (generic function).
data-event-lossage (condition).
define-file-bundle-test (macro).
define-invoked (macro).
delete-file-bundle (function).
directory-of (reader method).
end-of-journal (condition).
equivalent-replay-journals-p (generic function).
event (type).
event-args (function).
event-exit (function).
event-exit (type).
event-name (function).
event-outcome (function).
event-version (function).
event-version (type).
event= (function).
events-to-frames (function).
expected-outcome-p (function).
expected-type (function).
external-event (type).
external-event-p (function).
file-bundle (class).
file-journal (class).
flet-invoked (macro).
framed (macro).
identical-journals-p (generic function).
in-event (type).
in-event-p (function).
in-memory-bundle (class).
in-memory-journal (class).
input-streamlet-p (function).
install-journal-elisp (function).
journal (reader method).
journal (reader method).
journal (reader method).
journal (class).
journal-divergent-p (function).
journal-error (condition).
journal-events (reader method).
journal-log-decorator (reader method).
(setf journal-log-decorator) (writer method).
journal-previous-sync-position (reader method).
journal-replay-mismatch (reader method).
journal-state (reader method).
journal-state (type).
journal-sync (reader method).
journaled (macro).
journaling-failure (function).
journaling-failure (condition).
journaling-failure-embedded-condition (reader method).
jtrace (macro).
juntrace (macro).
leaf-event (type).
leaf-event-p (function).
list-events (function).
log-event (type).
log-event-p (function).
logged (macro).
make-file-bundle (function).
make-file-journal (function).
make-in-event (function).
make-in-memory-bundle (function).
make-in-memory-journal (function).
make-leaf-event (function).
make-log-decorator (function).
make-out-event (function).
make-pprint-journal (function).
make-streamlet-finalizer (generic function).
max-n-completed (reader method).
(setf max-n-completed) (writer method).
max-n-failed (reader method).
(setf max-n-failed) (writer method).
open-streamlet (generic function).
open-streamlet-p (generic function).
out-event (type).
out-event-p (function).
output-streamlet-p (function).
pathname-of (reader method).
peek-event (generic function).
peek-replay-event (function).
pprint-events (function).
pprint-journal (class).
pprint-journal-prettifier (reader method).
(setf pprint-journal-prettifier) (writer method).
pprint-journal-pretty (reader method).
(setf pprint-journal-pretty) (writer method).
pprint-journal-stream (reader method).
(setf pprint-journal-stream) (writer method).
prettify-event (function).
print-events (function).
print-object (method).
print-object (method).
print-object (method).
print-object (method).
print-object (method).
print-object (method).
read-event (generic function).
(setf read-position) (setf expander).
read-position (generic function).
record-journal (function).
record-unexpected-outcome (condition).
replay-args-mismatch (condition).
replay-failure (function).
replay-failure (condition).
replay-failure-new-event (reader method).
replay-failure-replay-event (reader method).
replay-failure-replay-journal (reader method).
replay-incomplete (condition).
replay-journal (function).
replay-name-mismatch (condition).
replay-outcome-mismatch (condition).
replay-unexpected-outcome (condition).
replay-version-downgrade (condition).
replayed (macro).
request-completed-on-abort (generic function).
save-excursion (macro).
set-read-position (generic function).
streamlet (reader method).
streamlet (class).
streamlet-error (condition).
sync-journal (function).
sync-streamlet (generic function).
to-journal (generic function).
unexpected-outcome-p (function).
values-> (function).
values<- (function).
versioned-event (type).
versioned-event-p (function).
with-bundle (macro).
with-journaling (macro).
with-open-journal (macro).
with-replay-filter (macro).
with-replay-streamlet (macro).
write-event (generic function).
write-position (generic function).
%commit-file-journal-events (function).
%direction (reader method).
(setf %direction) (writer method).
%fsync (function).
%in-depth (reader method).
(setf %in-depth) (writer method).
%journals (reader method).
(setf %journals) (writer method).
%out-depth (reader method).
%out-depth (reader method).
(setf %out-depth) (writer method).
(setf %out-depth) (writer method).
%output-streamlet-of (reader method).
(setf %output-streamlet-of) (writer method).
%print-events (function).
%print-journal-object-slots (function).
%read-event-from-stream (function).
%read-event-from-streamlet (function).
%set-file-journal-completed-on-abort (function).
%set-in-memory-streamlet-read-position (function).
%state (reader method).
(setf %state) (writer method).
%stream (reader method).
(setf %stream) (writer method).
%truename (function).
*file-bundle-lock* (special variable).
*file-journal-lock* (special variable).
*invoked-event-name-to-function-name* (special variable).
*journaling-failure* (special variable).
*local-invoked-event-name-to-function* (special variable).
*next-write-event-fn* (special variable).
*no-replay-outcome-names* (special variable).
*record-journal-state* (special variable).
*record-streamlet* (special variable).
*replay-eoj-error-p* (special variable).
*replay-event-mapper* (special variable).
*replay-failure* (special variable).
*replay-filter-base-depth* (special variable).
*replay-streamlet* (special variable).
*skip-events* (special variable).
*skip-patterns* (special variable).
*skipped-events-until* (special variable).
*suppress-trace* (special variable).
*testing* (special variable).
*traced-functions* (special variable).
*truename-to-file-bundle* (special variable).
*truename-to-file-journal* (special variable).
*with-journaling-failure-on-nlx-body-completed* (special variable).
->recording-p (function).
@aborted-execution (special variable).
@async-unwind (special variable).
@block (special variable).
@boolean-valued-symbol (special variable).
@bundles (special variable).
@bundles-reference (special variable).
@comparing-journals (special variable).
@condition-outcome (special variable).
@continuation (special variable).
@customizing-logs (special variable).
@data-event (special variable).
@decoration (special variable).
@error-outcome (special variable).
@event-sourcing (special variable).
@event-versions (special variable).
@events-reference (special variable).
@expected-outcome (special variable).
@ext4-writeback (special variable).
@file-bundles (special variable).
@file-journals (special variable).
@frame (special variable).
@in-events (special variable).
@in-events-reference (special variable).
@in-memory-bundles (special variable).
@in-memory-journals (special variable).
@invoked (special variable).
@journal-background (special variable).
@journal-basics (special variable).
@journal-error-handling (special variable).
@journal-features (special variable).
@journal-links (special variable).
@journal-manual (special variable).
@journal-portability (special variable).
@journal-slime-integration (special variable).
@journal-utilities (special variable).
@journal/glossary (special variable).
@journaled-for-replay (special variable).
@journaling-fs (special variable).
@journals-reference (special variable).
@leaf-events-reference (special variable).
@log-record (special variable).
@logging (special variable).
@logging-with-leaves (special variable).
@matching-in-events (special variable).
@matching-out-events (special variable).
@mock-object (special variable).
@nlx-outcome (special variable).
@opening-and-closing (special variable).
@out-events (special variable).
@out-events-reference (special variable).
@persistence (special variable).
@persistence-tutorial (special variable).
@pprint-journals (special variable).
@pretty-printing (special variable).
@readable (special variable).
@reading-from-streamlets (special variable).
@replay (special variable).
@replay-event (special variable).
@replay-failures (special variable).
@replaying-the-outcome (special variable).
@safety (special variable).
@streamlets-reference (special variable).
@synchronization (special variable).
@synchronization-strategies (special variable).
@synchronization-with-file-journals (special variable).
@synchronization-with-in-memory-journals (special variable).
@testing (special variable).
@testing-on-multiple-levels (special variable).
@the-replay-strategy (special variable).
@tracing (special variable).
@unexpected-outcome (special variable).
@upgrades-and-replay (special variable).
@values-outcome (special variable).
@working-with-unreadable-values (special variable).
@writing-to-streamlets (special variable).
apply-key (function).
bundle-file-version (function).
bundle-record-journal (function).
bundle-replay-journal (function).
call-journaled (function).
call-with-journaling (function).
call-with-journaling-failure-on-nlx (function).
call-with-open-journal (function).
check-args (function).
check-concurrent-write-access (function).
check-file-bundle-options (function).
check-file-journal-options (function).
check-input-streamlet-p (function).
check-journal-state (function).
check-jrn-elisp-version (function).
check-okay-for-input (function).
check-okay-for-output (function).
check-open-streamlet-p (function).
check-outcome (function).
check-output-streamlet-p (function).
check-sync-value (function).
check-within-with-journaling-failure-on-nlx (function).
cleanup (function).
condition-event-p (function).
condition-to-string (function).
delete-file-journal (function).
delete-journal-from-bundle (generic function).
direction (type).
eat-event (function).
eat-events (function).
eat-full-frames-of-events (function).
echo-current-frame (function).
end-of-frame-position (function).
ensure-txn (function).
equivalent-states-p (function).
error-event-p (function).
events (reader method).
every-event-in-frame (function).
fail-with-journaling-failure (function).
file-streamlet (class).
finalize-journal-state (function).
flet-invoked/1 (function).
format-args (reader method).
format-args (reader method).
format-control (reader method).
format-control (reader method).
fsync (function).
fsync-directory (function).
getf* (function).
handle-in-event (function).
handle-leaf-event (function).
handle-out-event (function).
in-memory-streamlet (class).
in-with-journaling-p (function).
initialize-journal-state (function).
input-direction-p (function).
invalidate-journal (function).
invoked-function (function).
invoked/1 (function).
journal-output-streamlet (function).
journaling-failure-n-resignallings (reader method).
(setf journaling-failure-n-resignallings) (writer method).
journals (reader method).
jtrace-1 (macro).
jtracedp (function).
juntrace-1 (function).
list-journal-files-in-directory (function).
list-traced-functions (function).
make-file-journals-for-bundle (function).
make-in-event* (function).
make-out-event* (function).
make-record-journal-in-bundle (generic function).
match-version (function).
maybe-downgrade-version (function).
maybe-handle-invoked (function).
maybe-mark-record-as-divergent (function).
maybe-print-resignalling-message (function).
maybe-replay-outcome (function).
maybe-resignal-journaling-failure (function).
maybe-sync-after-in-event (function).
maybe-sync-after-out-event (function).
new-event (reader method).
nlx-event-p (function).
nlx-outcome-and-maybe->logging (function).
nlx-protect (macro).
output-direction-p (function).
pattern-to-pred (function).
patterns-to-disjunction (function).
peek-at-out-event (function).
peek-mapped-replay-event (function).
position-to-read (function).
position-to-write (function).
pprint-streamlet (class).
print-record-closed (function).
read-file-journal-state (function).
read-file-position (reader method).
(setf read-file-position) (writer method).
read-mapped-replay-event (function).
reap-identical-or-non-divergent-journals (function).
reap-journals-in-bundle (function).
replay-failure-record-journal (reader method).
replay-failure-replay-position (reader method).
replay-filter-at-base-depth-p (function).
replay-strategy (function).
replaying-outcome-allowed-p (function).
resolve-log-record (function).
route-event (function).
safe-condition (type).
set-file-journal-completed-on-abort (function).
set-journal-state (function).
skip-events (function).
skip-events-and-maybe->recording (function).
skip-log-events (function).
stream-fd (function).
swank-toggle-jtrace (function).
turn-off-with-journaling-failure-on-nlx (function).
unsafe-condition (type).
untrace-all (function).
values-event-p (function).
version< (function).
version= (function).
with-bundle-locked (macro).
with-journal-locked (macro).
with-journaling-failure-on-nlx (macro).
with-nlx-cancelled (macro).
with-standard-io-syntax* (macro).
write-file-journal-state (function).
wrote-last-p (reader method).
(setf wrote-last-p) (writer method).
journal/src/doc.lispjournal.lisp (file).
src (module).
pax-pages (function).
pax-sections (function).
Packages are listed by definition order.
journaljrn
common-lisp.
editor-hints.named-readtables.
mgl-pax.
pythonic-string-reader.
*force-insertable* (special variable).
*trace-depth* (special variable).
*trace-journal* (special variable).
*trace-out-name* (special variable).
*trace-pretty* (special variable).
*trace-real-time* (special variable).
*trace-run-time* (special variable).
*trace-thread* (special variable).
*trace-time* (special variable).
bundle (class).
checked (macro).
close-streamlet (generic function).
data-event-lossage (condition).
define-file-bundle-test (macro).
define-invoked (macro).
delete-file-bundle (function).
directory-of (generic reader).
end-of-journal (condition).
equivalent-replay-journals-p (generic function).
event (type).
event-args (function).
event-exit (function).
event-exit (type).
event-name (function).
event-outcome (function).
event-version (function).
event-version (type).
event= (function).
events-to-frames (function).
expected-outcome-p (function).
expected-type (function).
external-event (type).
external-event-p (function).
file-bundle (class).
file-journal (class).
flet-invoked (macro).
framed (macro).
identical-journals-p (generic function).
in-event (type).
in-event-p (function).
in-memory-bundle (class).
in-memory-journal (class).
input-streamlet-p (function).
install-journal-elisp (function).
journal (generic reader).
journal (class).
journal-divergent-p (function).
journal-error (condition).
journal-events (generic reader).
journal-log-decorator (generic reader).
(setf journal-log-decorator) (generic writer).
journal-previous-sync-position (generic reader).
journal-replay-mismatch (generic reader).
journal-state (generic reader).
journal-state (type).
journal-sync (generic reader).
journaled (macro).
journaling-failure (function).
journaling-failure (condition).
journaling-failure-embedded-condition (generic reader).
jtrace (macro).
juntrace (macro).
leaf-event (type).
leaf-event-p (function).
list-events (function).
log-event (type).
log-event-p (function).
logged (macro).
make-file-bundle (function).
make-file-journal (function).
make-in-event (function).
make-in-memory-bundle (function).
make-in-memory-journal (function).
make-leaf-event (function).
make-log-decorator (function).
make-out-event (function).
make-pprint-journal (function).
make-streamlet-finalizer (generic function).
max-n-completed (generic reader).
(setf max-n-completed) (generic writer).
max-n-failed (generic reader).
(setf max-n-failed) (generic writer).
open-streamlet (generic function).
open-streamlet-p (generic function).
out-event (type).
out-event-p (function).
output-streamlet-p (function).
pathname-of (generic reader).
peek-event (generic function).
peek-replay-event (function).
pprint-events (function).
pprint-journal (class).
pprint-journal-prettifier (generic reader).
(setf pprint-journal-prettifier) (generic writer).
pprint-journal-pretty (generic reader).
(setf pprint-journal-pretty) (generic writer).
pprint-journal-stream (generic reader).
(setf pprint-journal-stream) (generic writer).
prettify-event (function).
print-events (function).
read-event (generic function).
(setf read-position) (setf expander).
read-position (generic function).
record-journal (function).
record-unexpected-outcome (condition).
replay-args-mismatch (condition).
replay-failure (function).
replay-failure (condition).
replay-failure-new-event (generic reader).
replay-failure-replay-event (generic reader).
replay-failure-replay-journal (generic reader).
replay-incomplete (condition).
replay-journal (function).
replay-name-mismatch (condition).
replay-outcome-mismatch (condition).
replay-unexpected-outcome (condition).
replay-version-downgrade (condition).
replayed (macro).
request-completed-on-abort (generic function).
save-excursion (macro).
set-read-position (generic function).
streamlet (generic reader).
streamlet (class).
streamlet-error (condition).
sync-journal (function).
sync-streamlet (generic function).
to-journal (generic function).
unexpected-outcome-p (function).
values-> (function).
values<- (function).
versioned-event (type).
versioned-event-p (function).
with-bundle (macro).
with-journaling (macro).
with-open-journal (macro).
with-replay-filter (macro).
with-replay-streamlet (macro).
write-event (generic function).
write-position (generic function).
%commit-file-journal-events (function).
%direction (generic reader).
(setf %direction) (generic writer).
%fsync (function).
%in-depth (generic reader).
(setf %in-depth) (generic writer).
%journals (generic reader).
(setf %journals) (generic writer).
%out-depth (generic reader).
(setf %out-depth) (generic writer).
%output-streamlet-of (generic reader).
(setf %output-streamlet-of) (generic writer).
%print-events (function).
%print-journal-object-slots (function).
%read-event-from-stream (function).
%read-event-from-streamlet (function).
%set-file-journal-completed-on-abort (function).
%set-in-memory-streamlet-read-position (function).
%state (generic reader).
(setf %state) (generic writer).
%stream (generic reader).
(setf %stream) (generic writer).
%truename (function).
*file-bundle-lock* (special variable).
*file-journal-lock* (special variable).
*invoked-event-name-to-function-name* (special variable).
*journaling-failure* (special variable).
*local-invoked-event-name-to-function* (special variable).
*next-write-event-fn* (special variable).
*no-replay-outcome-names* (special variable).
*record-journal-state* (special variable).
*record-streamlet* (special variable).
*replay-eoj-error-p* (special variable).
*replay-event-mapper* (special variable).
*replay-failure* (special variable).
*replay-filter-base-depth* (special variable).
*replay-streamlet* (special variable).
*skip-events* (special variable).
*skip-patterns* (special variable).
*skipped-events-until* (special variable).
*suppress-trace* (special variable).
*testing* (special variable).
*traced-functions* (special variable).
*truename-to-file-bundle* (special variable).
*truename-to-file-journal* (special variable).
*with-interrupts-available* (special variable).
*with-journaling-failure-on-nlx-body-completed* (special variable).
*without-interrupts-available* (special variable).
->recording-p (function).
@aborted-execution (special variable).
@async-unwind (special variable).
@block (special variable).
@boolean-valued-symbol (special variable).
@bundles (special variable).
@bundles-reference (special variable).
@comparing-journals (special variable).
@condition-outcome (special variable).
@continuation (special variable).
@customizing-logs (special variable).
@data-event (special variable).
@decoration (special variable).
@error-outcome (special variable).
@event-sourcing (special variable).
@event-versions (special variable).
@events-reference (special variable).
@expected-outcome (special variable).
@ext4-writeback (special variable).
@file-bundles (special variable).
@file-journals (special variable).
@frame (special variable).
@in-events (special variable).
@in-events-reference (special variable).
@in-memory-bundles (special variable).
@in-memory-journals (special variable).
@invoked (special variable).
@journal-background (special variable).
@journal-basics (special variable).
@journal-error-handling (special variable).
@journal-features (special variable).
@journal-links (special variable).
@journal-manual (special variable).
@journal-portability (special variable).
@journal-slime-integration (special variable).
@journal-utilities (special variable).
@journal/glossary (special variable).
@journaled-for-replay (special variable).
@journaling-fs (special variable).
@journals-reference (special variable).
@leaf-events-reference (special variable).
@log-record (special variable).
@logging (special variable).
@logging-with-leaves (special variable).
@matching-in-events (special variable).
@matching-out-events (special variable).
@mock-object (special variable).
@nlx-outcome (special variable).
@opening-and-closing (special variable).
@out-events (special variable).
@out-events-reference (special variable).
@persistence (special variable).
@persistence-tutorial (special variable).
@pprint-journals (special variable).
@pretty-printing (special variable).
@readable (special variable).
@reading-from-streamlets (special variable).
@replay (special variable).
@replay-event (special variable).
@replay-failures (special variable).
@replaying-the-outcome (special variable).
@safety (special variable).
@streamlets-reference (special variable).
@synchronization (special variable).
@synchronization-strategies (special variable).
@synchronization-with-file-journals (special variable).
@synchronization-with-in-memory-journals (special variable).
@testing (special variable).
@testing-on-multiple-levels (special variable).
@the-replay-strategy (special variable).
@tracing (special variable).
@unexpected-outcome (special variable).
@upgrades-and-replay (special variable).
@values-outcome (special variable).
@working-with-unreadable-values (special variable).
@writing-to-streamlets (special variable).
apply-key (function).
async-signal-safe (macro).
bundle-file-version (function).
bundle-record-journal (function).
bundle-replay-journal (function).
call-journaled (function).
call-with-journaling (function).
call-with-journaling-failure-on-nlx (function).
call-with-open-journal (function).
check-args (function).
check-concurrent-write-access (function).
check-file-bundle-options (function).
check-file-journal-options (function).
check-input-streamlet-p (function).
check-journal-state (function).
check-jrn-elisp-version (function).
check-okay-for-input (function).
check-okay-for-output (function).
check-open-streamlet-p (function).
check-outcome (function).
check-output-streamlet-p (function).
check-sync-value (function).
check-within-with-journaling-failure-on-nlx (function).
cleanup (function).
condition-event-p (function).
condition-to-string (function).
delete-file-journal (function).
delete-journal-from-bundle (generic function).
direction (type).
eat-event (function).
eat-events (function).
eat-full-frames-of-events (function).
echo-current-frame (function).
end-of-frame-position (function).
ensure-txn (function).
equivalent-states-p (function).
error-event-p (function).
events (generic reader).
every-event-in-frame (function).
fail-with-journaling-failure (function).
file-streamlet (class).
finalize-journal-state (function).
flet-invoked/1 (function).
format-args (generic reader).
format-control (generic reader).
fsync (function).
fsync-directory (function).
getf* (function).
handle-in-event (function).
handle-leaf-event (function).
handle-out-event (function).
in-memory-streamlet (class).
in-with-journaling-p (function).
initialize-journal-state (function).
input-direction-p (function).
invalidate-journal (function).
invoked-function (function).
invoked/1 (function).
journal-output-streamlet (function).
journaling-failure-n-resignallings (generic reader).
(setf journaling-failure-n-resignallings) (generic writer).
journals (generic reader).
jtrace-1 (macro).
jtracedp (function).
juntrace-1 (function).
list-journal-files-in-directory (function).
list-traced-functions (function).
make-file-journals-for-bundle (function).
make-in-event* (function).
make-out-event* (function).
make-record-journal-in-bundle (generic function).
match-version (function).
maybe-downgrade-version (function).
maybe-handle-invoked (function).
maybe-mark-record-as-divergent (function).
maybe-print-resignalling-message (function).
maybe-replay-outcome (function).
maybe-resignal-journaling-failure (function).
maybe-sync-after-in-event (function).
maybe-sync-after-out-event (function).
new-event (generic reader).
nlx-event-p (function).
nlx-outcome-and-maybe->logging (function).
nlx-protect (macro).
output-direction-p (function).
pattern-to-pred (function).
patterns-to-disjunction (function).
pax-pages (function).
pax-sections (function).
peek-at-out-event (function).
peek-mapped-replay-event (function).
position-to-read (function).
position-to-write (function).
pprint-streamlet (class).
print-record-closed (function).
read-file-journal-state (function).
read-file-position (generic reader).
(setf read-file-position) (generic writer).
read-mapped-replay-event (function).
reap-identical-or-non-divergent-journals (function).
reap-journals-in-bundle (function).
replay-failure-record-journal (generic reader).
replay-failure-replay-position (generic reader).
replay-filter-at-base-depth-p (function).
replay-strategy (function).
replaying-outcome-allowed-p (function).
resolve-log-record (function).
route-event (function).
safe-condition (type).
set-file-journal-completed-on-abort (function).
set-journal-state (function).
skip-events (function).
skip-events-and-maybe->recording (function).
skip-log-events (function).
stream-fd (function).
swank-toggle-jtrace (function).
turn-off-with-journaling-failure-on-nlx (function).
unsafe-condition (type).
untrace-all (function).
unwind-protect* (macro).
values-event-p (function).
version< (function).
version= (function).
with-bundle-locked (macro).
with-interrupts (macro).
with-journal-locked (macro).
with-journaling-failure-on-nlx (macro).
with-nlx-cancelled (macro).
with-standard-io-syntax* (macro).
without-interrupts (macro).
write-file-journal-state (function).
wrote-last-p (generic reader).
(setf wrote-last-p) (generic writer).
Definitions are sorted by export status, category, package, and then by lexicographic order.
The default value of the INSERTABLE argument of JOURNALED for VERSIONED-EVENTs. Binding this to T allows en-masse structural upgrades in combination with WITH-REPLAY-FILTER. Does not affect EXTERNAL-EVENTs. See @UPGRADES-AND-REPLAY.
Controls whether to decorate the trace with the depth of event. See MAKE-LOG-DECORATOR.
The JOURNAL where JTRACE writes LOG-EVENTs. By default, it is a PPRINT-JOURNAL that sets up a SYNONYM-STREAM to *TRACE-OUTPUT* and sends its output there. It pays attention to *TRACE-PRETTY*, and its log decorator is affected by *TRACE-TIME* and *TRACE-THREAD*. However, by changing JOURNAL-LOG-DECORATOR and PPRINT-JOURNAL-PRETTIFIER, content and output can be customized.
Controls whether trace should print the EVENT-NAME of @OUT-EVENTS, which is redundant with the EVENT-NAME of the corresponding @IN-EVENTS. See MAKE-LOG-DECORATOR.
If *TRACE-PRETTY* is true, then JTRACE produces output like PPRINT-EVENTS, else it’s like PRINT-EVENTS.
Controls whether to decorate the trace with the internal real-time. See MAKE-LOG-DECORATOR.
Controls whether to decorate the trace with the internal run-time. See MAKE-LOG-DECORATOR.
Controls whether to decorate the trace with the name of the originating thread. See MAKE-LOG-DECORATOR.
Controls whether to decorate the trace with a timestamp. See MAKE-LOG-DECORATOR.
A wrapper around JOURNALED to produce @FRAMEs of VERSIONED-EVENTs.
VERSION defaults to 1. CHECKED is for ensuring that supposedly
deterministic processing does not veer off the replay.
With CHECKED, BODY – which must be deterministic – is always run and
REPLAY-FAILUREs are triggered when the events generated do not match
the events in the replay journal. BODY may have side-effects.
For further discussion of determinism, see REPLAYED.
Define a function with NAME for record-and-replay testing. The
function’s BODY is executed in a WITH-BUNDLE to guarantee
replayability. The bundle in question is a FILE-BUNDLE created in
DIRECTORY. The function has a single keyword argument, RERECORD. If
RERECORD is true, the bundle is deleted with DELETE-FILE-BUNDLE to
start afresh.
Furthermore, if BODY returns normally, and it is a replay of a previous run, and EQUIVALENTP, then it is ASSERTed that the record and replay journals are EQUIVALENT-REPLAY-JOURNALS-P. If this check fails, RECORD-JOURNAL is discarded when the function returns. In addition to the replay consistency, this checks that no inserts or upgrades were performed (see @THE-REPLAY-STRATEGY).
DEFINE-INVOKED is intended for recording asynchronous function
invocations like event or signal handlers. It defines a function
that records VERSIONED-EVENTs with ARGS set to the actual arguments.
At replay, it is invoked whenever the recorded IN-EVENT becomes the
@REPLAY-EVENT.
DEFUN and CHECKED rolled into one, DEFINE-INVOKED defines a
top-level function with FUNCTION-NAME and ARGS (only simple
positional arguments are allowed) and wraps CHECKED with NAME, the
same ARGS and INSERTABLE around BODY. Whenever an IN-EVENT becomes
the @REPLAY-EVENT, and it has a DEFINE-INVOKED defined with the name
of the event, FUNCTION-NAME is invoked with EVENT-ARGS.
While BODY’s return values are recorded as usual, the defined
function returns no values to make it less likely to affect control
flow in a way that’s not possible to reproduce when the function is
called by the replay mechanism.
“‘
(defvar *state*)
(define-invoked foo (x) ("foo")
(setq *state* (1+ x)))
(define-invoked bar (x) ("bar")
(setq *state* (+ 2 x)))
(if (zerop (random 2))
(foo 0)
(bar 1))
“‘
The above can be alternatively implemented with REPLAYED explicitly
encapsulating the non-determinism:
“‘
(let ((x (replayed (choose) (random 2))))
(if (zerop x)
(checked (foo :args ‘(,x))
(setq *state* (1+ x)))
(checked (bar :args ‘(,x))
(setq *state* (+ 2 x)))))
“‘
Like DEFINE-INVOKED, but with FLET instead of DEFUN. The event
name and the function are associated in the dynamic extent of BODY.
WITH-JOURNALING does not change the bindings. The example in
DEFINE-INVOKED can be rewritten as:
“‘
(let ((state nil))
(flet-invoked ((foo (x) ("foo")
(setq state (1+ x)))
(bar (x) ("bar")
(setq state (+ 2 x))))
(if (zerop (random 2))
(foo 0)
(bar 1))))
“‘
A wrapper around JOURNALED to produce @FRAMEs of LOG-EVENTs. That
is, VERSION is always NIL, and some irrelevant arguments are
omitted. The related LOGGED creates a single LEAF-EVENT.
With FRAMED, BODY is always run and no REPLAY-FAILUREs are triggered. BODY is not required to be deterministic, and it may have side-effects.
JOURNALED generates events upon entering and leaving the dynamic
extent of BODY (also known as the journaled @BLOCK), which we call
the @IN-EVENTS and @OUT-EVENTS. Between generating the two events,
BODY is typically executed normally (except for
@REPLAYING-THE-OUTCOME).
Where the generated events are written is determined by the :RECORD
argument of the enclosing WITH-JOURNALING. If there is no enclosing
WITH-JOURNALING and LOG-RECORD is NIL, then event recording is
turned off and JOURNALED imposes minimal overhead.
- NAME can be of any type except [NULL][type], not evaluated. For
names, and for anything that gets written to a journal, a
non-keyword symbol is a reasonable choice as it can be easily made
unique. However, it also exposes the package structure, which
might make reading stuff back more difficult. Keywords and strings
do not have this problem.
- ARGS can be of any type, but is typically a list.
Also see @LOG-RECORD in the @LOGGING section. For a description of VERSION, INSERTABLE, REPLAY-VALUES and REPLAY-CONDITION, see @JOURNALED-FOR-REPLAY.
Like CL:TRACE, JTRACE takes a list of symbols. When functions
denoted by those NAMES are invoked, their names, arguments and
outcomes are printed in human readable form to *TRACE-OUTPUT*. These
values may not be @READABLE, JTRACE does not care.
The format of the output is the same as that of PPRINT-EVENTS.
Behind the scenes, JTRACE encapsulates the global functions with
NAMES in wrapper that behaves as if ‘FOO‘ in the example above was
defined like this:
“‘
(defun foo (x)
(framed (foo :args ‘(,x) :log-record *trace-journal*)
(1+ x)))
“‘
If JTRACE is invoked with no arguments, it returns the list of
symbols currently traced.
On Lisps other than SBCL, where a function encapsulation facility is
not available or it is not used by Journal, JTRACE simply sets
SYMBOL-FUNCTION. This solution loses the tracing encapsulation when
the function is recompiled. On these platforms, ‘(JTRACE)‘ also
retraces all functions that should be traced but aren’t.
The main advantage of JTRACE over CL:TRACE is the ability to trace errors, not just normal return values. As it is built on JOURNALED, it can also detect – somewhat heuristically – THROWs and similar.
Like CL:UNTRACE, JUNTRACE makes it so that the global functions denoted by the symbols NAMES are no longer traced by JTRACE. When invoked with no arguments, it untraces all traced functions.
LOGGED creates a single LEAF-EVENT, whose name is the string
constructed by FORMAT. For example:
“‘
(with-journaling (:record t)
(logged () "Hello, ~A." "world")
(list-events))
=> ((:LEAF "Hello, world."))
“‘
LEAF-EVENTs are LOG-EVENTs with no separate in- and out-events. They
have an EVENT-NAME and no other properties. Use LOGGED for
point-in-time textual log messages, and JOURNALED with VERSION
NIL (i.e. FRAMED) to provide context.
Also, see @LOG-RECORD.
A wrapper around JOURNALED to produce @FRAMEs of EXTERNAL-EVENTs.
VERSION is :INFINITY. REPLAYED is for primarily for marking and
isolating non-deterministic processing.
With REPLAYED, the IN-EVENT is checked for consistency with the replay (as with CHECKED), but BODY is not run (assuming it has a recorded @EXPECTED-OUTCOME), and the outcome in the OUT-EVENT is reproduced (see @REPLAYING-THE-OUTCOME). For this scheme to work, REPLAYED requires its BODY to be side-effect free, but it may be non-deterministic.
Save READ-POSITION of STREAMLET, execute BODY, and make sure to restore the saved read position.
This is like WITH-JOURNALING where the REPLAY-JOURNAL is the last
successfully completed one in BUNDLE, and the RECORD-JOURNAL is a
new one created in BUNDLE. When WITH-BUNDLE finishes, the record
journal is in JOURNAL-STATE :FAILED or :COMPLETED.
To avoid accumulating useless data, the new record is immediately
deleted when WITH-BUNDLE finishes if it has not diverged from the
replay journal (see JOURNAL-DIVERGENT-P). Because :FAILED journals
are always divergent in this sense, they are deleted instead based
on whether there is already a previous failed journal in the bundle
and the new record is identical to that journal (see
IDENTICAL-JOURNALS-P).
It is a JOURNAL-ERROR to have concurrent or nested WITH-BUNDLEs on the same bundle.
Turn recording and/or replaying of events on or off for the
duration of BODY. Both RECORD and REPLAY should be a JOURNAL
designator (in the sense of TO-JOURNAL) or NIL.
If RECORD designates a JOURNAL, then events generated by enclosed
JOURNALED @BLOCKs are written to that journal (with exceptions, see
the LOG-RECORD argument of JOURNALED). If REPLAY designates a
JOURNAL, then the generated events are matched against events from
that journal according to the rules of @REPLAY.
A JOURNAL-ERROR is signalled if RECORD is a JOURNAL that has been
previously recorded to by another WITH-JOURNALING (that is, if its
JOURNAL-STATE is not :NEW) or if REPLAY is a JOURNAL that is not a
complete recording of successful replay (i.e. its JOURNAL-STATE is
not :COMPLETED). These checks are intended to catch mistakes that
would render the new or existing records unusable for replay. When
WITH-JOURNALING finishes, the RECORD journal is marked :COMPLETED or
:FAILED in its JOURNAL-STATE.
REPLAY-EOJ-ERROR-P controls whether END-OF-JOURNAL is signalled when
a new event is being matched to the replay journal from which there
are no more events to read. If there was a JOURNALING-FAILURE or a
REPLAY-FAILURE during execution, then END-OF-JOURNAL is not
signalled.
If BODY completes successfully, but REPLAY has unprocessed events,
then REPLAY-INCOMPLETE is signalled.
WITH-JOURNALING for different RECORD journals can be nested and run independently.
This is like WITH-OPEN-FILE but for JOURNALs.
Open the journal designated by JOURNAL (see TO-JOURNAL) with
OPEN-STREAMLET, passing DIRECTION along, and bind VAR to the
resulting STREAMLET. Call CLOSE-STREAMLET after BODY finishes. If
JOURNAL is NIL, then VAR is bound to NIL and no streamlet is
created.
WITH-REPLAY-FILTER performs journal upgrade during replay by allowing events to be transformed as they are read from the replay journal or skipped if they match some patterns. For how to add new blocks in a code upgrade, see JOURNALED’s :INSERTABLE argument. In addition, it also allows some control over @REPLAYING-THE-OUTCOME.
- MAP: A function called with an event read from the replay journal
which returns a transformed event. See @EVENTS-REFERENCE. MAP
takes effect before before SKIP.
- SKIP: In addition to filtering out LOG-EVENTs (which always
happens during replay), filter out all events that belong to
frames that match any of its SKIP patterns. Filtered out events
are never seen by JOURNALED as it replays events. SKIP patterns
are of the format ‘(&KEY NAME VERSION<)‘, where VERSION< is a
valid [EVENT-VERSION][type], and NAME may be NIL, which acts as a
wildcard.
SKIP is for when JOURNALED @BLOCKs are removed from the code,
which would render replaying previously recorded journals
impossible. Note that, for reasons of safety, it is not possible
to filter EXTERNAL-EVENTs.
- NO-REPLAY-OUTCOME is a list of EVENT-NAMEs. @REPLAYING-THE-OUTCOME
is prevented for frames with EQUAL names. See
@TESTING-ON-MULTIPLE-LEVELS for an example.
WITH-REPLAY-FILTER affects only the immediately enclosing
WITH-JOURNALING. A WITH-REPLAY-FILTER nested within another in the
same WITH-JOURNALING inherits the SKIP patterns of its parent, to
which it adds its own. The MAP function is applied to before the
parent’s MAP.
Examples of SKIP patterns:
“‘
;; Match events with name FOO and version 1, 2, 3 or 4
(:name foo :version< 5)
;; Match events with name BAR and any version
(:name bar :version< :infinity)
;; Same as the previous
(:name bar)
;; Match all names
(:name nil)
;; Same as the previous
()
“‘
Skipping can be thought of as removing nodes of the tree of frames,
connecting its children to its parent. The following example removes
frames ‘J1‘ and ‘J2‘ from around ‘J3‘, the ‘J1‘ frame from within
‘J3‘, and the third ‘J1‘ frame.
“‘
(let ((journal (make-in-memory-journal)))
;; Record trees J1 -> J2 -> J3 -> J1, and J1.
(with-journaling (:record journal)
(checked (j1)
(checked (j2)
(checked (j3)
(checked (j1)
42))))
(checked (j1)
7))
;; Filter out all occurrences of VERSIONED-EVENTs named J1 and
;; J2 from the replay, leaving only J3 to match.
(with-journaling (:replay journal :record t :replay-eoj-error-p t)
(with-replay-filter (:skip ’((:name j1) (:name j2)))
(checked (j3)
42))))
“‘
Open REPLAY-JOURNAL for reading with WITH-OPEN-JOURNAL, set the READ-POSITION on it to the event next read by the @REPLAY mechanism (which is never a LOG-EVENT). The low-level @READING-FROM-STREAMLETS api is then available to inspect the contents of the replay. It is an error if REPLAY-JOURNAL is NIL.
read-position (generic function).
set-read-position (generic function).
Delete all journal files (‘*.jrn‘) from DIRECTORY. Delete the directory if empty after the journal files were deleted, else signal an error. Existing FILE-BUNDLE objects are not updated, so MAKE-FILE-JOURNAL with FORCE-RELOAD may be required.
Return the arguments of IN-EVENT, normally populated using the ARGS form in JOURNALED.
Return how the journaled @BLOCK finished. See [EVENT-EXIT][type] for the possible types.
The name of an event can be of any type. It is often a symbol or a string. When replaying, names are compared with EQUAL. All EVENTs have names. The names of the in- and out-events belonging to the same @FRAME are the same.
Return the outcome of the @FRAME (or loosely speaking of a @BLOCK) to which OUT-EVENT belongs.
Return the version of EVENT of type EVENT-VERSION.
Return whether EVENT-1 and EVENT-2 represent the same event.
In- and out-events belonging to the same @FRAME are _not_ the same
event. EVENT-OUTCOMEs are not compared when EVENT-EXIT is :ERROR to
avoid undue dependence on implementation specific string
representations. This function is useful in conjunction with
MAKE-IN-EVENT and MAKE-OUT-EVENT to write tests.
Convert a flat list of events, such as those returned by LIST-EVENTS,
to a nested list representing the @FRAMEs. Each frame is a list of
the form ‘(<in-event> <nested-frames>* <out-event>?)‘. Like in
PRINT-EVENTS, EVENTS may be a JOURNAL.
“‘
(events-to-frames ’((:in foo :args (1 2))
(:in bar :args (7))
(:leaf "leaf")
(:out bar :values (8))
(:out foo :values (2))
(:in foo :args (3 4))
(:in bar :args (8))))
=> (((:IN FOO :ARGS (1 2))
((:IN BAR :ARGS (7))
(:LEAF "leaf")
(:OUT BAR :VALUES (8)))
(:OUT FOO :VALUES (2)))
((:IN FOO :ARGS (3 4)) ((:IN BAR :ARGS (8)))))
“‘
Note that, as in the above example, incomplete frames (those without an OUT-EVENT) are included in the output.
See if OUT-EVENT has an @EXPECTED-OUTCOME.
Return a function suitable as the CONDITION argument of JOURNALED, which returns the type of its single argument as a string if it is of TYPE, else NIL.
See if EVENT is an EXTERNAL-EVENT.
See if EVENT is a IN-EVENT.
See if STREAMLET was opened for input (the DIRECTION argument of OPEN-STREAMLET was :INPUT or :IO).
Copy ‘mgl-jrn.el‘ distributed with this package to TARGET-DIR.
See if WITH-JOURNALING recorded any event so far in this journal
that was not EQUAL to its @REPLAY-EVENT or it had no corresponding
replay event. This completely ignores LOG-EVENTs in both journals
being compared and can be called any time during @REPLAY. It plays a
role in WITH-BUNDLE deciding when a journal is important enough to
keep and also in @SYNCHRONIZATION-WITH-IN-MEMORY-JOURNALS.
The position of the first mismatch is available via JOURNAL-REPLAY-MISMATCH.
See if EVENT is a LEAF-EVENT.
Return a list of all the events in the journal designated by JOURNAL. Calls SYNC-JOURNAL first to make sure that all writes are taken into account.
See if EVENT is a LOG-EVENT.
Return a FILE-BUNDLE object backed by FILE-JOURNALs in DIRECTORY.
See [MAX-N-FAILED][(accessor bundle)] and
[MAX-N-COMPLETED][(accessor bundle)]. For a description of SYNC, see
@SYNCHRONIZATION-STRATEGIES.
If there is already a FILE-BUNDLE with the same directory (according to TRUENAME), return that object is returned if it has the same MAX-N-FAILED, MAX-N-COMPLETED and SYNC options, else JOURNAL-ERROR is signalled.
Return a FILE-JOURNAL backed by the file with PATHNAME. The file is
created when the journal is opened for writing. For a description of
SYNC, see @SYNCHRONIZATION-STRATEGIES.
If there is already an existing FILE-JOURNAL backed by the same
file, then that object is returned. If the existing object has
different options (e.g. it has SYNC T while the SYNC argument is NIL
here), then a JOURNAL-ERROR is signalled.
If there is already an existing FILE-JOURNAL backed by the same file, the JOURNAL-STATE is not :NEW, but the file doesn’t exist, then the existing object is __invalidated__: attempts to write will fail with JOURNAL-ERROR. If the existing journal object is being written, then invalidation fails with a JOURNAL-ERROR. After invalidation, a new FILE-JOURNAL object is created.
Create an IN-EVENT with NAME, VERSION (of type EVENT-VERSION) and ARGS as its EVENT-NAME, [EVENT-VERSION][function] and EVENT-ARGS.
Create a new IN-MEMORY-BUNDLE with [MAX-N-FAILED][(accessor bundle)] and [MAX-N-COMPLETED][(accessor bundle)]. SYNC and SYNC-FN are passed on to MAKE-IN-MEMORY-JOURNAL.
Create an IN-MEMORY-JOURNAL.
The returned journal’s JOURNAL-STATE will be set to STATE. If STATE
is NIL, then it is replaced by a default value, which is :COMPLETED
if the EVENTS argument is provided, else it is :NEW.
Thus, ‘(make-in-memory-journal)‘ creates a journal suitable for
recording, and to make a replay journal, use :STATE :COMPLETED with
some sequence of EVENTS:
“‘
(make-in-memory-journal :events ’((:in foo :version 1)) :state :completed)
“‘
SYNC determines when SYNC-FN will be invoked on the RECORD-JOURNAL.
SYNC defaults to T if SYNC-FN, else to NIL. For a description of
possible values, see @SYNCHRONIZATION-STRATEGIES. For more
discussion, see @SYNCHRONIZATION-WITH-IN-MEMORY-JOURNALS.
Create a LEAF-EVENT with NAME.
Return a function suitable as JOURNAL-LOG-DECORATOR that may add
a string timestamp, the internal real-time or run-time (both in
seconds), the name of the thread, to events, which will be handled
by PRETTIFY-EVENT. If DEPTH, then PRETTIFY-EVENT will the nesting
level of the event being printed. If OUT-NAME, the PRETTIFY-EVENT
will print the name of @OUT-EVENTS.
All arguments are @BOOLEAN-VALUED-SYMBOLs.
“‘
(funcall (make-log-decorator :depth t :out-name t :thread t
:time t :real-time t :run-time t)
(make-leaf-event :foo))
=> (:LEAF :FOO :DEPTH T :OUT-NAME T :THREAD "worker"
:TIME "2023-05-26T12:27:44.172614+01:00"
:REAL-TIME 2531.3254 :RUN-TIME 28.972797)
“‘
Create an OUT-EVENT with NAME, VERSION (of type EVENT-VERSION), EXIT (of type EVENT-EXIT), and OUTCOME as its EVENT-NAME, [EVENT-VERSION][function], [EVENT-EXIT][function] and EVENT-OUTCOME.
Creates a PPRINT-JOURNAL.
See if EVENT is an OUT-EVENT.
See if STREAMLET was opened for input (the DIRECTION argument of OPEN-STREAMLET was :OUTPUT or :IO).
Return the @REPLAY-EVENT to be read from REPLAY-JOURNAL. This is
roughly equivalent to
“‘
(when (replay-journal)
(with-replay-streamlet (streamlet)
(peek-event streamlet))
“‘
except PEEK-REPLAY-EVENT takes into account WITH-REPLAY-FILTER
:MAP, and it may return ‘(:INDETERMINATE)‘ if WITH-REPLAY-FILTER
:SKIP is in effect and what events are to be skipped cannot be
decided until the next in-event generated by the code.
Imagine a business process for paying an invoice. In the first
version of this process, we just pay the invoice:
“‘
(replayed (pay))
“‘
We have left the implementation of PAY blank. In the second version,
we need to get an approval first:
“‘
(when (replayed (get-approval)
(= (random 2) 0))
(replayed (pay)))
“‘
Replaying a journal produced by the first version of the code with
the second version would run into difficulties because inserting
EXTERNAL-EVENTs is tricky.
We have to first decide how to handle the lack of approval in the first version. Here, we just assume the processes started by the first version get approval automatically. The implementation is based on a dummy ‘PROCESS‘ block whose version is bumped when the payment process changes and is inspected at the start of journaling.
When v1 is replayed with v2, we introduce an INSERTABLE, versioned
‘GET-APPROVAL‘ block that just returns T. When replaying the code
again, still with v2, the ‘GET-APPROVAL‘ block will be upgraded to
:INFINITY.
“‘
(let ((bundle (make-in-memory-bundle)))
;; First version of the payment process. Just pay.
(with-bundle (bundle)
(checked (process :version 1))
(replayed (pay)))
;; Second version of the payment process. Only pay if approved.
(loop repeat 2 do
(with-bundle (bundle)
(let ((replay-process-event (peek-replay-event)))
(checked (process :version 2))
(when (if (and replay-process-event
(< (event-version replay-process-event) 2))
;; This will be upgraded to :INFINITY the second
;; time around the LOOP.
(checked (get-approval :insertable t)
t)
(replayed (get-approval)
(= (random 2) 0)))
(replayed (pay)))))))
“‘
Like PRINT-EVENTS, but produces terser, more human readable
output.
“‘
(pprint-events ’((:in log :args ("first arg" 2))
(:in versioned :version 1 :args (3))
(:leaf "This is a leaf, not a frame.")
(:out versioned :version 1 :values (42 t))
(:out log :condition "a :CONDITION outcome")
(:in log-2)
(:out log-2 :nlx nil)
(:in external :version :infinity)
(:out external :version :infinity
:error ("ERROR" "an :ERROR outcome"))))
..
.. (LOG "first arg" 2)
.. (VERSIONED 3) v1
.. This is a leaf, not a frame.
.. => 42, T
.. =C "a :CONDITION outcome"
.. (LOG-2)
.. =X
.. (EXTERNAL) ext
.. =E "ERROR" "an :ERROR outcome"
=> ; No value
“‘
The function given as the PRETTIFIER argument formats individual
events. The above output was produced with PRETTIFY-EVENT. For a
description of PRETTIFIER’s arguments see PRETTIFY-EVENT.
Write EVENT to STREAM in a somewhat human-friendly format.
This is the function PPRINT-JOURNAL, PPRINT-EVENTS, and @TRACING use
by default. In addition to the basic example in PPRINT-EVENTS,
@DECORATION on events is printed before normal, indented output like
this:
“‘
(pprint-events ’((:leaf "About to sleep" :time "19:57:00" :function "FOO")))
..
.. 19:57:00 FOO: About to sleep
“‘
DEPTH is the nesting level of the EVENT. Top-level events have depth
0. PRETTIFY-EVENT prints indents the output after printing the
decorations by 2 spaces per depth.
Print EVENTS to STREAM as lists, starting a new line for each
event and indenting them according to their nesting structure.
EVENTS may be a sequence or a JOURNAL, in which case LIST-EVENTS is
called on it first.
“‘
(print-events ’((:in log :args ("first arg" 2))
(:in versioned :version 1 :args (3))
(:out versioned :version 1 :values (42 t))
(:out log :condition "a :CONDITION outcome")
(:in log-2)
(:out log-2 :nlx nil)
(:in external :version :infinity)
(:out external :version :infinity
:error ("ERROR" "an :ERROR outcome"))))
..
.. (:IN LOG :ARGS ("first arg" 2))
.. (:IN VERSIONED :VERSION 1 :ARGS (3))
.. (:OUT VERSIONED :VERSION 1 :VALUES (42 T))
.. (:OUT LOG :CONDITION "a :CONDITION outcome")
.. (:IN LOG-2)
.. (:OUT LOG-2 :NLX NIL)
.. (:IN EXTERNAL :VERSION :INFINITY)
.. (:OUT EXTERNAL :VERSION :INFINITY :ERROR ("ERROR" "an :ERROR outcome"))
=> ; No value
“‘
Return the [JOURNAL][class] in which events are currently being recorded (see WITH-JOURNALING and WITH-BUNDLE) or NIL.
Return the [JOURNAL][class] from which events are currently being replayed (see WITH-JOURNALING and WITH-BUNDLE) or NIL.
Durably persist changes made to JOURNAL if JOURNAL-SYNC is T.
The changes that are persisted are
- WRITE-EVENTs and JOURNAL-STATE changes made in an enclosing
WITH-JOURNALING; and
- LOG-RECORDs from any thread.
In particular, writes made in a WITH-JOURNALING in another thread are not persisted. SYNC-JOURNAL is a noop if JOURNAL-SYNC is NIL. It is safe to call from any thread.
See if OUT-EVENT has an @UNEXPECTED-OUTCOME.
A utility to create a function suitable as the [VALUES][argument]
argument of JOURNALED. The VALUES function is called with the list
of values returned by the @BLOCK and returns a transformed set of
values that may be recorded in a journal. While arbitrary
transformations are allowed, ‘VALUES->‘ handles the common case of
transforming individual elements of the list independently by
calling the functions in FN with the values of the list of the same
position.
“‘
(funcall (values-> #’1+) ’(7 :something))
=> (8 :SOMETHING)
“‘
Note how ‘#’1+‘ is applied only to the first element of the values
list. The list of functions is shorter than the values list, so
‘:SOMETHING‘ is not transformed. A value can be left explicitly
untransformed by specifying #’IDENTITY or NIL as the function:
“‘
(funcall (values-> #’1+ nil #’symbol-name)
’(7 :something :another))
=> (8 :SOMETHING "ANOTHER")
“‘
The inverse of ‘VALUES->‘, this returns a function suitable as
the REPLAY-VALUES argument of JOURNALED. It does pretty much what
‘VALUES->‘ does, but the function returned returns the transformed
list as multiple values instead of as a list.
“‘
(funcall (values<- #’1-) ’(8 :something))
=> 7
=> :SOMETHING
“‘
See if EVENT is a VERSIONED-EVENT.
Close STREAMLET, which was returned by
OPEN-STREAMLET. After closing, STREAMLET may not longer be used for
IO.
file-streamlet)) ¶in-memory-streamlet)) ¶pprint-streamlet)) ¶file-bundle)) ¶The directory where the files backing the FILE-JOURNALs in the FILE-BUNDLE are kept.
See if two journals are equivalent when used the
for REPLAY in WITH-JOURNALING. EQUIVALENT-REPLAY-JOURNALS-P is like
IDENTICAL-JOURNALS-P, but it ignores LOG-EVENTs and allows events
with EVENT-EXIT :ERROR to differ in their outcomes, which may very
well be implementation specific, anyway. Also, it considers two
groups of states as different :NEW, :REPLAYING, :MISMATCHED, :FAILED
vs :RECORDING, :LOGGING, COMPLETED.
Compare two journals in a strict sense: whether
they have the same JOURNAL-STATE and the lists of their events (as
in LIST-EVENTS) are EQUAL.
in-memory-journal) (journal-2 in-memory-journal)) ¶end-of-journal)) ¶journal-error)) ¶in-memory-journal)) ¶A sequence of events in the journal. Not to be mutated by client code.
journal)) ¶journal)) ¶If non-NIL, this is a function to add @DECORATION
to LOG-EVENTs before they are written to a journal. The only
allowed transformation is to _append_ a plist to the event, which
is a plist itself. The keys can be anything.
in-memory-journal)) ¶The length of JOURNAL-EVENTS at the time of the most recent invocation of SYNC-FN.
journaling-failure)) ¶Return NIL or a function of no arguments suitable
as a finalizer for STREAMLET. That is, a function that closes
STREAMLET but holds no reference to it. This is intended for
streamlets that are not dynamic-extent, so using WITH-OPEN-JOURNAL
is not appropriate.
file-streamlet)) ¶in-memory-streamlet)) ¶pprint-streamlet)) ¶bundle)) ¶bundle)) ¶If MAX-N-COMPLETED is non-NIL, and the number of
journals of [JOURNAL-STATE][type] :COMPLETED in the bundle exceeds
its value, then some journals (starting with the oldest) are
deleted.
bundle)) ¶bundle)) ¶If MAX-N-FAILED is non-NIL, and the number of
journals of [JOURNAL-STATE][type] :FAILED in the bundle exceeds
its value, then some journals (starting with the oldest) are
deleted.
Return a STREAMLET suitable for performing I/O on
JOURNAL. DIRECTION (defaults to :INPUT) is one of :INPUT, :OUTPUT,
:IO, and it has the same purpose as the similarly named argument of
CL:OPEN.
file-journal) &key direction) ¶in-memory-journal) &key direction) ¶pprint-journal) &key direction) ¶Return true if STREAMLET is open. STREAMLETs are
open until they have been explicitly closed with CLOSE-STREAMLET.
file-journal)) ¶The pathname of the file backing the journal.
Read the next event from STREAMLET without changing
the read position, or return NIL if there is no event to be read.
file-streamlet)) ¶in-memory-streamlet)) ¶pprint-journal)) ¶pprint-journal)) ¶A function like PRETTIFY-EVENT that writes an
event to a stream. Only used when PPRINT-JOURNAL-PRETTY, this is
the output format customization knob. Also see @DECORATIONs.
pprint-journal)) ¶pprint-journal)) ¶Whether to use PPRINT-JOURNAL-PRETTIFIER or write events in as the property lists they are. A @BOOLEAN-VALUED-SYMBOL.
pprint-journal)) ¶pprint-journal)) ¶The stream where events are dumped. May be set any time to another STREAM.
Read the event at the current read position from
STREAMLET, and move the read position to the event after. If there
are no more events, signal END-OF-JOURNAL or return NIL depending on
EOJ-ERROR-P. Signals STREAMLET-ERROR if STREAMLET is not
INPUT-STREAMLET-P or not OPEN-STREAMLET-P.
file-streamlet) &optional eoj-error-p) ¶in-memory-streamlet) &optional eoj-error-p) ¶Return an integer that identifies the position of
the next event to be read from STREAMLET. ‘SETF‘able, see
SET-READ-POSITION.
file-streamlet)) ¶in-memory-streamlet)) ¶automatically generated reader method
replay-failure)) ¶replay-failure)) ¶replay-failure)) ¶Make it so that upon @ABORTED-EXECUTION,
STREAMLET’s JOURNAL will be in JOURNAL-STATE :COMPLETED when loaded
fresh (e.g. when creating a FILE-JOURNAL with an existing file). Any
previously written events must be persisted before making this
change. Before REQUEST-COMPLETED-ON-ABORT is called, a journal must
be reloaded in state :FAILED.
It is permissible to defer carrying out this request until the next SYNC-STREAMLET call. If the request was carried out, return true. If it was deferred, return NIL.
file-streamlet)) ¶in-memory-streamlet)) ¶pprint-streamlet)) ¶Set the read position of STREAMLET to POSITION, which must have been acquired from READ-POSITION.
file-streamlet) read-position) ¶in-memory-streamlet) read-position) ¶streamlet-error)) ¶Durably persist the effects of all preceding
WRITE-EVENT calls made via STREAMLET to its journal and any deferred
REQUEST-COMPLETED-ON-ABORT in this order.
file-streamlet)) ¶in-memory-streamlet)) ¶pprint-streamlet)) ¶Return the journal designated by DESIGNATOR or
signal an error. The default implementation:
- returns DESIGNATOR itself if it is of type JOURNAL, - returns a new IN-MEMORY-JOURNAL if DESIGNATOR is T, - returns a new FILE-JOURNAL if DESIGNATOR is a PATHNAME.
Write EVENT to STREAMLET.
Writing always happens at the end of STREAMLET’s journal regardless
of the READ-POSITION, and the read position is not changed. Signals
STREAMLET-ERROR if STREAMLET is not OUTPUT-STREAMLET-P or not
OPEN-STREAMLET-P.
file-streamlet)) ¶in-memory-streamlet)) ¶pprint-streamlet)) ¶Return an integer that identifies the position of the next event to be written to STREAMLET.
file-streamlet)) ¶in-memory-streamlet)) ¶file-journal) stream) ¶in-memory-journal) stream) ¶file-bundle) stream) ¶Signalled when a @DATA-EVENT is about to be recorded
in JOURNAL-STATE :MISMATCHED or :LOGGING. Since the data event will
not be replayed that constitutes data loss.
This might be signalled by the replay mechanism if WITH-JOURNALING’s REPLAY-EOJ-ERROR-P is true. Unlike REPLAY-FAILUREs, this does not affect JOURNAL-STATE of RECORD-JOURNAL. At a lower level, it is signalled by READ-EVENT upon reading past the end of the JOURNAL if EOJ-ERROR-P.
Signalled by WITH-JOURNALING, WITH-BUNDLE and by @LOG-RECORD. It is also signalled by the low-level streamlet interface (see @STREAMLETS-REFERENCE).
error.
The JOURNAL in question.
:journal
This slot is read-only.
:format-control
This slot is read-only.
(quote nil)
:format-args
This slot is read-only.
Signalled during the dynamic extent of
WITH-JOURNALING when an error threatens to leave the journaling
mechanism in an inconsistent state. These include I/O errors
encountered reading or writing journals by WITH-JOURNALING,
JOURNALED, LOGGED, WITH-REPLAY-FILTER, SYNC-JOURNAL, and also
STORAGE-CONDITIONs, assertion failures, errors calling JOURNALED’s
[VALUES][argument] and [CONDITION][argument] function arguments.
Crucially, this does not apply to [non-local exit][clhs]s from other
code, such as JOURNALED @BLOCKs, whose error handling is largely
unaltered (see @OUT-EVENTS and @REPLAY-FAILURES).
In general, any [non-local exit][clhs] from critical parts of the
code is turned into a JOURNALING-FAILURE to protect the integrity of
the RECORD-JOURNAL. The condition that caused the unwinding is in
JOURNALING-FAILURE-EMBEDDED-CONDITION, or NIL if it was a pure
[non-local exit][clhs] like THROW. This is a SERIOUS-CONDITION, not
to be handled within WITH-JOURNALING.
After a JOURNALING-FAILURE, the journaling mechanism cannot be
trusted anymore. The REPLAY-JOURNAL might have failed a read and be
out-of-sync. The RECORD-JOURNAL may have missing events (or even
half-written events with FILE-JOURNALs without SYNC, see
@SYNCHRONIZATION-STRATEGIES), and further writes to it would risk
replayability, which is equivalent to database corruption. Thus,
upon signalling JOURNALING-FAILURE, JOURNAL-STATE is set to
- :COMPLETED if the journal is in state :RECORDING or :LOGGING and
the transition to :RECORDING was reflected in storage,
- else it is set to :FAILED.
After a JOURNALING-FAILURE, any further attempt within the affected
WITH-JOURNALING to use the critical machinery mentioned
above (JOURNALED, LOGGED, etc) resignals the same journal failure
condition. As a consequence, the record journal cannot be changed,
and the only way to recover is to leave WITH-JOURNALING. This does
not affect processing in other threads, which by design cannot write
to the record journal.
Note that in contrast with JOURNALING-FAILURE and REPLAY-FAILURE, which necessitate leaving WITH-JOURNALING to recover from, the other conditions – JOURNAL-ERROR, and STREAMLET-ERROR – are subclasses of [ERROR][condition] as the their handling need not be so heavy-handed.
Signalled (with SIGNAL: this is not an
[ERROR][condition]) by JOURNALED when a VERSIONED-EVENT or an
EXTERNAL-EVENT had an UNEXPECTED-OUTCOME while in JOURNAL-STATE
:RECORDING. Upon signalling this condition, JOURNAL-STATE is set to
:LOGGING, thus no more events can be recorded that will affect
replay of the journal being recorded. The event that triggered this
condition is recorded in state :LOGGING, with its version
downgraded. Since @REPLAY (except @INVOKED) is built on the
assumption that control flow is deterministic, an unexpected outcome
is significant because it makes this assumption to hold unlikely.
Also see REPLAY-UNEXPECTED-OUTCOME.
condition.
Signalled when the new event’s and @REPLAY-EVENT’s EVENT-ARGS are not EQUAL. The REPLAY-FORCE-UPGRADE restart is provided.
A abstract superclass (never itself signalled) for
all kinds of mismatches between the events produced and the replay
journal. Signalled only in JOURNAL-STATE :REPLAYING and only once
per WITH-JOURNALING. If a REPLAY-FAILURE is signalled for an EVENT,
then the event will be recorded, but RECORD-JOURNAL will transition
to JOURNAL-STATE :MISMATCHED. Like JOURNALING-FAILURE, this is a
serious condition because it is to be handled outside the enclosing
WITH-JOURNALING. If a REPLAY-FAILURE were to be handled inside the
WITH-JOURNALING, keep in mind that in :MISMATCHED, replay always
uses the _insert_ replay strategy (see @THE-REPLAY-STRATEGY).
serious-condition.
The event being generated.
:new-event
This slot is read-only.
The event read from the replay journal.
:replay-event
This slot is read-only.
The RECORD-JOURNAL in effect at the time of signalling the error.
(quote (journal:record-journal))
This slot is read-only.
The REPLAY-JOURNAL in effect at the time of signalling the error.
(quote (journal:replay-journal))
This slot is read-only.
(quote (journal:read-position journal::*replay-streamlet*))
This slot is read-only.
Signalled if there are unprocessed non-log events in REPLAY-JOURNAL when WITH-JOURNALING finishes and the body of WITH-JOURNALING returned normally, which is to prevent this condition to cancel an ongoing unwinding. No restarts are provided.
Signalled when the new event’s and @REPLAY-EVENT’s EVENT-NAME are not EQUAL. The REPLAY-FORCE-INSERT, REPLAY-FORCE-UPGRADE restarts are provided.
Signalled when the new event’s and @REPLAY-EVENT’s EVENT-EXIT and/or EVENT-OUTCOME are not EQUAL. The REPLAY-FORCE-UPGRADE restart is provided.
Signalled when the new event has an
@UNEXPECTED-OUTCOME. Note that the @REPLAY-EVENT always has an
@EXPECTED-OUTCOME due to the logic of RECORD-UNEXPECTED-OUTCOME. No
restarts are provided.
Signalled when the new event and the @REPLAY-EVENT
have the same EVENT-NAME, but the new event has a lower version. The
REPLAY-FORCE-UPGRADE restart is provided.
Like CL:STREAM-ERROR: failures pertaining to I/O on
a closed STREAMLET or of the wrong DIRECTION. Actual I/O errors are
_not_ encapsulated in STREAMLET-ERROR.
A BUNDLE consists of a sequence of journals which
are all reruns of the same code, hopefully making more and more
progress towards completion. These journals are @REPLAYs of the
previous successful one, extending it with new events. Upon
replay (see WITH-BUNDLE), the latest journal in the bundle in
JOURNAL-STATE :COMPLETED plays the role of the replay journal, and a
new journal is added to the bundle for recording. If the replay
succeeds, this new journal eventually becomes :COMPLETED and takes
over the role of the replay journal for future replays until another
replay succeeds. When the bundle is created and it has no journals
yet, the replay journal is an empty, completed one.
This is an abstract base class. Direct subclasses are IN-MEMORY-BUNDLE and FILE-BUNDLE.
:journals
If MAX-N-FAILED is non-NIL, and the number of
journals of [JOURNAL-STATE][type] :FAILED in the bundle exceeds
its value, then some journals (starting with the oldest) are
deleted.
1
:max-n-failed
If MAX-N-COMPLETED is non-NIL, and the number of
journals of [JOURNAL-STATE][type] :COMPLETED in the bundle exceeds
its value, then some journals (starting with the oldest) are
deleted.
1
:max-n-completed
(bordeaux-threads:make-recursive-lock "a bundle-lock")
0
A FILE-BUNDLE is a BUNDLE that is built on FILE-JOURNALs. It provides easy replay-based persistence.
A FILE-JOURNAL is a journal whose contents and
JOURNAL-STATE are persisted in a file. This is the [JOURNAL][class]
subclass with out-of-the-box persistence, but see @FILE-BUNDLES for
a more full-featured solution for repeated @REPLAYs.
Since serialization in FILE-JOURNALs is built on top of Lisp READ
and WRITE, everything that JOURNALED records in events (i.e. its
NAME, ARGS arguments, and also the return VALUES of the block, or
the value returned by CONDITION) must be @READABLE.
File journals are human-readable and editable by hand with some
care. When editing, the following needs to be remembered:
- The first character of the file represents its JOURNAL-STATE. It
is a ‘#\Space‘ (for state :NEW, :REPLAYING, :MISMATCHED and
:FAILED), or a ‘#\Newline‘ (for state :RECORDING, :LOGGING and
:COMPLETED).
- If the journal has SYNC (see @SYNCHRONIZATION-STRATEGIES), then
between two events, there may be ‘#\Del‘ (also called ‘#\Rubout‘)
or ‘#\Ack‘ characters (CHAR-CODE 127 and 6). ‘#\Del‘ marks the end
of the journal contents that may be read back: it’s kind of an
uncommitted-transaction marker for the events that follow it.
‘#\Ack‘ characters, of which there may be many in the file, mark
the sequence of events until the next marker of either kind as
valid (or committed). ‘#\Ack‘ characters are ignored when reading
the journal.
Thus, when editing a file, don’t change the first character and leave the ‘#\Del‘ character, if any, where it is. Also see @SYNCHRONIZATION-WITH-FILE-JOURNALS.
The pathname of the file backing the journal.
common-lisp.
:pathname
This slot is read-only.
An IN-MEMORY-BUNDLE is a BUNDLE that is built on IN-MEMORY-JOURNALs. IN-MEMORY-BUNDLEs have limited utility as a persistence mechanism and are provided mainly for reasons of symmetry and for testing. See @SYNCHRONIZATION-WITH-IN-MEMORY-JOURNALS for an example of how to achieve persistence without bundles.
IN-MEMORY-JOURNALs are backed by a non-persistent
Lisp array of events. Much quicker than FILE-JOURNALs, they are
ideal for smallish journals persisted manually (see
@SYNCHRONIZATION-WITH-IN-MEMORY-JOURNALS for an example).
They are also useful for writing tests based on what events were
generated. They differ from FILE-JOURNALs in that events written to
IN-MEMORY-JOURNALs are not serialized (and deserialized on replay)
with the following consequences for the objects recorded by
JOURNALED (i.e. its NAME, ARGS arguments, and also the return VALUES
of the block, or the value returned by CONDITION):
- These objects need not be @READABLE.
- Their identity (‘EQ‘ness) is not lost.
- They must __must not be mutated__ in any way.
A sequence of events in the journal. Not to be mutated by client code.
:events
This slot is read-only.
:sync-fn
The length of JOURNAL-EVENTS at the time of the most recent invocation of SYNC-FN.
0
This slot is read-only.
JOURNAL is an abstract base class for a sequence of
events. In case of FILE-JOURNALs, the events are stored in a file,
while for IN-MEMORY-JOURNALs, they are in a Lisp array. When a
journal is opened, it is possible to perform I/O on it (see
@STREAMLETS-REFERENCE), which is normally taken care of by
WITH-JOURNALING. For this reason, the user’s involvement with
journals normally only consists of creating and using them in
WITH-JOURNALING.
Return the state of JOURNAL, which is of type [JOURNAL-STATE][TYPE].
journal:journal-state
:state
The SYNC argument specified at instantiation. See @SYNCHRONIZATION-STRATEGIES.
:sync
This slot is read-only.
If non-NIL, this is a function to add @DECORATION
to LOG-EVENTs before they are written to a journal. The only
allowed transformation is to _append_ a plist to the event, which
is a plist itself. The keys can be anything.
:log-decorator
(bordeaux-threads:make-recursive-lock "a journal-lock")
0
0
If JOURNAL-DIVERGENT-P, then this is a list of two
elements: the READ-POSITIONs in the RECORD-JOURNAL and
REPLAY-JOURNAL of the first events that were different (ignoring
LOG-EVENTs). It is NIL, otherwise.
This slot is read-only.
Events written to a PPRINT-JOURNAL have a
customizable output format. PPRINT-JOURNALs are intended for
producing prettier output for @LOGGING and @TRACING, but they do not
support reads, so they cannot be used as a REPLAY-JOURNAL or in
LIST-EVENTS, for example. On the other hand, events written to
PPRINT-JOURNALs need not be @READABLE.
The stream where events are dumped. May be set any time to another STREAM.
common-lisp.
stream
*standard-output*
:stream
Whether to use PPRINT-JOURNAL-PRETTIFIER or write events in as the property lists they are. A @BOOLEAN-VALUED-SYMBOL.
t
:pretty
A function like PRETTIFY-EVENT that writes an
event to a stream. Only used when PPRINT-JOURNAL-PRETTY, this is
the output format customization knob. Also see @DECORATIONs.
(quote journal:prettify-event)
:prettifier
A STREAMLET is a handle to perform I/O on a
JOURNAL. The high-level stuff (WITH-JOURNALING, JOURNALED, etc) is
built on top of streamlets.
The JOURNAL that was passed to OPEN-STREAMLET.
This is the journal [STREAMLET][dislocated] operates on.
:journal
This slot is read-only.
(or journal::direction null)
:direction
0
t
:sync
An event is either an IN-EVENT, an OUT-EVENT or a LEAF-EVENT.
One of :VALUES, :CONDITION, :ERROR and :NLX. Indicates whether a
journaled @BLOCK
- returned normally (:VALUES, see @VALUES-OUTCOME),
- unwound on an expected condition (:CONDITION, see @CONDITION-OUTCOME),
- unwound on an unexpected condition (:ERROR, see @ERROR-OUTCOME),
- unwound by performing a [non-local exit][clhs] of some other kind
such as a throw (:NLX, see @NLX-OUTCOME).
The first two are @EXPECTED-OUTCOMEs, while the latter two are @UNEXPECTED-OUTCOMEs.
An event’s version is either NIL, a positive FIXNUM, or :INFINITY, which correspond to LOG-EVENTs, VERSIONED-EVENTs, and EXTERNAL-EVENTs, respectively, and have an increasingly strict behaviour with regards to @REPLAY. All EVENTs have versions. The versions of the in- and out-events belonging to the same @FRAME are the same.
Events with [EVENT-VERSION][type] :INFINITY are called external events.
They are like VERSIONED-EVENTs whose version was bumped all the way
to infinity, which rules out easy, non-matching upgrades. Also, they
are never inserted to the record without a matching replay
event (see @THE-REPLAY-STRATEGY).
In return for these restrictions, external events can be replayed
without running the corresponding @BLOCK (see
@REPLAYING-THE-OUTCOME). This allows their out-event variety, called
@DATA-EVENTs, to be non-deterministic. Data events play a crucial
role in @PERSISTENCE.
If an EXTERNAL-EVENT has an @UNEXPECTED-OUTCOME, RECORD-UNEXPECTED-OUTCOME is signalled.
IN-EVENTs are triggered upon entering the dynamic extent of a JOURNALED @BLOCK. IN-EVENTs have EVENT-NAME, [EVENT-VERSION][function], and EVENT-ARGS. See @IN-EVENTS for a more introductory treatment.
JOURNAL’s state with respect to replay is updated during
WITH-JOURNALING. The possible states are:
- __:NEW__: This journal was just created but never recorded to.
- __:REPLAYING__: Replaying events has started, some events may have
been replayed successfully, but there are more non-log events to
replay.
- __:MISMATCHED__: There was a REPLAY-FAILURE. In this state,
VERSIONED-EVENTs generated are downgraded to LOG-EVENTs,
EXTERNAL-EVENTs and @INVOKED trigger DATA-EVENT-LOSSAGE.
- __:RECORDING__: All events from the replay journal were
successfully replayed, and now new events are being recorded
without being matched to the replay journal.
- __:LOGGING__: There was a RECORD-UNEXPECTED-OUTCOME. In this
state, VERSIONED-EVENTs generated are downgraded to LOG-EVENTs,
EXTERNAL-EVENTs and @INVOKED trigger DATA-EVENT-LOSSAGE.
- __:FAILED__: The journal is to be discarded. It encountered a
JOURNALING-FAILURE or a REPLAY-FAILURE without completing the
replay and reaching :RECORDING.
- __:COMPLETED__: All events were successfully replayed and
WITH-JOURNALING finished or a JOURNALING-FAILURE occurred while
:RECORDING or :LOGGING.
The state transitions are:
:NEW -> :REPLAYING (on entering WITH-JOURNALING)
:REPLAYING -> :MISMATCHED (on REPLAY-FAILURE)
:REPLAYING -> :FAILED (on REPLAY-INCOMPLETE)
:REPLAYING -> :FAILED (on JOURNALING-FAILURE)
:REPLAYING -> :RECORDING (on successfully replaying all events)
:MISMATCHED -> :FAILED (on leaving WITH-JOURNALING)
:RECORDING -> :LOGGING (on RECORD-UNEXPECTED-OUTCOME)
:RECORDING/:LOGGING -> :COMPLETED (on leaving WITH-JOURNALING)
:RECORDING/:LOGGING -> :COMPLETED (on JOURNALING-FAILURE)
:NEW is the starting state. It is a JOURNAL-ERROR to attempt to
write to journals in :COMPLETED. Note that once in :RECORDING, the
only possible terminal state is :COMPLETED.
Leaf events are triggered by LOGGED. Unlike IN-EVENTs and OUT-EVENTs, which represent a @FRAME, leaf events represent a point in execution thus cannot have children. They are also the poorest of their kind: they only have an EVENT-NAME. Their VERSION is always NIL, which makes them LOG-EVENTs.
Events with [EVENT-VERSION][type] NIL called log events. During @REPLAY, they are never matched to events from the replay journal, and log events in the replay do not affect events being recorded either. These properties allow log events to be recorded in arbitrary journals with JOURNALED’s LOG-RECORD argument. The convenience macro FRAMED is creating frames of log-events, while the LOGGED generates a log-event that’s a LEAF-EVENT.
OUT-EVENTs are triggered upon leaving the dynamic extent of the JOURNALED @BLOCK. OUT-EVENTs have EVENT-NAME, [EVENT-VERSION][function], [EVENT-EXIT][function] and EVENT-OUTCOME. See @OUT-EVENTS for a more introductory treatment.
Events with a positive integer [EVENT-VERSION][type] are called
versioned events. In @REPLAY, they undergo consistency checks unlike
LOG-EVENTs, but the rules for them are less strict than for
EXTERNAL-EVENTs. In particular, higher versions are always
considered compatible with lower versions, they become an _upgrade_
in terms of the @THE-REPLAY-STRATEGY, and versioned events can be
inserted into the record without a corresponding @REPLAY-EVENT with
JOURNALED’s INSERTABLE.
If a VERSIONED-EVENT has an @UNEXPECTED-OUTCOME, RECORD-UNEXPECTED-OUTCOME is signalled.
file-streamlet)) ¶automatically generated reader method
pprint-streamlet)) ¶automatically generated reader method
file-streamlet)) ¶automatically generated writer method
pprint-streamlet)) ¶automatically generated writer method
file-streamlet)) ¶automatically generated reader method
file-streamlet)) ¶automatically generated writer method
file-bundle) journal) ¶in-memory-bundle) journal) ¶in-memory-journal)) ¶A sequence of events in the journal. Not to be mutated by client code.
journal-error)) ¶streamlet-error)) ¶journal-error)) ¶streamlet-error)) ¶journaling-failure)) ¶journaling-failure)) ¶file-bundle)) ¶in-memory-bundle)) ¶record-unexpected-outcome)) ¶file-streamlet)) ¶automatically generated reader method
file-streamlet)) ¶automatically generated writer method
replay-failure)) ¶replay-failure)) ¶file-streamlet)) ¶automatically generated reader method
file-streamlet)) ¶automatically generated writer method
(setf %out-depth).
%out-depth.
(setf %stream).
%stream.
close-streamlet.
make-streamlet-finalizer.
peek-event.
read-event.
(setf read-file-position).
read-file-position.
read-position.
request-completed-on-abort.
set-read-position.
sync-streamlet.
write-event.
write-position.
(setf wrote-last-p).
wrote-last-p.
common-lisp.
(or stream null)
:stream
0
A streamlet for performing IO on IN-MEMORY-JOURNALs.
0
| Jump to: | %
(
-
A B C D E F G H I J L M N O P R S T U V W |
|---|
| Jump to: | %
(
-
A B C D E F G H I J L M N O P R S T U V W |
|---|
| Jump to: | %
*
@
C D E F I J L M N O P R S T W |
|---|
| Jump to: | %
*
@
C D E F I J L M N O P R S T W |
|---|
| Jump to: | B C D E F I J L M O P R S T U V |
|---|
| Jump to: | B C D E F I J L M O P R S T U V |
|---|