(guile.info.gz) Structure Layout

Info Catalog

(guile.info.gz) Structure Concepts

(guile.info.gz) Structures

(guile.info.gz) Structure Basics

 
 22.5.2 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 malloc'd 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 conventional
 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:
 
  -- Scheme Procedure: make-struct-layout fields
  -- C Function: scm_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.
 

Info Catalog

(guile.info.gz) Structure Concepts

(guile.info.gz) Structures

(guile.info.gz) Structure Basics