Node:Structure Layout, Next:Structure Basics, Previous:Structure Concepts, Up:Structures

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:

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.