Node:Structure Layout, Next:Structure Basics, Previous:Structure Concepts, Up:Structures
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:
The field holds binary data that is not GC protected.
The field holds a Scheme value and is GC protected.
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:
The field can be read and written.
The field can be read, but not written.
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:
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:
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
; 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:
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:
|make-struct-layout fields||Scheme Procedure|
|scm_make_struct_layout (fields)||C Function|
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.