Chapter 2. Library compiler-base

Table of Contents

Module c-representation
File compiler/base/c-rep.dylan
Module utils
File compiler/base/utils.dylan

Module c-representation

This module contains classes that represent the various C representations of Dylan ™ objects, along with various methods to manipulate them.

File compiler/base/c-rep.dylan

$byte-bits[Constant]

The number of bits in a byte.

Type
<integer>

Description

The number of bits in a byte. This is used for documentation in various byte-twiddling operations.


*pointer-alignment*[Variable]

Word boundary for pointers

Type
<object> — really false-or(<integer>)

Description

This variable is initially <false>, and is set by the method seed-representations.


*pointer-size*[Variable]

The size of a pointer.

Type
<object> — really false-or(<integer>)

Description

This variable is initially false, and set by seed-representations.


*short-alignment*[Variable]

Boundaries based on size of C short ints.

Type
<object> — really false-or(<integer>)

Description

This variable is initially false, and set by seed-representations.


*short-size*[Variable]

The size in bytes of a C short int.

Type
<object> — really false-or(<integer>)

Description

This variable is initially false, and set by seed-representations.


*int-alignment*[Variable]

Natural boundaries for C ints.

Type
<object> — really false-or(<integer>)

Description

This variable is initially false, and set by seed-representations.


*int-size*[Variable]

The size in bytes of a C int.

Type
<object> — really false-or(<integer>)

Description

This variable is initially false, and set by seed-representations.


*long-alignment*[Variable]

Natural boundaries for C longs.

Type
<object> — really false-or(<integer>)

Description

This variable is initially false, and set by seed-representations.


*long-size*[Variable]

The size in bytes of a C long integer

Type
<object> — really false-or(<integer>)

Description

This variable is initially false, and set by seed-representations.


*single-alignment*[Variable]

Boundary for C single-precision floats.

Type
<object> — really false-or(<integer>)

Description

This variable is initially false, and set by seed-representations.


*single-size*[Variable]

The size in bytes of a C float.

Type
<object> — really false-or(<integer>)

Description

This variable is initially false, and set by seed-representations.


*double-alignment*[Variable]

Boundary for C double-precision floats.

Type
<object> — really false-or(<integer>)

Description

This variable is initially false, and set by seed-representations.


*double-size*[Variable]

Size in bytes of C double-precision floats.

Type
<object> — really false-or(<integer>)

Description

This variable is initially false, and set by seed-representations.


*long-double-alignment*[Variable]

Boundary for C long double floats.

Type
<object> — really false-or(<integer>)

Description

This variable is initially false, and set by seed-representations.


*long-double-size*[Variable]

Size in bytes of C long double floats.

Type
<object> — really false-or(<integer>)

Description

This variable is initially false, and set by seed-representations.


*data-word-size*[Variable]

Bytes of largest one-word data element

Type
<object> — really false-or(<integer>)

Description

that fits in one word — the max of *long-size* and *pointer-size*. This variable is initially false, and is set by seed-representations.


<c-representation>[abstract Class]

The abstract supertype of C representations.

Superclasses
<representation> <identity-preserving-mixin>

