GNU Info

(guile.info)Structure Layout

---

Next: Structure Basics Prev: Structure Concepts Up: Structures

---

Enter node , (file) or (file)node

Structure Layout
----------------

When a structure is created, a region of memory is allocated to hold its
state.  The "layout" of the structure's type determines how that memory
is divided into fields.

Each field has a specified type.  There are only three types allowed,
each corresponding to a one letter code.  The allowed types are:

   * 'u' - unprotected

     The field holds binary data that is not GC protected.

   * 'p' - protected

     The field holds a Scheme value and is GC protected.

   * 's' - self

     The field holds a Scheme value and is GC protected.  When a
     structure is created with this type of field, the field is
     initialized to refer to the structure's own handle.  This kind of
     field is mainly useful when mixing Scheme and C code in which the
     C code may need to compute a structure's handle given only the
     address of its malloced data.

Each field also has an associated access protection.   There are only
three kinds of protection, each corresponding to a one letter code.
The allowed protections are:

   * 'w' - writable

     The field can be read and written.

   * 'r' - readable

     The field can be read, but not written.

   * 'o' - opaque

     The field can be neither read nor written.   This kind of
     protection is for fields useful only to built-in routines.

A layout specification is described by stringing together pairs of
letters: one to specify a field type and one to specify a field
protection.    For example, a traditional cons pair type object could
be described as:

     ; cons pairs have two writable fields of Scheme data
     "pwpw"

A pair object in which the first field is held constant could be:

     "prpw"

Binary fields, (fields of type "u"), hold one _word_ each.  The size of
a word is a machine dependent value defined to be equal to the value of
the C expression: `sizeof (long)'.

The last field of a structure layout may specify a tail array.  A tail
array is indicated by capitalizing the field's protection code ('W',
'R' or 'O').   A tail-array field is replaced by a read-only binary
data field containing an array size.   The array size is determined at
the time the structure is created.  It is followed by a corresponding
number of fields of the type specified for the tail array.   For
example, a conventional Scheme vector can be described as:

     ; A vector is an arbitrary number of writable fields holding Scheme
     ; values:
     "pW"

In the above example, field 0 contains the size of the vector and
fields beginning at 1 contain the vector elements.

A kind of tagged vector (a constant tag followed by conventioal vector
elements) might be:

     "prpW"

Structure layouts are represented by specially interned symbols whose
name is a string of type and protection codes.  To create a new
structure layout, use this procedure:

 - primitive: make-struct-layout fields
     Return a new structure layout object.

     FIELDS must be a string made up of pairs of characters strung
     together.  The first character of each pair describes a field
     type, the second a field protection.  Allowed types are 'p' for
     GC-protected Scheme data, 'u' for unprotected binary data, and 's'
     for a field that points to the structure itself.    Allowed
     protections are 'w' for mutable fields, 'r' for read-only fields,
     and 'o' for opaque fields.  The last field protection
     specification may be capitalized to indicate that the field is a
     tail-array.