(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
automatically generated byinfo2html