Project

The final assessment for this course consists of an individually completed project.

Final deliverables are due by the end of the time schedule for the class’s final exam as set by the registrar.

There are several projects to choose from, described below.

Compared to assignments, the project is more open-ended. You will need to select from a project description below and then select which language you’d like to target with your project. As starter code, you can use the source code of any of the course languages. How you implement your project is up to you. It may involve changes to all aspects of the language implementation: the parser, the compiler, and the run-time system (however, we do not require an interpreter implementation). No tests are provided, so we recommend you write your own and suggest focusing on tests before trying to implement these features.

In addition to the source code for your project, you must write a 2-page document in PDF format, which gives a summary of your work and describes how your project is implemented.

1 Multiple return values

Racket, Scheme, and even x86 support returning more than one value from a function call. Implement Racket’s let-values and values forms to add multiple return values.

You may choose to implement this feature for any language that is Iniquity or later for a maximum 95% of the possible points. For 100% you’ll need to implement the feature for Loot or later.

Here are the key features that need to be added:

• (values e1 ... en) will evaluate e1 through en and then “return” all of their values.

• (let-values ([(x1 ... xn) e]) e0) will evaluate e, which is expected to be an expression that produces n values, which are bound to x1 through xn in the body expression e0.

Here are some examples to help illustrate:

Examples

> (let-values ([(x y) (values 1 2)]) (+ x y))

3

> (let-values ([(x) (values 1)]) (add1 x))

2

> (let-values ([() (values)]) 7)

7

> (define (f x)     (values x (+ x 1) (+ x 2)))

