(defvar *generation* (list '*generation*)
"Generation marker, used to remember when we last updated a particular dep.
- Essentially, if the dep's generation matches *GENERATION* then it doesn't
- need updating again.")
+ Essentially, if the dep's generation matches `*generation*' then it
+ doesn't need updating again.")
(defvar *evaluating-dep* nil
"The dep currently being evaluated. This is bound only during the call of
(defvar *state* :ready
"The current state. It may be any of:
- * :READY -- the usual state: everything is up-to-date and correct.
+ * `:ready' -- the usual state: everything is up-to-date and correct.
- * :FROZEN -- the state used to evaluate the body of WITH-DEPS-FROZEN.
- Deps may be assigned values, but their dependents are not immediately
- recomputed.
+ * `:frozen' -- the state used to evaluate the body of
+ `with-deps-frozen'. Deps may be assigned values, but their dependents
+ are not immediately recomputed.
- * :RECOMPUTING -- the state imposed while updating dependents.")
+ * `:recomputing' -- the state imposed while updating dependents.")
(defvar *delayed-operations* nil
- "A queue of operations delayed by WITH-DEPS-FROZEN. Only available in the
- :RECOMPUTING state.")
+ "A queue of operations delayed by `with-deps-frozen'. Only available in
+ the `:recomputing' state.")
(defvar *pending-deps* nil
"A queue of deps pending recomputation. This is bound to a queue during
detect whether recomputation is happening.
Deps on the queue are always in the current generation, and have the
- +QUEUED+ flag set.")
+ `+queued+' flag set.")
;;;--------------------------------------------------------------------------
;;; Data structures.
(progn (setf (dep-%value dep) value) t))))
(defun new-dep-value (dep)
- "Recompute and return the value of DEP, or .BAD. if the dep is bad.
+ "Recompute and return the value of DEP, or `.bad.' if the dep is bad.
This function is very minimal. The caller expected to deal with many
aspects of caring for and feeding DEP. In particular:
- * Non-local exits (except throwing DEP-BAD) are not handled here.
+ * Non-local exits (except throwing `dep-bad') are not handled here.
* We assume that DEP is already in the current generation, and has its
- +RECOMPUTING+ flag set.
+ `+recomputing+' flag set.
* The caller is responsible for setting the current flags afterwards."
(catch 'dep-bad
"Notify the dependents of DEP of a change to its value.
We assume that DEP is up-to-date in the current generation, and has
- correct flags (at least +VALUE+ and +CHANGED+, and maybe +DEPS+).
+ correct flags (at least `+value+' and `+changed+', and maybe `+deps+').
Dependents of DEP are enqueued for recomputation. The DEP's dependents
are forced into the current generation and enqueued, and the dependents
list is cleared ready to be repopulated. The DEP's listener functions are
"Recompute the value of DEP.
Returns true if DEP's value actually changed, or nil otherwise. On exit,
- the DEP's +VALUE+ and +DEPS+ flags are set, and +CHANGED+ is set if the
- value actually changed.
+ the DEP's `+value+' and `+deps+' flags are set, and `+changed+' is set if
+ the value actually changed.
We assume that DEP's dependencies are up-to-date already, and that DEP's
- +RECOMPUTING+ flag is set. In the former case, DEP's dependents and
- listeners are notified, using PROPAGATE-TO-DEPENDENTS."
+ `+recomputing+' flag is set. In the former case, DEP's dependents and
+ listeners are notified, using `propagate-to-dependents'."
(let ((winning nil)
(new-flags (logior (logand (dep-%flags dep) +queued+)
+value+ +deps+)))
or nil if not.
If DEP is already has a good value, then we just use that; the return
- value is determined by the +CHANGED+ flag. Otherwise, we set
- +RECOMPUTING+ (in order to trap circularities) and force the values of
+ value is determined by the `+changed+' flag. Otherwise, we set
+ `+recomputing+' (in order to trap circularities) and force the values of
DEP's dependencies in turn. If any of them returned true then we have to
explicitly recompute DEP (so we do); otherwise we can leave it as it is."
(let ((flags (dep-flags dep)))
(export 'dep-try)
(defmacro dep-try (expr &body body)
- "Evaluate EXPR. If it throws DEP-BAD then evaluate BODY instead."
+ "Evaluate EXPR. If it throws `dep-bad' then evaluate BODY instead."
(let ((block-name (gensym "TRY")))
`(block ,block-name
(catch 'dep-bad
(throw 'dep-bad nil))
(defun recompute-pending-deps ()
- "Process the *PENDING-DEPS* queue, recomputing the deps listed on it.
+ "Process the `*pending-deps*' queue, recomputing the deps listed on it.
- We bind *STATE* to :RECOMPUTING during the process."
+ We bind `*state*' to `:recomputing' during the process."
(let ((*state* :recomputing))
(unwind-protect
(loop (when (queue-emptyp *pending-deps*)
(setf (dep-%value d) .bad.))))))
(defun with-deps-frozen* (thunk &key delay)
- "Invoke THUNK in the :FROZEN state. See WITH-DEPS-FROZEN for full
+ "Invoke THUNK in the `:frozen' state. See `with-deps-frozen' for full
information."
(ecase *state*
(:frozen
(export 'with-deps-frozen)
(defmacro with-deps-frozen ((&key delay) &body body)
- "Evaluate BODY in the :FROZEN state.
-
- In the :FROZEN state, recomutation is deferred. If the current state is
- :READY, then we enter :FROZEN, evaluate the BODY, and then enter
- :RECOMPUTING to fix up the dependency graph. If the current state is
- :FROZEN, we do nothing particularly special. Finally, if the current
- state is :RECOMPUTING then the behaviour depends on the value of
- the :DELAY argument: if false, an error is signalled; if true, the
+ "Evaluate BODY in the `:frozen' state.
+
+ In the `:frozen' state, recomutation is deferred. If the current state is
+ `:ready', then we enter `:frozen', evaluate the BODY, and then enter
+ `:recomputing' to fix up the dependency graph. If the current state is
+ `:frozen', we do nothing particularly special. Finally, if the current
+ state is `:recomputing' then the behaviour depends on the value of
+ the `:delay' argument: if false, an error is signalled; if true, the
evaluation is postponed until the end of the recomputation.
This macro has four immediate uses.
It's invoked behind the scenes to do the right thing.
* If you're making a large number of updates without data dependencies
- then you can make them go faster by wrapping them in WITH-DEPS-FROZEN
- and only having a single recomputation phase.
+ then you can make them go faster by wrapping them in
+ `with-deps-frozen' and only having a single recomputation phase.
- * A simple (SETF (DEP-VALUE ...) ...) is unsafe during recomputation.
- You can use WITH-DEPS-FROZEN to indicate that it's safe to defer the
+ * A simple (setf (dep-value ...) ...) is unsafe during recomputation.
+ You can use `with-deps-frozen' to indicate that it's safe to defer the
assignment until later. Deferred operations take place in the order
in which they were requested.
(:value &optional OBJECT)
Return a leaf dep, whose value is OBJECT; if no OBJECT is given, the
- dep is initially bad. The keyword :LEAF is accepted as a synonym.
+ dep is initially bad. The keyword `:leaf' is accepted as a synonym.
(:function FUNCTION)
Return a non-leaf dep whose value is computed by FUNCTION.
- Additionally, if the first argument is something other than :VALUE or
- :FUNCTION (ideally not a keyword, for forward compatibility), then the
+ Additionally, if the first argument is something other than `:value' or
+ `:function' (ideally not a keyword, for forward compatibility), then the
first argument is inspected: if it's a function, then a function dep is
- retuerned (as if you'd specified :function); otherwise a leaf dep is
+ retuerned (as if you'd specified `:function'); otherwise a leaf dep is
returned.
- Finally, it's possible to specify both :VALUE and :FUNCTION
+ Finally, it's possible to specify both `:value' and `:function'
simultaneously; this will set the initial values as requested, but
recompute them as necessary. It is possible to establish dependency
cycles, but you need to suppress recomputation in order to do this
- correctly -- see the DELAY-RECOMPUTING-DEPS macro.
+ correctly -- see the `with-deps-frozen' macro.
If no arguments are given, a bad leaf dep is returned."
(flet ((arg () (if args (pop args)
- (error "Not enough arguments to MAKE-DEP."))))
+ (error "Not enough arguments to `make-dep'."))))
;; Sort out the arguments.
(let ((value .bad.)
#[FORM ...] -> (make-dep :funcion (lambda () FORM ...))
Return a derived dep whose value function computes the given FORMs
- (as an implicit PROGN)
+ (as an implicit `progn')
Returns the READTABLE."
(set-macro-character #\?
~mdw / lisp / commitdiff