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

[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  <ludovic.courtes@laas.fr>

	* 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}.
+@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
 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:
+
+@example
+(define-class <chbouib> ()
+  (hashtab #:init-value (make-hash-table)))
+@end example
+
+Here, only one hash table is created, and all instances of
+@code{<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:
+
+@example
+(define-class <chbouib> ()
+  (hashtab #:init-thunk make-hash-table))
+@end 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



_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel

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

[Kevin Ryde]

ludovic.courtes@laas.fr (Ludovic Courtès) writes:
>
> shared across all new instances of the class

That bit sounds fair, I it in.  I think the rest labours the point a
little.  Hopefully seeing init-thunk and init-form described is
enough.


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel

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

[Ludovic Courtès]

Hi,

Kevin Ryde <user42@zip.com.au> writes:

> That bit sounds fair, I it in.  I think the rest labours the point a
> little.

Sorry, I'm not sure I understand what you mean.

> Hopefully seeing init-thunk and init-form described is
> enough.

I think the `@emph{shared across all new instances of the class}' is the
least I would expect from the documentation.  Then perhaps the example
that follows is just too much, too trivial.  Is it what you mean?

Thanks,
Ludovic.


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel

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

[Kevin Ryde]

ludovic.courtes@laas.fr (Ludovic Courtès) writes:
>
> Then perhaps the example
> that follows is just too much, too trivial.  Is it what you mean?

Yes.  (But fortunately I'm not the final arbiter, so if perhaps Mikael
thinks otherwise then it could yet get go in :-)


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel

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

[Ludovic Courtès]

Hello,

(See [0] for the beginning of this thread...)

Kevin Ryde <user42@zip.com.au> writes:

> ludovic.courtes@laas.fr (Ludovic Courtès) writes:
>>
>> Then perhaps the example
>> that follows is just too much, too trivial.  Is it what you mean?
>
> Yes.  (But fortunately I'm not the final arbiter, so if perhaps Mikael
> thinks otherwise then it could yet get go in :-)

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


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel

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

[Neil Jerram]

ludovic.courtes@laas.fr (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.

(I think I'm a good "final arbiter" in Mikael's absence, since I
originally wrote most of the GOOPS manual.)

Regards,
     Neil



_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel

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

[Ludovic Courtès]

[-- Attachment #1: Type: text/plain, Size: 857 bytes --]

Hi Neil,

Neil Jerram <neil@ossau.uklinux.net> writes:

> ludovic.courtes@laas.fr (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.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: GOOPS documentation patch --]
[-- Type: text/x-patch, Size: 2967 bytes --]

--- 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).
-@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}.
+@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
 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:
+
+@example
+(define-class <chbouib> ()
+  (hashtab #:init-value (make-hash-table)))
+@end example
+
+Here, only one hash table is created, and all instances of
+@code{<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:
+
+@example
+(define-class <chbouib> ()
+  (hashtab #:init-thunk make-hash-table))
+@end 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


[-- Attachment #3: Type: text/plain, Size: 143 bytes --]

_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel

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

[Neil Jerram]

ludovic.courtes@laas.fr (Ludovic Courtès) writes:

> Hi Neil,
>
> Neil Jerram <neil@ossau.uklinux.net> writes:
>
>> 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).

It was actually Kevin.

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

Thanks; I've applied most of it to HEAD, with slight edits so as not
to make the point too many times.

Regards,
     Neil



_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel

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

[Kevin Ryde]

Neil Jerram <neil@ossau.uklinux.net> writes:
>
> Thanks; I've applied most of it to HEAD,

If it's any good then it's worth having in the 1.8 branch, no need for
doc clarifications to wait the 3 years between major releases :-).

> with slight edits so as not to make the point too many times.

Looks a little verbose still.  Perhaps separating each #:init-foo
would be clearer.


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel

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

[Neil Jerram]

Kevin Ryde <user42@zip.com.au> writes:

> Neil Jerram <neil@ossau.uklinux.net> writes:
>>
>> Thanks; I've applied most of it to HEAD,
>
> If it's any good then it's worth having in the 1.8 branch, no need for
> doc clarifications to wait the 3 years between major releases :-).

Agreed; done.

>> with slight edits so as not to make the point too many times.
>
> Looks a little verbose still.

Yes, but I think it's useful all the same.

>  Perhaps separating each #:init-foo
> would be clearer.

Do you mean making separate @deffn's, or just paragraph breaks between
the sentences covering the different keywords?

Regards,
     Neil



_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel

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

[Kevin Ryde]

Neil Jerram <neil@ossau.uklinux.net> writes:
>
> Do you mean making separate @deffn's,

Yes.


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel

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

[Kevin Ryde]

I wrote:
>
> Yes.

(Which is not to say I'm sure it'd look better, just an idea.  Those
bits don't seem like they should be terribly difficult, a niceish or
typical example of each is probably plenty.)


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel

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

[Neil Jerram]

Kevin Ryde <user42@zip.com.au> writes:

> I wrote:
>>
>> Yes.
>
> (Which is not to say I'm sure it'd look better, just an idea.  Those
> bits don't seem like they should be terribly difficult, a niceish or
> typical example of each is probably plenty.)

I'm inclined not to do this right now.

We probably should do something like this in the future, when we come
to do a fine detail "could this doc appear in a printed book" kind of
review, because the node as it stands has no framing or context at
all.  Then I think we may find that when some of text is moved outside
the deffn's, it will make sense to split up the deffn's as you've
suggested.  But I don't think it makes sense to make this kind of
change now, and looking at just one node in isolation.

(FYI I'm currently trying to do this level of review for the parts of
the manual related to debugging, and making gradual progress on it.
This isn't because I have secret book-publishing plans :-), it's just
because I want to make sure that it's all correct, and I'd like to be
able to say that these sections of the manual are in their final form
(subject to future changes, of course).)

Regards,
     Neil



_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel