Changeset 12094


Ignore:
Timestamp:
May 19, 2009, 11:38:20 PM (10 years ago)
Author:
gz
Message:

Public interface to populations (r12092 plus doc changes)

Location:
trunk/source
Files:
3 edited

Legend:

Unmodified
Added
Removed
  • trunk/source/doc/src/gc.xml

    r8981 r12094  
    225225    </sect1>
    226226
    227     <sect1 id="Weak-Hash-Tables">
    228       <title>Weak Hash Tables</title>
     227    <sect1 id="Weak-References">
     228      <title>Weak References</title>
    229229      <para>In general, a "weak reference" is a reference to an object
    230       which will not prevent the object from being garbage-collected.
     230      which does not prevent the object from being garbage-collected.
    231231      For example, suppose that you want to keep a list of all the
    232232      objects of a certain type.  If you don't take special steps, the
     
    235235      list.  Therefore, they will never be garbage-collected, and
    236236      their memory will never be reclaimed, even if they are
    237       referenced nowhere else in the program.  You may want this
    238       behavior.  If you don't, you need weak references.</para>
    239       <para>&CCL; supports weak references with "weak hash tables".
    240       Hash tables may be weak with respect to either their keys or
    241       their values.  To make a hash table with weak keys, invoke
     237      referenced nowhere else in the program.  If you don't want this
     238      behavior, you need weak references.</para>
     239
     240      <para>&CCL; supports weak references with two kinds of objects:
     241      weak hash tables and populations.</para>
     242
     243      <para>Weak hash tables are created with the standard Common Lisp
     244      function <literal>make-hash-table</literal>, which is extended
     245      to accept the keyword argument <literal>:weak</literal>.  Hash
     246      tables may be weak with respect to either their keys or their
     247      values.  To make a hash table with weak keys, invoke
    242248      <literal>make-hash-table</literal> with the option :weak t, or,
    243249      equivalently, :weak :key.  To make one with weak values, use
    244250      :weak :value.  When the key is weak, the equality test must be
    245251      #'eq (because it wouldn't make sense otherwise).</para>
     252
    246253      <para>When garbage-collection occurs, key-value pairs are
    247       removed from the hash table if there are no other references to
     254      removed from the hash table if there are no non-weak references to
    248255      the weak element of the pair (key or value).</para>
     256
    249257      <para>In general, weak-key hash tables are useful when you want
    250258      to use the hash to store some extra information about the
     
    252260      useful when you want to use the hash as an index for looking up
    253261      objects.</para>
    254       <para>If you are experimenting with weak hash tables
     262
     263      <para>A population encapsulates an object, causing certain
     264      reference from the object to be considered weak.  &CCL; supports
     265      two kinds of populations: lists, in which case the encapsulated
     266      object is a list of elements, which are spliced out of the list
     267      when there are no non-weak references to the element; and alists,
     268      in which case the encapsulated object is a list of conses which
     269      are spliced out of the list if there are no non-weak references
     270      to the car of the cons.</para>
     271
     272    <para>If you are experimenting with weak references
    255273      interactively, remember that an object is not dead if it was
    256274      returned by one of the last three interactively-evaluated
     
    259277      workaround is to evaluate some meaningless expression before
    260278      invoking <literal>gc</literal>, to get the object out of the
    261       repl variables.</para>
     279      REPL variables.</para>
     280
     281
     282      <para>
     283        <indexterm zone="f_make-population"/>
     284        <command><varname id="f_make-population">MAKE-POPULATION</varname>
     285           &key; <parameter>type</parameter> <parameter>initial-contents</parameter>
     286        [Function]</command>
     287      </para>
     288
     289    <variablelist>
     290      <varlistentry>
     291        <term><varname>type</varname></term>
     292        <listitem>
     293          <para>The type of population, one of <literal>:LIST</literal> (the default) or <literal>:ALIST</literal></para>
     294        </listitem>
     295      </varlistentry>
     296      <varlistentry>
     297        <term><varname>initial-contents</varname></term>
     298        <listitem>
     299          <para> A sequence of elements (or conses, for <literal>:alist</literal>) to be used to initialize the
     300            population. The sequence itself (and the conses in case of an alist) is not stored, a new list
     301            or alist is created to be stored in the population.</para>
     302        </listitem>
     303      </varlistentry>
     304    </variablelist>
     305
     306    <para>Creates a new population of the specified type.</para>
     307
     308
     309    <para>
     310      <indexterm zone="f_population-type"/>
     311      <command><varname id="f_population-type">POPULATION-TYPE</varname>  <parameter>population</parameter>
     312        [Function]</command>
     313    </para>
     314
     315    <para>returns the type of <literal>population</literal>, one of <literal>:LIST</literal> or <literal>:ALIST</literal></para>
     316
     317    <para>
     318      <indexterm zone="f_population-contents"/>
     319      <command><varname id="f_population-contents">POPULATION-CONTENTS</varname>  <parameter>population</parameter>
     320        [Function]</command>
     321    </para>
     322
     323    <para>returns the list encapsulated in <literal>population</literal>.  Note
     324    that as long as there is a direct (non-weak) reference to this list, it will
     325    not be modified by the garbage collector.  Therefore it is safe to traverse
     326    the list, and even modify it, no different from any other list. If you want the
     327    elements to become garbage-collectable again, you must stop refering to the
     328    list directly.</para>
     329
     330    <para>
     331      <indexterm zone="f_setf_population-contents"/>
     332      <command>(SETF (<varname id="f_setf_population-contents">POPULATION-CONTENTS</varname> <parameter>population</parameter>) <parameter>contents</parameter>)
     333              [Function]</command>
     334    </para>
     335
     336    <para>Sets the list encapsulated in <literal>population</literal> to <literal>contents</literal>.  <literal>Contents</literal> is not copied, it is used directly.</para>
     337
    262338    </sect1>
     339
    263340
    264341    <sect1 id="Garbage-Collection-Dictionary">
  • trunk/source/lib/ccl-export-syms.lisp

    r12090 r12094  
    427427     *static-cons-chunk*
    428428     static-cons
     429
     430     population
     431     make-population
     432     population-type
     433     population-contents
    429434
    430435     compiler-let
  • trunk/source/lib/misc.lisp

    r11868 r12094  
    658658
    659659
     660
     661(defun make-population (&key (type :list) initial-contents)
     662  (let* ((ntype (ecase type
     663                  (:list $population_weak-list)
     664                  (:alist $population_weak-alist)))
     665         (list (if (eq type :alist)
     666                 (map 'list (lambda (c) (cons (car c) (%cdr c))) initial-contents)
     667                 (if (listp initial-contents)
     668                   (copy-list initial-contents)
     669                   (coerce initial-contents 'list)))))
     670    (%cons-population list ntype)))
     671
     672(defun population-type (population)
     673  (let ((ntype (population.type (require-type population 'population))))
     674    (cond ((eq ntype $population_weak-alist) :alist)
     675          ((eq ntype $population_weak-list) :list)
     676          (t nil))))
     677
     678(declaim (inline population-contents (setf population-contents)))
     679
     680(defun population-contents (population)
     681  (population.data (require-type population 'population)))
     682
     683(defun (setf population-contents) (list population)
     684  (setf (population.data (require-type population 'population)) (require-type list 'list)))
     685
     686
     687
     688
    660689(defun get-string-from-user (prompt)
    661690  (with-terminal-input
Note: See TracChangeset for help on using the changeset viewer.