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

[Ludovic Courtès]

Hi Neil,

Neil Jerram <address@hidden> writes:

> address@hidden (Ludovic Courtès) writes:
>
>> I'm not sure whether Mikael Djurfeldt is actually following this list so
>> perhaps somebody else would like to give their opinion about these
>> documentation bits?
>>
>> Thanks,
>> Ludovic.
>>
>> [0] http://lists.gnu.org/archive/html/guile-devel/2006-03/msg00005.html
>
> I'm trying to clear out old email...  Would you mind reposting the
> remaining patch if you still have it; unfortunately the texinfo is
> mangled in the HTML copy.

In the meantime, Marius (IIRC) applied a more concise version of this
patch, without the example (sorry, I couldn't find the post in question,
but see changelog entry dated 2006-03-08).

Anyway, I re-issued a patch that should apply to the current CVS HEAD.

Thanks,
Ludovic.

--- orig/doc/goops/goops.texi
+++ mod/doc/goops/goops.texi
@@ -26,7 +26,7 @@
 @ifinfo
 This file documents GOOPS, an object oriented extension for Guile.
 
-Copyright (C) 1999, 2000, 2001, 2003, 2006 Free Software Foundation
+Copyright (C) 1999, 2000, 2001, 2003 Free Software Foundation
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -61,7 +61,7 @@
 @c  start the copyright page.
 @page
 @vskip 0pt plus 1filll
-Copyright @copyright{} 1999, 2006 Free Software Foundation
+Copyright @copyright{} 1999 Free Software Foundation
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -833,13 +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 (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
+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