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 read-only 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 fields that should point 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.

Go to the first, previous, next, last section, table of contents.