Cells
-----

Scheme48 also provides a simple mutable cell data type from the cells structure.  It uses them internally for local, lexical variables that are assigned, but cells are available still to the rest of the system for general use.

 -- procedure: make-cell contents returns cell
 -- procedure: cell? object returns boolean
 -- procedure: cell-ref cell returns value
 -- procedure: cell-set! cell value returns unspecified
     Make-cell creates a new cell with the given contents. Cell? is the disjoint type predicate for cells.  Cell-ref returns the current contents of CELL.  Cell-set! assigns the contents of CELL to VALUE.

Examples:

     (define cell (make-cell 42))
     (cell-ref cell)                         => 42
     (cell? cell)                            => #t
     (cell-set! cell 'frobozz)
     (cell-ref cell)                         => frobozz lisp

Queues
------

The queues structure exports names for procedures that operate on simple first-in, first-out queues.

 -- procedure: make-queue returns queue
 -- procedure: queue? object returns boolean
     Make-queue constructs an empty queue.  Queue? is the disjoint type predicate for queues.

 -- procedure: queue-empty? queue returns boolean
 -- procedure: empty-queue! queue returns unspecified
     Queue-empty? returns #t if QUEUE contains zero elements or #f if it contains some.  Empty-queue! removes all elements from QUEUE.

 -- procedure: enqueue! queue object returns unspecified
 -- procedure: dequeue! queue returns value
 -- procedure: maybe-dequeue! queue returns value or #f
 -- procedure: queue-head queue returns value
     Enqueue! adds OBJECT to QUEUE.  Dequeue! removes & returns the next object available from QUEUE; if QUEUE is empty, dequeue! signals an error. Maybe-dequeue! is like dequeue!, but it returns #f in the case of an absence of any element, rather than signalling an error.  Queue-head returns the next element available from QUEUE without removing it, or it signals an error if QUEUE is empty.

 -- procedure: queue-length queue returns integer
     Returns the number of objects in QUEUE.

 -- procedure: on-queue? queue object returns boolean
 -- procedure: delete-from-queue! queue object returns unspecified
     On-queue? returns true if QUEUE contains OBJECT or #f if not.  Delete-from-queue! removes the first occurrence of OBJECT from QUEUE that would be dequeued.

 -- procedure: queue->list queue returns list
 -- procedure: list->queue list returns queue
     These convert queues to and from lists of their elements. Queue->list returns a list in the order in which its elements were added to the queue.  List->queue returns a queue that will produce elements starting at the head of the list.

Examples:

     (define q (make-queue))
     (enqueue! q 'foo)
     (enqueue! q 'bar)
     (queue->list q)                         => (foo bar)
     (on-queue? q 'bar)                      => #t
     (dequeue! q)                            => 'foo
     (queue-empty? q)                        => #f
     (delete-from-queue! queue 'bar)
     (queue-empty? q)                        => #t
     (enqueue! q 'frobozz)
     (empty-queue! q)
     (queue-empty? q)                        => #t
     (dequeue! q)                            error--> empty queue lisp

     Queues are integrated with Scheme48's Optimistic concurrency,
     optimistic concurrency facilities, in that every procedure exported
     except for queue->list ensures fusible atomicity in operation
     --- that is, every operation except for queue->list ensures that
     the transaction it performs is atomic, and that it may be fused within
     larger atomic transactions, as transactions wrapped within
     call-ensuring-atomicity etc may be.

Hash tables
-----------

Scheme48 provides a simple hash table facility in the structure tables.

 -- procedure: make-table [hasher] returns table
 -- procedure: make-string-table returns string-table
 -- procedure: make-symbol-table returns symbol-table
 -- procedure: make-integer-table returns integer-table
     Hash table constructors.  Make-table creates a table that hashes keys either with HASHER, if it is passed to make-table, or default-hash-function, and it compares keys for equality with eq?, unless they are numbers, in which case it compares with eqv?.  Make-string-table makes a table whose hash function is string-hash and that compares the equality of keys with string=?.  Make-symbol-table constructs a table that hashes symbol keys by converting them to strings and hashing them with string-hash; it compares keys' equality by eq?.  Tables made by make-integer-table hash keys by taking their absolute value, and test for key equality with the = procedure.

 -- procedure: make-table-maker comparator hasher returns table-maker
     Customized table constructor constructor: this returns a nullary procedure that creates a new table that uses COMPARATOR to compare keys for equality and HASHER to hash keys.

 -- procedure: table? object returns boolean
     Hash table disjoint type predicate.

 -- procedure: table-ref table key returns value or #f
 -- procedure: table-set! table key value returns unspecified
     Table-ref returns the value associated with KEY in TABLE, or #f if there is no such association. If VALUE is #f, table-set! ensures that there is no longer an association with KEY in TABLE; if VALUE is any other value, table-set! creates a new association or assigns an existing one in TABLE whose key is KEY and whose associated value is VALUE.

 -- procedure: table-walk proc table returns unspecified
     Table-walk applies PROC to the key & value, in that order of arguments, of every association in TABLE.

 -- procedure: make-table-immutable! table returns table
     This makes the structure of TABLE immutable, though not its contents.  Table-set! may not be used with tables that have been made immutable.

 -- procedure: default-hash-function value returns integer-hash-code
 -- procedure: string-hash string returns integer-hash-code
     Two built-in hashing functions.  Default-hash-function can hash any Scheme value that could usefully be used in a case clause. String-hash is likely to be fast, as it is implemented as a VM primitive.  String-hash is the same as what the features structure exports under the same name.

Weak references
---------------

Scheme48 provides an interface to weakly held references in basic weak pointers and populations, or sets whose elements are weakly held. The facility is in the structure weak.

Weak pointers
.............

 -- procedure: make-weak-pointer contents returns weak-pointer
 -- procedure: weak-pointer? object returns boolean
 -- procedure: weak-pointer-ref weak-pointer returns value or #f
     Make-weak-pointer creates a weak pointer that points to CONTENTS.  Weak-pointer? is the weak pointer disjoint type predicate.  Weak-pointer-ref accesses the value contained within weak-pointer, or returns #f if there were no strong references to the contents and a garbage collection occurred.  Weak pointers resemble Cells, cells, except that they are immutable and hold their contents weakly, not strongly.

Populations (weak sets)
.......................

 -- procedure: make-population returns population
 -- procedure: add-to-population! object population returns unspecified
 -- procedure: population->list population returns list
 -- procedure: walk-population proc population returns unspecified
     Make-population constructs an empty population. Add-to-population! adds OBJECT to the population POPULATION.  Population->list returns a list of the elements of POPULATION.  Note, though, that this can be dangerous in that it can create strong references to the population's contents and potentially leak space because of this. Walk-population applies PROC to every element in POPULATION.