> (let-values ([(x y z) (f 5)])     (cons x (cons y (cons z '()))))

'(5 6 7)

> (add1 (values 5))

6

> (let ((x (values 5)))     (add1 x))

6

Any time an expression produces a number of values that doesn’t match what the surrounding context expects, an error should be signaled.

Examples

> (add1 (values 1 2))

result arity mismatch;

expected number of values not received

expected: 1

received: 2

> (let-values ([(x y) 2]) x)

result arity mismatch;

expected number of values not received

expected: 2

received: 1

in: local-binding form

arguments...:

2

The top-level expression may produce any number of values and the run-time system should print each of them out, followed by a newline:

Examples

> (values 1 2 3)

1 2 3

Note there is some symmetry here between function arity checking where we make sure the number of arguments matches the number of parameters of the function being called and the “result arity” checking that is required to implement this feature. This suggests a similar approach to implementing this feature, namely designating a register to communicate the arity of the result, which should be checked by the surrounding context.

You will also need to design an alternative mechanism for communicating return values. Using a single register ('rax) works when every expression produces a single result, but now expressions may produce an arbitrary number of results and using registers will no longer suffice. (Although you may want to continue to use 'rax for the common case of a single result.) The solution for this problem with function parameters was to use the stack and a similar approach can work for results too.

1.1 Returning multiple values to the run-time system or asm-interp

In implementing values, there are two design decisions you have to make:

1. How are values going to be represented during the execution of a program?

2. How are values going to be communicated back to the run-time system and/or asm-interp when the program completes?

The answers to (1) and (2) don’t necessarily have to be the same.

Note that you can go a long way working on (1) without making any changes to the run-time system or unload-bits-asm.rkt (which is how the result of asm-interp is converted back to a Racket value). You can basically punt on (2) and work on (1) by writing tests that use multiple values within a computation, but ultimately return a single value, e.g. (let-values ([(x y) (values 1 2)] (cons x y))).

As for (2), here is a suggestion that you are free to adopt, although you can implement (2) however you’d like so long as when running an executable that returns multiple values it prints the results in a way consistent with how Racket prints and that if using asm-interp, your version of unload/free produces multiple values whenever the program does.

You can return a vector of results at the end of entry. This means after the instructions for the program, whatever values are produced are converted from the internal representation of values (i.e., your design for (1)) to a vector and the address (untagged) is put into rax to be returned to the run-time system and/or asm-interp.

Now both the run-time system and unload-bits-asm.rkt need to be updated to deal with this change in representation for the result.

In main.c, the part that gets the result and prints it:

  val_t result = entry(heap);
  print_result(result);
  if (val_typeof(result) != T_VOID)
    putchar('\n');

can be changed to getting the vector and printing each element:

  val_vect_t *result = entry(heap);
  for (int i = 0; i < result->len; ++i) {
    print_result(result->elems[i]);
    if (val_typeof(result->elems[i]) != T_VOID)
      putchar('\n');
  }

You’ll also need to update the signature of entry in runtime.h to:

  val_vect_t* entry();

You’ll also need to make a similar change to unload/free in unload-bits-asm.rkt, which plays the role of the run-time system when writing tests that use asm-interp.

Instead of:

; Answer* -> Answer

(define (unload/free a)

(match a

['err 'err]

[(cons h v) (begin0 (unload-value v)

(free h))]))

You’ll want:

; Answer* -> Answer

(define (unload/free a)

(match a

['err 'err]

[(cons h vs) (begin0 (unload-values vs)

(free h))]))

(define (unload-values vs)

(let ((vec (unload-value (bitwise-xor vs type-vect))))

(apply values (vector->list vec))))

Let’s say you make these changes to the run-time system and unload/free before you make any changes to the compiler and now you want to adapt the compiler to work with the new set up (before trying to do anything with values). You can add the following at the end of entry, just before the (Ret):

; Create and return unary vector holding the result

(Mov r8 1)

(Mov (Offset rbx 0) r8)  ; write size of vector, 1

(Mov (Offset rbx 8) rax) ; write rax as single element of vector

(Mov rax rbx)            ; return the pointer to the vector

In order to return more values, you’d construct a larger vector.

2 Exceptions and exception handling

Exceptions and exception handling mechanisms are widely used in modern programming languages. Implement Racket’s raise and with-handlers forms to add exception handling.

You may choose to implement this feature for any language that is Iniquity or later for a maximum 95% of the possible points. For 100% you’ll need to implement the feature for Loot or later.

Here are the key features that need to be added:

• (raise e) will evaluate e and then “raise” the value, side-stepping the usual flow of control and instead jump to the most recently installed exception handler.

• (with-handlers ([p1 f1] ...) e) will install a new exception handler during the evaluation of e. If e raises an exception that is not caught, the predicates should be applied to the raised value until finding the first pi that returns true, at which point the corresponding function fi is called with the raised value and the result of that application is the result of the entire with-handlers expression. If e does not raise an error, its value is the value of the with-handler expression.

Here are some examples to help illustrate:

Examples

> (with-handlers ([string? (λ (s) (cons "got" s))])     (raise "a string!"))

'("got" . "a string!")

> (with-handlers ([string? (λ (s) (cons "got" s))]                   [number? (λ (n) (+ n n))])     (raise 10))

20

> (with-handlers ([string? (λ (s) (cons "got" s))]                   [number? (λ (n) (+ n n))])     (+ (raise 10) 30))

20

> (let ((f (λ (x) (raise 10))))     (with-handlers ([string? (λ (s) (cons "got" s))]                     [number? (λ (n) (+ n n))])       (+ (f 10) 30)))

20

> (with-handlers ([string? (λ (s) (cons "got" s))]                   [number? (λ (n) (+ n n))])     'nothing-bad-happens)

'nothing-bad-happens

> (with-handlers ([symbol? (λ (s) (cons 'reraised s))])     (with-handlers ([string? (λ (s) (cons "got" s))]                     [number? (λ (n) (+ n n))])       (raise 'not-handled-by-inner-handler)))

'(reraised . not-handled-by-inner-handler)

Notice that when a value is raised, the enclosing context is discard. In the third example, the surrounding (+ [] 30) part is ignored and instead the raised value 10 is given the exception handler predicates, selecting the appropriate handler.

Thinking about the implementation, what this means is that a portion of the stack needs to be discarded, namely the area between the current top of the stack and the stack that was in place when the with-handlers expression was evaluated.

This suggestions that a with-handlers expression should stash away the current value of 'rsp. When a raise happens, it grabs the stashed away value and installs it as the current value of 'rsp, effectively rolling back the stack to its state at the point the exception handler was installed. It should then jump to code that will carry out the applying of the predicates and right-hand-side functions.

Since with-handlers can be nested, you will need to maintain an arbitrarily large collection of exception handlers, each of which has a pointer into the stack and a label for the code to handle the exception. This collection should operate like a stack: each with-handlers expression adds a new handler to the handler stack. If the body expression returns normally, the top-most handler should be removed. When a raise happens, the top-most handler is popped and used.

3 Garbage collection

Racket, OCaml, Java, JavaScript, Ruby, and many, many other languages use garbage collection as the means of deallocating memory. Implement a garbage collector.

You may choose to implement this feature for any language that is Loot or later.

Here are the key features that need to be added:

• all language constructs that allocate memory should check that the current state of the heap can accommodate an allocation before performing it, and if not, doing a garbage collection and trying again. If there is still not possible to accommodate the allocation, an error should be signaled.

• (collect-garbage) will run a garbage collection and return void.

• (current-memory-use) will return the number of bytes current allocated in the heap. This operation should not run a garbage collection and should not trace reachable objects in the heap. Instead it should simply return the total size, in bytes, that are currently allocated in the heap.

• (dump-memory-stats) prints information about the current stack and heap and returns void. See the iniquity-gc language for an example.

4 Design your own

You may also design your own project, however, you will need to submit a one-page write-up that documents what you plan to do and how you will evaluate whether it is successful. You must submit this document and have it approved by the instructor by November 22.

5 Submitting

Submissions should be made on Gradescope.

Your submission should be a zip file containing the following contents:

where <lang> corresponds to the language you have chosen to implement for your project, e.g. iniquity, loot, etc.

The info.rkt should contain the following information:

#lang info

(define project '<project>)

(define language '<lang>)

where <project> indicates which project you are doing. It should either be values, exceptions, garbage-collection, or custom. The <lang> should be iniquity, loot, etc. and should be the same as the directory that contains the implementation.