assigns a new-value to
These must be called after deliver is called.
must be one of the legal keywords to deliver (which are listed in Alphabetical list of deliver keywords, or can be displayed by calling deliver-keywords).
returns the value associated with this keyword. When deliver is called, the values associated with each keyword are initialized from the arguments to deliver or using their default values (which are listed by deliver-keywords
, or set to
. They can be modified later by user actions that were added to the "Delivery actions" action-list, and then by the system. Before starting the shaking operations, the values of the keywords are reset, and
cannot be called after the shaking.
can beused to set the value of a keyword. Since the user actions are done before the system ones, the system actions (which also use
to access the keywords value) will see any change that the user actions did.
Lists the legal keywords to deliver. If the keyword default is non-nil, it is printed on the same line. The default is a form that is evaluated if the keyword was not passed to deliver, in the order that
also prints a short documentation string for each keyword.
Used to define a cleanup function that is called after the shaking operation.
stores a pointer to
and a weak pointer to
. After the shaking, the shaker goes through all the object/function pairs, and for each object that is still alive, calls this function with the object as argument. This is used to perform operations that are dependent on the results of the shaking operation.
If the cleanup function has to be called unconditionally, the object should be
. The cleanup function should be a symbol or compiled function/closure, unless the evaluator is kept via
. The shaker performs another round of shaking after calling the cleanup functions, so unless something points to them, they are shaken away before the delivered image is saved. This also means that objects (including symbols) that survived the shaking until the cleanup function is called, but become garbage as a result of the cleanup function, are shaken away as well.
The cleanup function cannot use delivery-value. If the value of one of the keywords to deliver is needed in the cleanup function, it has to be stored somewhere (for example, as a value of a symbol, or closed over). It cannot be bound dynamically around the call to deliver, because the cleanup function is executed outside the dynamic context in which deliver is called.
Suppose the symbol P:X is referred to by objects that are not shaken, but its values are used in function P:Y, which may or may not be shaken. We want to get rid of the value of P:X if the symbol P:Y has been shaken, and set the value of P:X to T if
is passed to deliver and is non-nil, or
(defun setup-eliminate-x ()
(let ((new-value (if (delivery-value :keep-debug-mode) t nil)))
(unless (find-symbol "Y" "P")
(let ((sym (find-symbol "X" "P")))
(set sym new-value))))))))
(define-action "Delivery actions" "Eliminate X"
This sets up the lambda to be called after the shaking operation. It will set the value of P:X if the symbol P:Y has been shaken. Notes about the cleanup function:
[The code above assumes the the package "P" is not deleted or smashed ]
The cleanup functions are called after the operation of delivery-shaker-weak-pointer is complete, and are useful for cleaning up the operations of delivery-shaker-weak-pointer.
setter remover dead-value pointed
Used to make a pointer from one object to another weak object during the shaking operation. The operations of
The pointing object. Because of the way
is defined, you are free to use your own notion of pointing, for example, it may be the key in a
The accessor that is called with the pointing object. It returns the pointed object. The accessor is used for two purposes:
1. getting the pointed object if it is not given.
2. computing the setter if it is not given.
are passed to
, the accessor is not used. The
can be one of:
A symbol. This specifies a function that is called with the pointing object as its argument.
A list starting with a symbol. In this case the
of the list is called with the
object as its first argument, and the
forming the rest of the arguments, that is:
(apply (car accessor ) pointing (cdr accessor ))
For example, if the accessor is
, the call is
(aref 1 2) => (aref pointing 1 2).
If the setter is not given, it is computed by the system using the
and the same expansion that
would use. If it is given, it has the same properties as the
, except that in the call the
object is inserted before all the arguments. That is, if the setter is
), the call is
pointed pointing name
. In addition, where the
accepts a symbol, the
also accepts a function object.
which means use the
. This is used to remove the
object. It is called exactly like the
, except that the first argument is
, rather than
This gives the value of the pointed object. If it is not given, the accessor is used to get the pointed object.
. This the value that is stored by the
in the pointing value before starting the shaking. Note that if the
object is shaken, the
object is left with the
Note that between the calls to the
(steps 2 and 3 above), the
object points to the wrong thing (the
). This may cause problems if the object is used by the system during the shaking (this does not happen unless you access objects which you should not access), or if you define more than one
on the same object, and one of these uses a slot that has been defined by the other. Thus you have to make sure that you do not cause this situation.
Example 1 :
Suppose the keys of
are conses of an object and a number, and it is desired to remove from
those entries where the
is not pointed to from anywhere else. This can be done by something like this :
;; This will eliminate all the entries where the car is nil
(defun clean-my-hash-table (table)
(maphash (lambda (x y)
(declare (ignore y))
(unless (car x) (remhash x table)))
;; this will cause the car of any entry where the car is not
;; pointed to from another object to change to nil
(defun shake-my-hash-table ()
(maphash #'(lambda (x y) (declare (ignore y))
(delivery-shaker-weak-pointer x 'car))
;;this will cause clean-my-hash-table to be called later
;; in the shaking, provided *my-hash-table* is still alive.
(delivery-shaker-cleanup *my-hash-table* 'clean-my-hash-table))
;; call this function at delivery time
(define-action "Delivery Actions" "shake my hash table"
, the code above removes some entries it should not. In this case the appropriate lines should be changed to:
(delivery-shaker-weak-pointer x 'car :dead-value 'my-dead-value))
(when (eq (car x) 'my-dead-value) (remhash x table))
[ This assumes there are no entries where the
Note that the cleanup function is not going to be called unless the hash table actually survives the shaking operation.
The value of
is a list of objects of type
, which has a slot called
, which points to a symbol. We want to get rid of any of these structures if the symbol is not pointed to by some other object.
Make the pointers from the structures to the names be weak, and have the cleanup function throw away any structure where the name becomes
(defun clean-*aaa* ()
(loop for a on *aaa*)
(delivery-shaker-weak-pointer a 'a-struct-name))
(symbol-value symbol ) )))))
(define-action "Delivery Actions" "Clean aaa" 'clean-*aaa*)
Make a pointer from the symbol to the structure, and make
point weakly to the names, and set
. The remover and accessor do nothing, and the setter is defined to restore
. This implementation does not use the cleanup function.
(defun clean-*aaa* ()
(let ((setter #'(lambda (name symbol)
(set symbol (nconc
(list(get name 'a-struct))) )
(remprop name 'a-struct))))
(dolist (x *aaa* ()
(let ((name (a-struct-name x)))
(setf (get name 'a-struct) x)
(delivery-shaker-weak-pointer '*aaa* nil
(setq *aaa* nil)))
(define-action "Delivery actions" "Clean aaa" 'clean-*aaa*)
LispWorks Delivery User Guide - 13 Dec 2011