d2c API Reference

Edited by

Neel Krishnaswami

Use and copying of this software and preparation of derivative works based on this software are permitted, including commercial use, provided that the following conditions are observed:

  • This copyright notice must be retained in full on any copies and on appropriate parts of any derivative works.

  • Documentation (paper or online) accompanying any system that incorporates this software, or any part of it, must acknowledge the contribution of the Gwydion Project at Carnegie Mellon University.

This software is made available "as is". Neither the authors nor Carnegie Mellon University make any warranty about the software, its performance, or its conformity to any specification.

Bug reports, questions, comments, and suggestions should be sent by E-mail to the Internet address .

24 May 2000


Table of Contents

1. Introduction
2. Library compiler-base
Module c-representation
File compiler/base/c-rep.dylan
Module utils
File compiler/base/utils.dylan

Chapter 1. Introduction

This document is a companion to the Gwydion Dylan ™ Maintainer's Manual. The Maintainer's Manual contains an overview of the compiler's overall design, and information about its use. This document, the d2c API Reference Manual, is simply a catalog and description of all the methods, classes and variables in d2c. In addition to the signature and overview, each method definition contains information about which variables and parameters are mutated. There may be some descriptions of algorithms in this document, but it is intended that that information be put in the Maintainer's Manual.

Each chapter comprises one library, and is broken down into subsections by module and then file.

Comments, corrections and additions are welcomed. This is intended to be a collaborative effort — your contributions are sorely needed. In particular, I'd like to ask that when you add or modify any definitions to d2c, that you add the documentation to this guide. The more people that work on this, the faster that it will get done.

Chapter 2. Library compiler-base

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.


Module utils

Unsurprisingly, this module is a grab-bag of various useful functions and methods the used by modules in the rest of the compiler. Some of this stuff is actually quite useful in contexts beyond writing a compiler, and should probably be moved into some of the common libraries rather than living in compiler base.

File compiler/base/utils.dylan

pretty-format[Method]

Pretty-print error messages.

Parameters
streamAn instance of <stream>.
stringAn instance of <byte-string>.
argsAn instance of <object>.

Return Values
None

Description

Used for error message printing. Turns each space in the control string into a conditional newline, and turns literal newlines into a mandatory newline and 2 space indent.


condition-format[Method]

A method that uses pretty-format.

Parameters
streamAn instance of <stream>.
control-stringAn instance of <byte-string>.
argsAn instance of <object>.

Return Values
None

Description

This method prints error messages using pretty-format. It works by shadowing the condition-format method defined on (<stream>, <string>).


write-class-name[Method]

Print an object's classname to a stream.

Parameters
thingAn instance of <object>.
streamAn instance of <object>.

Return Values
None

Description

This print's thing's object-class's name to the stream. If the class is anonymous, the default representation of classes is printed to the stream. (This should never happen until d2c learns how to make anonymous classes.)


write-address[Method]

Prints the address of an object

Parameters
thingAn instance of <object>.
streamAn instance of <object>.

Return Values
None

Description

Prints the hexadecimal address of object to the stream stream.


pprint-fields[Method]

Used to print an object and its fields

Parameters
thingAn instance of <object>.
streamAn instance of <object>.
fieldsAn instance of <object>. Plist of fieldnames and values.

Return Values
None

Description

This method is a tool used to print the constituents of an object. The #rest argument is a list of symbols alternating with values — the symbols are used as the field names for the values.


$thousand-cardinals[Variable]

Vector of English names for numbers.

Type
<vector>

Description

This vector contains the names that are prefixed by numbers less than a hundred — "thousand", "million", etc. It is used in the method integer-to-english.


$ten-cardinals[Variable]

Vector of the English tens units.

Type
<vector>

Description

This vector contains the names of multiples of ten — "twenty", "thirty", etc. It is used in the method integer-to-english.


$unit-cardinals[Variable]

Vector of English words for 0 to 20.

Type
<vector>

Description

This vector contains strings naming the integers from 0 to 20. It is used in the method integer-to-english .


$thousand-ordinals[Variable]

Like $thousand-cardinals, except to name positions.

Type
<vector>

Description

This vector lists the ordinals for numbers bigger than 1000 — "millionth", "billionth" and so on. It is used in the method integer-to-english.


$ten-ordinals[Variable]

Like $ten-cardinals, except to name positions.

Type
<vector>

Description

This vector lists the ordinals for small integers from 0 to 20 — "zeroth", "first", etc. It is used in the method integer-to-english.


integer-to-english[Method]

Convert an integer to an English string.

Parameters
intAn instance of <integer>.
as:An instance of one-of(#"cardinal", #"ordinal").

Return Values
resAn instance of <byte-string>.

Description

This method converts an <integer> object into the English string for the number it represents. If the keyword as: is set to #"ordinal", then the English string is the name of the n-th position; otherwise it is just the name of the number.