Major Section: ARRAYS
Example Form: (flush-compress 'my-array) General Form: (flush-compress name)where
name is a symbol.Recall that (compress1 nm alist) associates an under-the-hood raw Lisp
one-dimensional array of name nm with the given association list,
alist, while (compress2 nm alist) is the analogous function for
two-dimensional arrays; see compress1 and see compress2. The only purpose
of flush-compress, which always returns nil, is to remove the
association of any under-the-hood array with the given name, thus eliminating
slow array accesses (see slow-array-warning). It is not necessary if the
return values of compress1 and compress2 are always used as the
``current'' copy of the named array, and thus flush-compress should
rarely, if ever, be needed in user applications.
Nevertheless, we provide the following contrived example to show how
flush-compress can be used to good effect. Comments have been added to
this log to provide explanation.
ACL2 !>(assign a (compress1 'demo
'((:header :dimensions (5)
:maximum-length 15
:default uninitialized
:name demo)
(0 . zero)
(1 . one))))
((:HEADER :DIMENSIONS (5)
:MAXIMUM-LENGTH
15 :DEFAULT UNINITIALIZED :NAME DEMO)
(0 . ZERO)
(1 . ONE))
ACL2 !>(aref1 'demo (@ a) 0)
ZERO
; As expected, the above evaluation did not cause a slow array warning. Now
; we associate a different under-the-hood array with the name 'demo.
ACL2 !>(compress1 'demo
'((:header :dimensions (5)
:maximum-length 15
:default uninitialized
:name demo)
(0 . zero)))
((:HEADER :DIMENSIONS (5)
:MAXIMUM-LENGTH
15 :DEFAULT UNINITIALIZED :NAME DEMO)
(0 . ZERO))
; The following array access produces a slow array warning because (@ a) is
; no longer associated under-the-hood with the array name 'demo.
ACL2 !>(aref1 'demo (@ a) 0)
**********************************************************
Slow Array Access! A call of AREF1 on an array named
DEMO is being executed slowly. See :DOC slow-array-warning
**********************************************************
ZERO
; Now we associate under-the-hood, with array name 'demo, an alist equal to
; (@ a).
ACL2 !>(compress1 'demo
'((:header :dimensions (5)
:maximum-length 15
:default uninitialized
:name demo)
(0 . zero)
(1 . one)))
((:HEADER :DIMENSIONS (5)
:MAXIMUM-LENGTH
15 :DEFAULT UNINITIALIZED :NAME DEMO)
(0 . ZERO)
(1 . ONE))
; The following array access is still slow, because the under-the-hood array
; is merely associated with a copy of (@ a), not with the actual object
; (@ a).
ACL2 !>(aref1 'demo (@ a) 0)
**********************************************************
Slow Array Access! A call of AREF1 on an array named
DEMO is being executed slowly. See :DOC slow-array-warning
**********************************************************
ZERO
; So we might try to fix the problem by recompressing. But this doesn't
; work. It would work, by the way, if we re-assign a:
; (assign a (compress1 'demo (@ a))). That is why we usually will not need
; flush-compress.
ACL2 !>(compress1 'demo (@ a))
((:HEADER :DIMENSIONS (5)
:MAXIMUM-LENGTH
15 :DEFAULT UNINITIALIZED :NAME DEMO)
(0 . ZERO)
(1 . ONE))
ACL2 !>(aref1 'demo (@ a) 0)
**********************************************************
Slow Array Access! A call of AREF1 on an array named
DEMO is being executed slowly. See :DOC slow-array-warning
**********************************************************
ZERO
; Finally, we eliminate the warning by calling flush-compress before we call
; compress1. The call of flush-compress removes any under-the-hood
; association of an array with the name 'demo. Then the subsequent call of
; compress1 associates the object (@ a) with that name. (Technical point:
; compress1 always associates the indicated name with the value that it
; returns. in this case, what compress1 returns is (@ a), because (@ a) is
; already, logically speaking, a compressed array1p (starts with a :header
; and the natural number keys are ordered).
ACL2 !>(flush-compress 'demo)
NIL
ACL2 !>(compress1 'demo (@ a))
((:HEADER :DIMENSIONS (5)
:MAXIMUM-LENGTH
15 :DEFAULT UNINITIALIZED :NAME DEMO)
(0 . ZERO)
(1 . ONE))
ACL2 !>(aref1 'demo (@ a) 0)
ZERO
ACL2 !>
