6.7 Finalization

6.7.2 Reference pages

Syntax:delete-finalization-registration object queue

Gets rid of a registration before adisksave.

The argument object is a Lisp object, and the argument queue is a finalization queue. You should use this function to remove object from finalization queues you may have created before callingdisksave with the:full-gc argument set tot. Otherwise, the system will enter an error break, offering you a continuation in which all finalizations you have made are deleted.

Note: Since the cost of finalization during each gc is on the order of the square of the number of registered objects, it is a good idea to register only what is absolutely needed, and to delete any useless registrations as soon as possible.

Recall that the effect of the:full-gc keyword argument todisksave, when t, is to make all objects permanent. This would mean that an object registered for finalization would never be finalized, because finalization occurs during garbage collection, and permanent objects are never garbage collected.

Syntax:make-finalization-queue&optional name

Makes a new finalization queue.

Creates an object of typefinalization-queue. The optional name argument is the name of the finalization queue structure, and is used in printing.

;;; We create a finalization queue.
> (setq my-final-queue (make-finalization-queue))
#<Structure FINALIZATION-QUEUE 9A0366>

;;; We create two fleeting objects and register them for 
;;; finalization.
> (setq fleeting1 '(a b c))
(A B C)

> (register-for-finalization fleeting1 my-final-queue)
T

> (setq fleeting2 '(d e f))
(D E F)

> (register-for-finalization fleeting2 my-final-queue)
T

;;; We discard all references to the two original objects, i.e.,
;;; the lists '(a b c)and '(d e f)
> (setq fleeting1 nil)
NIL

> (setq fleeting2 nil)
;;; queue MY-FINAL-QUEUE.

> (gc)
;;; GC: 4606 words [18424 bytes] of dynamic storage in use.
;;; 454144 words [1816576 bytes] of free storage available before
;;; a GC. 912894 words [3651576 bytes] of free storage available
;;; if GC is disabled.
18528
1815448
3649424

;;; We list the contents of the queue (this empties the queue).
> (list-finalization-queue my-final-queue)
((A B C) (D E F))

;;; Now the queue is empty.
> (list-finalization-queue my-final-queue)
NIL
> 

Syntax:finalization-queue-p object

Tests whether an object is a finalization queue.

Returnst if the argument object is a finalization queue.

See Also: make-finalization-queue

Syntax:finalization-queue-empty-p queue

Determines whether a finalization queue is empty.

Returnst if the argument queue is empty. This is particularly useful for "wait" functions in multiprocessing.

See Also: list-finalization-queue, pop-finalization-queue

Syntax:pop-finalization-queue queue

Pops an element off a finalization queue.

Returns one element from a finalization queue, ornil if the queue is empty. The element is removed from the queue. The argument queue must be a finalization queue.

> (setq my-final-queue (make-finalization-queue))
#<Structure FINALIZATION-QUEUE 980366>

;;; We are trying to create two objects that are each referenced
;;; only once. Thus we embed the SETQ's within the PROGN and
;;; create a dummy variable DUMMY in order to shield FLEETING1 and
;;; FLEETING2 from being pointed to by the Common Lisp variables *
;;; and **.
> (progn 
     (setq fleeting1 (list 'a 'b 'c)
           fleeting2 (list 'd 'e 'f)
           dummy nil))
NIL

> (register-for-finalization fleeting1 my-final-queue)
T

> (register-for-finalization fleeting2 my-final-queue)
T

> (setq fleeting1 nil fleeting2 nil)
NIL

;;; We invoke the garbage collector, which will place the lists
;;; previously pointed to by FLEETING1 and FLEETING2 on the 
;;; finalization queueu, MY-FINAL-QUEUE.
> (gc)
;;; GC: 1330 words [5320 bytes] of dynamic storage in use.
;;; 457420 words [1829680 bytes] of free storage available before
;;; a GC. 916170 words [3664680 bytes] of free storage available
;;; if GC is disabled.
5448
1828528
3662504

;;; We pop the two items off of the finalization queue one
;;; at a time.
> (pop-finalization-queue my-final-queue)
(A B C)

> (pop-finalization-queue my-final-queue)
(D E F)
> 

See Also: finalization-queue-empty-p, list-finalization-queue

Syntax:list-finalization-queue queue

Dequeues and returns all of the elements in a finalization queue.

Dequeues all elements from a finalization queue, returning them in a list. The argument queue is a finalization queue. After this function returns, queue will be empty.

;;; After placing some items in a finalization queue, we will
;;; call list-finalization-queue. As a side effect, the items
;;; will be dequeued.
> (setq my-final-queue (make-finalization-queue "One Last Queue"))
#<Structure FINALIZATION-QUEUE 9A5566>

> (setq var1 '(a b c))
(A B C)

> (setq var2 '(d e f))
(D E F)

> (setq var3 '(g h i))
(G H I)

> (register-for-finalization var1 my-final-queue)
T

> (register-for-finalization var2 my-final-queue)
T

> (register-for-finalization var3 my-final-queue)
T

> (setq var1 nil var2 nil var3 nil)
NIL

;;; We have to wait for a gc in order to see the items show up on 
;;; the queue.
> (gc)
;;; GC: 1282 words [5128 bytes] of dynamic storage in use.
;;; 457468 words [1829872 bytes] of free storage available
;;; before a GC. 916218 words [3664872 bytes] of free storage
;;; available if GC is disabled.

5232
1828744
3662720

> (list-finalization-queue my-final-queue)
((A B C) (D E F) (G H I))

> (finalization-queue-empty-p my-final-queue)
T
> 

See Also: finalization-queue-empty-p, pop-finalization-queue

Syntax:registered-for-finalization-queue-p object queue

Tests whether an object is registered on a particular finalization queue.

Returnst if the Lisp object object has been registered for resurrection to the finalization queue queue.

;;; After placing some items in a finalization queue, we will
;;; call list-finalization-queue. As a side effect, the items
;;; will be dequeued.
> (setq my-final-queue (make-finalization-queue 
        "One Last Queue"))
#<Structure FINALIZATION-QUEUE 9A5566>

> (setq var1 '(a b c))
(A B C)

> (setq var2 '(d e f))
(D E F)

> (register-for-finalization var1 my-final-queue)
T

> (registered-for-finalization-queue-p var1 my-final-queue)
T

> (registered-for-finalization-queue-p var2 my-final-queue)
NIL

See Also: register-for-finalization-queue

Syntax:register-for-finalization-queue object finalization-queue

Arranges for an object be placed on a finalization queue.

Arranges for object to be placed on finalization-queue the next time all pointers to the object are dropped. Returnst if the object was not registered before, and now is registered. Returnsnil if the object is already registered in this queue or if the object is immediate or in a space that is not collected. It makes sense to register only objects that may be discarded when they become dead.

See Also: registered-for-finalization-queue-p

Generated with Harlequin WebMaker