Re: array handles and non-local exits

[Ludovic Courtès]

"Neil Jerram" <address@hidden> writes:

> 2008/9/18 Ludovic Courtès <address@hidden>:

>> I would suggest that we drop that mention of dynwinds from the manual.

Just to clarify: I'm suggesting fixing the manual so that it conforms to
the implementation, not the opposite.

> In my view, this part is still useful:
>
> "You must take care to always unreserve an array after reserving it,
> also in the presence of non-local exits. To simplify this, reserving
> and unreserving work like a dynwind context (see Dynamic Wind): a call
> to scm_array_get_handle can be thought of as beginning a dynwind
> context and scm_array_handle_release as ending it. When a non-local
> exit happens between these two calls, the array is implicitely
> unreserved.
>
> That is, you need to properly pair reserving and unreserving in your
> code, but you don't need to worry about non-local exits."
>
> But this part is misleading and can be removed:
>
> "These calls and other pairs of calls that establish dynwind contexts
> need to be properly nested. If you begin a context prior to reserving
> an array, you need to unreserve the array before ending the context.
> Likewise, when reserving two or more arrays in a certain order, you
> need to unreserve them in the opposite order."
>
> Is that what you had in mind?

Not quite.  If get/release are left as is (i.e., they do not establish a
dynwind context), I would write something along the lines of:

     You must take care to always unreserve an array after reserving it,
  also in the presence of non-local exits.  If a non-local exit can
  happen between these two calls, you should install a dynwind context
  that releases the array when it is left (see Dynamic Wind).

     In addition, array reserving and unreserving must be properly
  paired.  For instance, when reserving two or more arrays in a certain
  order, you need to unreserve them in the opposite order.

I would simply remove the following paragraph:

     These calls and other pairs of calls that establish dynwind contexts
  need to be properly nested.  If you begin a context prior to reserving
  an array, you need to unreserve the array before ending the context.
  Likewise, when reserving two or more arrays in a certain order, you
  need to unreserve them in the opposite order.

What do you think?

Thanks,
Ludo'.