[MERGE-REQUEST] Wrap/unwrap CGs and "inlining"

[Ludovic Courtès]

Hello,

The following patches augment the API reference and fix tiny bugs.  The
last one is a followup to the issue #2 raised in [0].  Therefore, it
needs further reviewing.

  patch-10
      Fixed a bug in strings unwrapping on Guile; augmented the doc.
  patch-11
      Have WCPs honor the `null-ok' typespec; augmented the doc.
  patch-12
      Added an INLINED? arg to the wrap/unwrap CGs; augmented the doc.

Note that `patch-10' documents the `aggregated' typespec among other
things[1].

As for `patch-12', it basically adds an INLINED? argument to
`wrap-value-cg', `unwrap-value-cg', and `destroy-value-cg', while still
making it optional.  Currently, only the implementation of these methods
for <gw-guile-ctype-mchars> makes real use of it.  Here is how it is
documented (sorry, it's a bit long):

 -- method: wrap-value-cg (type <gw-type>) (value <gw-value>) err
          (inlined? <boolean>)
     Generates C code that wraps the value VALUE of type TYPE.  ERR is
     a string containing the name of the C variable holding a G-Wrap
     run-time error (*note Overview of the Code Generation Methods::).

     If INLINED? is false, then this means that the wrapping code is
     generated for use in a stand-alone wrapping function for TYPE.
     Generation of code for stand-alone wrapping functions is performed
     by `wrap-value-function-cg' (see below).

     If INLINED? is true, then this means that wrapping code is
     generated for use _within_ a C function wrapper.  C function
     wrapper code generation is performed by `function-wrapper-cg' for
     functions where run-time type information cannot be relied on
     (FIXME: xref).

     When wrapping code is generated within a function wrapper, then
     certain assumptions can be made that cannot be made in the case of
     stand-alone wrapping functions.  For instance, it can be assumed
     that storage for the wrapped value can be allocated on the stack
     rather than on the heap, in order to speed up operation.

     As an example, `unwrap-value-cg' method for type `mchars', for
     Guile wrapsets, can convert Scheme strings to C strings on the
     stack using `scm_to_locale_stringbuf' rather than
     `scm_to_locale_string' which allocates a new C string on the heap
     (*note Guile string wrapping/unwrapping: (guile)Conversion to/from
     C, for details).  The INLINE? argument is optional.  This means
     that you can overload WRAP-VALUE-CG without having to specify this
     argument:

          (define-method (wrap-value-cg (type <my-own-type>) (value <gw-value>)
                                        error-var)
            ;; Always generate the same code, whether it is generated in a
            ;; stand-alone wrapping function or not.
            )


Thanks,
Ludovic.

[0] http://lists.nongnu.org/archive/html/g-wrap-dev/2005-09/msg00007.html
[1] http://lists.nongnu.org/archive/html/g-wrap-dev/2005-09/msg00006.html