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:
"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:
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.