[PATCH] Document pitfalls with `define-class' and `#:init-value'

[Ludovic Courtès]

Hi,

The patch below documents the following "issue":

  ;; What you have in mind is that the `blurps' slot will always refer
  ;; to a new list.
  guile> (define-class <chbouib> ()
           (blurps :init-value (list 0)))
  guile> (define c (make <chbouib>))
  guile> (set-car! (slot-ref c 'blurps) 1)
  guile> (slot-ref c 'blurps)
  (1)

  ;; Now, see what happens when a new instance is created...
  guile> (define c2 (make <chbouib>))
  guile> (set-car! (slot-ref c2 'blurps) 7)
  guile> (slot-ref c 'blurps)
  (7)

Conclusion: the `init-value' is shared across instance of the class.  I
believe this is intentional given that we have `#:init-thunk' to work
around this problem.  The patch below is based around this assumption.

Thanks,
Ludovic.


2006-03-01  Ludovic Courtès  <address@hidden>

        * goops.texi (Slot Options): Explain the single-instance pitfall
        with `#:init-value' and how to work around it.


--- orig/doc/goops/goops.texi
+++ mod/doc/goops/goops.texi
@@ -833,12 +833,40 @@
 @deffnx {slot option} #:init-keyword init-keyword
 These options provide various ways to specify how to initialize the
 slot's value at instance creation time.  @var{init-value} is a fixed
-value.  @var{init-thunk} is a procedure of no arguments that is called
-when a new instance is created and should return the desired initial
-slot value.  @var{init-form} is an unevaluated expression that gets
+value, @emph{shared across all new instances of the class}.
address@hidden is a procedure of no arguments that is called when a
+new instance is created and should return the desired initial slot
+value.  @var{init-form} is an unevaluated expression that gets
 evaluated when a new instance is created and should return the desired
-initial slot value.  @var{init-keyword} is a keyword that can be used to
-pass an initial slot value to @code{make} when creating a new instance.
+initial slot value.  @var{init-keyword} is a keyword that can be used
+to pass an initial slot value to @code{make} when creating a new
+instance.
+
+Note that since the @code{init-value} is shared across new instances
+of a class, you may only use it when the initial value is an immutable
+value, like a constant.  If you want to initialize a slot with a
+fresh, mutable value, you should use @code{init-thunk} instead to make
+sure that each new instance's slot is initialized with a new object.
+Consider the following example:
+
address@hidden
+(define-class <chbouib> ()
+  (hashtab #:init-value (make-hash-table)))
address@hidden example
+
+Here, only one hash table is created, and all instances of
address@hidden<chbouib>} have their @code{hashtab} slot refer to it.  In order
+to have each instance of @code{<chbouib>} initialized with a new hash
+table, you have to proceed as follow:
+
address@hidden
+(define-class <chbouib> ()
+  (hashtab #:init-thunk make-hash-table))
address@hidden example
+
+Here, @code{make-hash-table} will be called each time a new instance
+of @code{<chbouib>} is created, thus initializing each @code{hashtab}
+slot with a new hash table.
 
 If more than one of these options is specified for the same slot, the
 order of precedence, highest first is