Initialization Keywords
name:An instance of false-or(<symbol>).
more-general:An instance of false-or(<representation>).
to-more-general:An instance of type-union(<byte-string>, one-of(#t, #f)).
from-more-general:An instance of type-union(<byte-string>, one-of(#t, #f)).
alignment:An instance of <integer>. This keyword is required.
size:An instance of <integer>. This keyword is required.
c-type:An instance of <string>. This keyword is required.

Description

This class is the abstract superclass of all C representations. There should be more description here, but I'm not sure what.


representation-has-bottom-value?[Generic]

Returns true if the representation can support bottom.

Parameters
resAn instance of <representation>.

Return Values
resultAn instance of <boolean>.

Description

This method returns true if the representation class can support a bottom value. (Eg, the immediate form for integers can't, but the full heap representation can.) I'm not sure if bottom is meant in the denotational sense or just as an imprecise shorthand for "this value is not defined."


representation-has-bottom-value?[Method]

The default method in the generic

Parameters
resAn instance of <representation>.

Return Values
resultAn instance of <boolean>.

Description

The default method returns #t.


print-object[Method]

Writes a string to a stream.

Parameters
repAn instance of <c-representation>.
streamAn instance of <stream>.

Return Values
None

Description

Prints the fields of rep to stream.


<general-representation>[Class]

Superclasses
<c-representation>

Initialization Keywords
to-more-general:An instance of type-union(<byte-string>, one-of(#t, #f)).
from-more-general:An instance of type-union(<byte-string>, one-of(#t, #f)).

Description

A subclass of <c-representation> that represents arbitrary objects of unknown type..


<heap-representation>[Class]

Superclasses
<c-representation>

Initialization Keywords
None

Description

A subclass of <c-representation> representing heap-allocated objects. I'm not sure how this differs from <general-representation> objects.

I think it might be useful in a case when an object needs to be heap allocated, but the type is known and doesn't necessarily need the full object representation — eg, to represent <pair>s with two words of RAM. I won't know for certain, though, until I learn more about d2c.


<immediate-representation>[Class]

Representation of "unboxed" values, I think.

Superclasses
<c-representation>

Initialization Keywords
None

Description

I believe this class represents unboxed values that may be larger than one machine word.


<c-data-word-representation>[Class]

Objects that can fit in one C word.

Superclasses
<immediate-representation> <data-word-representation<

Initialization Keywords
class:An instance of <cclass>. This argument is required.
data-word-member:An instance of <byte-string>. This argument is required.

Description

This class represents objects whose layout can fit into a single word of memory.


*general-rep*[Variable]

A module variable possibly defining the C representation for general variables.

Type
false-or(<c-representation>)

Description

This variable is set by seed-representations and is dependent on the value of *current-target* — more when I learn more. It's referenced in the cback a lot, but never mutated AFAICT.


*heap-rep*[Variable]

Same as *general-rep*, only for heap objects.

Type
false-or(<c-representation>)

Description

This variable is set by seed-representations and is dependent on the value of *current-target*.


*boolean-rep*[Variable]

Presumably, the representation of boolean values.

Type
false-or(<c-representation>)

Description

This variable is set by seed-representations and is dependent on the value of *current-target*.


*long-rep*[Variable]

The representation of integers fitting a C long.

Type
false-or(<c-representation>)

Description

This variable is set by seed-representations and is dependent on the value of *current-target*.


*int-rep*[Variable]

The representation of integers that fit in a C int.

Type
false-or(<c-representation>)

Description

This variable is set by seed-representations and is dependent on the value of *current-target*.


*uint-rep*[Variable]

The representation of integers that fit in a C unsigned int.

Type
false-or(<c-representation>)

Description

This variable is set by seed-representations and is dependent on the value of *current-target*.


*short-rep*[Variable]

The representation of integers that fit in a C short.

Type
false-or(<c-representation>)

Description

This variable is set by seed-representations and is dependent on the value of *current-target*.


*ushort-rep* [Variable]

The representation of integers that fit in a C unsigned short.

Type
false-or(<c-representation>)

Description

This variable is set by seed-representations and is dependent on the value of *current-target*.


*byte-rep*[Variable]

The representation of Dylan ™ objects that fit in a C char.

Type
false-or(<c-representation>)

Description

This type is meant for Dylan ™ objects that can be stuffed into one byte. Usually it will be used for limited(<integer>) types.

This variable is set by seed-representations and is dependent on the value of *current-target*.


*ubyte-rep*[Variable]

The representation of Dylan ™ objects that fit in a C unsigned char.

Description

This type is meant for Dylan ™ objects that can be stuffed into a C short, especially limited(<integer>) objects with min: and max: in the appropriate range.

This variable is set by seed-representations and is dependent on the value of *current-target*.


*float-rep*[Variable]

The C representation for <single-float> numbers.

Type
false-or(<c-representation>)

Description

This variable is set by seed-representations and is dependent on the value of *current-target*.


*double-rep*[Variable]

The C representation for <double-float>.

Type
false-or(<c-representation>)

Description

This variable is set by seed-representations and is dependent on the value of *current-target*.


*long-double-rep*[Variable]

The C representation for <extended-float>.

Type
false-or

Description

This variable is set by seed-representations and is dependent on the value of *current-target*.


seed-representaions[Method]

This method sets all the nice globals described above.

Parameters
None

Return Values
None

Description

This method will look up *current-target* and try to set all the alignment- and representation-related global variables in this module. It is used to set the following variables:

*pointer-alignment*
*pointer-size*
*short-alignment*
*short-size*
*int-alignment*
*int-size*
*long-alignment*
*long-size*
*single-alignment*
*single-size*
*double-alignment*
*double-size*
*long-double-alignment*
*long-double-size*
*data-word-size*
*general-rep*
*heap-rep*
*boolean-rep*
*long-rep*
*int-rep*
*uint-rep*
*short-rep*
*ushort-rep*
*byte-rep*
*ubyte-rep*
*ptr-rep*
*float-rep*
*double-rep*
*long-double-rep*


*assigning-representations-for*[Variable]

Unknown.

Type
<list>

Description

As far as I can tell, this is a dead/obsolete binding. There do not seem to be *any* references to this variable anywhere in the c-representation module, and it is not exported from the module. It's just dead code, which should be removed.


assign-representations[Method]

Compute the representations for a compile-time class.

Parameters
classAn instance of <cclass>.

Return Values
None

Description

This method computes the representations of class by mutating the slots direct-speed-representation and direct-space-representation of the class parameter.


use-data-word-representation[Method]

Compute a <c-data-word-representation> for a <cclass>.

Parameters
classAn instance of <cclass>.
data-word-typeAn instance of <ctype>.

Return Values
None

Description

Computes a representation for class consistent with data-word-type. This method mutates the slots direct-speed-representation and direct-speed-representation of class.


use-general-representation[Method]

Compute a <general-representation> for a <cclass>.

Parameters
classAn instance of <cclass>.

Return Values
None

Description

This method sets the slots direct-speed-representation and direct-speed-representation of class to *general-rep*.


pick-representation[Method]

Pick a representation for a compile-time class.

Parameters
classAn instance of <cclass>.
optimize-forAn instance of one-of(#"speed", #"space").

Return Values
repAn instance of <c-representation>.

Description

Based on the value of optimize-for, pick-representation will set either of the general-speed-representation or general-space-representation slots of class. It uses general-representation to select a representation.


general-representation[Method]

Returns a representation for a compile-time class.

Parameters
classAn instance of <cclass>.
optimize-forAn instance of one-of(#"speed", #"space").

Return Values
repAn instance of <c-representation>.

Description

This method returns a general representation for a compile-time class. It does not mutate any of its arguments.


pick-representation[Method]

Parameters
typeAn instance of <direct-instance-type>.
optimize-forAn instance of one-of(#"speed", #"space").

Return Values
repAn instance of <c-representation>.

Description

This specialized method returns the direct representation of its type argument. It may mutate the slots direct-speed-representation and direct-space-representation of the object. type.base-class.


direct-representation[Method]

Return the representation of the compile-time class.

Parameters
classAn instance of <cclass>.
optimize-forAn instance of one-of(#"speed", #"space").

Return Values
repAn instance of <c-representation>.

Description

This method returns either the direct-speed-representation or direct-space-representation slots of class; if they are unassigned it will set those slots and then return the appropriate value.


pick-representation[Method]

Return the representation of the compile-time class.

Parameters
typeAn instance of <limited-ctype>.
optimize-forAn instance of one-of(#"speed", #"space").

Return Values
repAn instance of <c-representation>.

Description

This method reinvokes pick-representation on type.base-class, and returns that slot's direct-speed-representation or direct-space-representation; if they are unassigned it may set those slots and then return the appropriate value.


*byte-char-rep*[Variable]

The representation of byte characters.

Type
<object> — really false-or(<c-data-word-representation>)

Description

The representation type of <byte-character>s.


pick-representation[Method]

Returns the representation of <byte-character-ctype>

Parameters
typeAn instance of <byte-character-ctype>.
optimize-forAn instance of one-of(#"speed", #"space").

Return Values
repAn instance of <c-representation>.

Description

This method returns *byte-char-rep*, first setting it if it is #f.


pick-representation[Method]

Returns the representation of compile-time integer types.

Parameters
typeAn instance of <limited-integer-ctype>.
optimize-forAn instance of one-of(#"speed", #"space").

Return Values
repAn instance of <c-representation>.

Description

Returns the appropriate representation for limited integer types. Does not mutate any slots.


pick-representation[Method]

Returns a representation of union types.

Parameters
typeAn instance of <union-ctype>.
optimize-forAn instance of one-of(#"speed", #"space").

Return Values
repAn instance of <c-representation>.

Description

This function merges all the representations in the members slot of type, to return the least general representation that can hold all possible legal values.

This method may modify the direct-{foo}-representation slots of the root types of the type-union tree.


merge-representations[Method]

Returns the minimal type that can contain any value in either of its arguments.

Parameters
rep1An instance of <c-representation>.
rep2An instance of <c-representation>.

Return Values
resAn instance of <c-representation>.

Description

This method returns a new representation that is more general than either of its arguments. It modifies neither of its arguments.


pick-representation[Method]

Returns a representation for a type not known at compile time.

Parameters
typeAn instance of <unknown-ctype>.
optimize-forAn instance of one-of(#"speed", #"space").

Return Values
repAn instance of <c-representation>.

Description

This method mutates none of its arguments.