FLUSH-COMPRESS.html -- ACL2 Version 6.3

### FLUSH-COMPRESS

flush the under-the-hood array for the given name

    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 !>