The trivial-garbage Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The trivial-garbage Reference Manual

This is the trivial-garbage Reference Manual, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 12:41:33 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

Build Status

trivial-garbage provides a portable API to finalizers, weak hash-tables and weak pointers on all major implementations of the Common Lisp programming language.

Documentation is available at the project's website.

It is placed in the public domain with absolutely no warranty.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 trivial-garbage

Author

Luis Oliveira <loliveira@common-lisp.net>

License

Public Domain

Description

Portable finalizers, weak hash-tables and weak pointers.

Source

trivial-garbage.asd (file)

Component

trivial-garbage.lisp (file)


Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 trivial-garbage.asd

Location

trivial-garbage.asd

Systems

trivial-garbage (system)


Previous: , Up: Lisp files   [Contents][Index]

3.1.2 trivial-garbage/trivial-garbage.lisp

Parent

trivial-garbage (system)

Location

trivial-garbage.lisp

Packages

trivial-garbage

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 trivial-garbage

@a[http://common-lisp.net/project/trivial-garbage]{trivial-garbage}
provides a portable API to finalizers, weak hash-tables and weak
pointers on all major implementations of the Common Lisp
programming language. For a good introduction to these
data-structures, have a look at @a[http://www.haible.de/bruno/papers/cs/weak/WeakDatastructures-writeup.html]{Weak
References: Data Types and Implementation} by Bruno Haible.

Source code is available at
@a[https://github.com/trivial-garbage/trivial-garbage]{github},
which you are welcome to use for submitting patches and/or @a[https://github.com/trivial-garbage/trivial-garbage/issues]{bug
reports}. Discussion takes place on @a[http://lists.common-lisp.net/cgi-bin/mailman/listinfo/trivial-garbage-devel]{trivial-garbage-devel at common-lisp.net}.

@a[http://common-lisp.net/project/trivial-garbage/releases/]{Tarball
releases} are available, but the easiest way to install this
library is via @a[http://www.quicklisp.org/]{Quicklisp}:
@code{(ql:quickload :trivial-garbage)}.

@begin[Weak Pointers]{section}
A @em{weak pointer} holds an object in a way that does not prevent
it from being reclaimed by the garbage collector. An object
referenced only by weak pointers is considered unreachable (or
"weakly reachable") and so may be collected at any time. When
that happens, the weak pointer’s value becomes @code{nil}.

@aboutfun{make-weak-pointer}
@aboutfun{weak-pointer-value}
@aboutfun{weak-pointer-p}
@end{section}

@begin[Weak Hash-Tables]{section}
A @em{weak hash-table} is one that weakly references its keys
and/or values. When both key and value are unreachable (or weakly
reachable) that pair is reclaimed by the garbage collector.

@aboutfun{make-weak-hash-table}
@aboutfun{hash-table-weakness}
@end{section}

@begin[Finalizers]{section}
A @em{finalizer} is a hook that is executed after a given object
has been reclaimed by the garbage collector.

@aboutfun{finalize}
@aboutfun{cancel-finalization}
@end{section}

Source

trivial-garbage.lisp (file)

Nickname

tg

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Functions

Function: cancel-finalization OBJECT

Cancels all of @code{object}’s finalizers, if any.

Package

trivial-garbage

Source

trivial-garbage.lisp (file)

Function: finalize OBJECT FUNCTION

Pushes a new @code{function} to the @code{object}’s list of finalizers. @code{function} should take no arguments. Returns @code{object}.

@b{Note:} @code{function} should not attempt to look at @code{object} by closing over it because that will prevent it from being garbage collected.

Package

trivial-garbage

Source

trivial-garbage.lisp (file)

Function: gc &key FULL VERBOSE

Initiates a garbage collection. @code{full} forces the collection of all generations, when applicable. When @code{verbose} is @em{true}, diagnostic information about the collection is printed if possible.

Package

trivial-garbage

Source

trivial-garbage.lisp (file)

Function: hash-table-weakness HT

Returns one of @code{nil}, @code{:key}, @code{:value}, @code{:key-or-value} or @code{:key-and-value}.

Package

trivial-garbage

Source

trivial-garbage.lisp (file)

Function: make-weak-hash-table &rest ARGS &key WEAKNESS WEAKNESS-MATTERS &allow-other-keys

Returns a new weak hash table. In addition to the standard arguments accepted by @code{cl:make-hash-table}, this function adds extra keywords: @code{:weakness} being the kind of weak table it should create, and @code{:weakness-matters} being whether an error should be signalled when that weakness isn’t available (the default is to signal an error). @code{weakness} can be one of @code{:key}, @code{:value}, @code{:key-or-value}, @code{:key-and-value}.

If @code{weakness} is @code{:key} or @code{:value}, an entry is kept as long as its key or value is reachable, respectively. If @code{weakness} is @code{:key-or-value} or @code{:key-and-value}, an entry is kept if either or both of its key and value are reachable, respectively.

@code{tg::make-hash-table} is available as an alias for this function should you wish to import it into your package and shadow @code{cl:make-hash-table}.

Package

trivial-garbage

Source

trivial-garbage.lisp (file)

Function: make-weak-pointer OBJECT

Creates a new weak pointer which points to @code{object}. For portability reasons, @code{object} must not be @code{nil}.

Package

trivial-garbage

Source

trivial-garbage.lisp (file)

Function: weak-pointer-p OBJECT

Returns @em{true} if @code{object} is a weak pointer and @code{nil} otherwise.

Package

trivial-garbage

Source

trivial-garbage.lisp (file)

Function: weak-pointer-value WEAK-POINTER

If @code{weak-pointer} is valid, returns its value. Otherwise, returns @code{nil}.

Package

trivial-garbage

Source

trivial-garbage.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *weakness-warnings*

List of weaknesses that have already been warned about this session. Used by ‘weakness-missing’.

Package

trivial-garbage

Source

trivial-garbage.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: make-hash-table &rest ARGS
Package

trivial-garbage

Source

trivial-garbage.lisp (file)

Function: weakness-keyword-arg WEAKNESS
Package

trivial-garbage

Source

trivial-garbage.lisp (file)

Function: weakness-keyword-opt WEAKNESS ERRORP
Package

trivial-garbage

Source

trivial-garbage.lisp (file)

Function: weakness-missing WEAKNESS ERRORP

Signal an error or warning, depending on ERRORP, about lack of Lisp support for WEAKNESS.

Package

trivial-garbage

Source

trivial-garbage.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   T  
Index Entry  Section

F
File, Lisp, trivial-garbage.asd: The trivial-garbage<dot>asd file
File, Lisp, trivial-garbage/trivial-garbage.lisp: The trivial-garbage/trivial-garbage<dot>lisp file

L
Lisp File, trivial-garbage.asd: The trivial-garbage<dot>asd file
Lisp File, trivial-garbage/trivial-garbage.lisp: The trivial-garbage/trivial-garbage<dot>lisp file

T
trivial-garbage.asd: The trivial-garbage<dot>asd file
trivial-garbage/trivial-garbage.lisp: The trivial-garbage/trivial-garbage<dot>lisp file

Jump to:   F   L   T  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   C   F   G   H   M   W  
Index Entry  Section

C
cancel-finalization: Exported functions

F
finalize: Exported functions
Function, cancel-finalization: Exported functions
Function, finalize: Exported functions
Function, gc: Exported functions
Function, hash-table-weakness: Exported functions
Function, make-hash-table: Internal functions
Function, make-weak-hash-table: Exported functions
Function, make-weak-pointer: Exported functions
Function, weak-pointer-p: Exported functions
Function, weak-pointer-value: Exported functions
Function, weakness-keyword-arg: Internal functions
Function, weakness-keyword-opt: Internal functions
Function, weakness-missing: Internal functions

G
gc: Exported functions

H
hash-table-weakness: Exported functions

M
make-hash-table: Internal functions
make-weak-hash-table: Exported functions
make-weak-pointer: Exported functions

W
weak-pointer-p: Exported functions
weak-pointer-value: Exported functions
weakness-keyword-arg: Internal functions
weakness-keyword-opt: Internal functions
weakness-missing: Internal functions

Jump to:   C   F   G   H   M   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*weakness-warnings*: Internal special variables

S
Special Variable, *weakness-warnings*: Internal special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   P   S   T  
Index Entry  Section

P
Package, trivial-garbage: The trivial-garbage package

S
System, trivial-garbage: The trivial-garbage system

T
trivial-garbage: The trivial-garbage system
trivial-garbage: The trivial-garbage package

Jump to:   P   S   T