# A5: Async
**Soft deadline:** Thursday, 11/12/15, 11:59 pm
**Hard deadline:** Saturday, 11/14/15, 11:59 pm
* * *
**Project component:** The design phase of your project is due at the same
time as this assignment. See [Milestone 1 of the project description][ms1] for
instructions.
[ms1]: ../proj/proj.html#ms1
* * *
*The rest of this writeup is an **individual** assignment. Sharing of code is not
permitted, especially not between you and your project team.*
## Overview
In lecture and lab, you have been learning to program with Async. This
assignment is a collection of small Async exercises. It is deliberately
smaller in scope than other assignments to give you time to work on the
design phase of your project.
## Objectives
* Write concurrent programs using futures.
* Write test cases for concurrent programs.
## Recommended reading
* [Lectures and recitations 16–18][web]
* [RWO chapter 18][rwo18]
[web]: http://www.cs.cornell.edu/Courses/cs3110/2015fa/
[rwo18]: https://realworldocaml.org/v1/en/html/concurrent-programming-with-async.html
## Requirements
* You must implement the functions in the `Exercises` module.
* You must implement an asynchronous queue in the `Queue` module.
* You must provide unit tests for your implementations in the file `tests.ml`.
* We must be able to compile and test your code as described below under
"Compiling and testing."
* Your code must be written with good style and be well documented.
## What we provide
- `.mli` and skeleton `.ml` files for the interfaces that you need to implement
- `.ocamlinit` and `.cs3110` files
- A template file `a5.txt` for submitting your written feedback.
## What to turn in
Submit the following files on [CMS][cms]:
* `exercises.ml`, `aQueue.ml`, and `tests.ml`, containing your solution code
and your test suite.
* `a5.txt`, containing your written feedback. It contains some questions
that you should answer individually on how teamwork is going with your project.
[cms]: https://cms.csuglab.cornell.edu/
## Grading issues
* **Allowed library functions:** Because the functions you will implement are
useful, many of them are already contained in the Async library. You should
use only the primitive async operations `bind` (or `>>=`), `return`, `upon`,
`after`, and the `Ivar` module to implement your solutions. You may also use
any functions from the OCaml standard library. In your test cases, however, you
may use any part of the Async library.
* **Compiling and testing:** Your submitted OCaml files must compile and run
using the `cs3110` tool. We will test your code by running `cs3110 compile`
on `exercises.ml`, `aQueue.ml` and `tests.ml`, and by running `cs3110 test
tests.ml`. You may not make any changes to the provided `.mli` files.
In fact, you won't even be submitting those files. We will compile your
against the original `.mli` files from the release code. Solutions
that do not compile and test according to these instructions will
receive minimal credit.
* **Code style:** Refer to the [CS 3110 style guide][style].
Ugly code that is functionally correct will nonetheless be penalized.
Take extra time to think and find elegant solutions.
* **Late submissions:** Carefully review the [course policies][syllabus] on
submission and late assignments. Verify before the deadline on CMS
that you have submitted the correct version.
* **Environment:** Your solution must function properly in the
[3110 virtual machine][vm], which is the official grading
environment for the course.
[style]: http://www.cs.cornell.edu/Courses/cs3110/2015fa/handouts/style.html
[syllabus]: http://www.cs.cornell.edu/Courses/cs3110/2015fa/syllabus.php
[vm]: http://www.cs.cornell.edu/Courses/cs3110/2015fa/vm.html
## Git
As always, you should use git (or another version control system) to manage
your development. We won't ask you to turn in a log for this assignment.
But we also won't have sympathy for anyone who loses their code because they
weren't keeping it in version control.
## Preparing the VM
As described in [recitation 18][rec18], you can install a patched version of `utop`
with better support for Async by running
```
$ opam pin add utop https://github.com/cs3110/utop.git
$ opam update utop
$ opam upgrade utop
```
[rec18]: http://www.cs.cornell.edu/Courses/cs3110/2015fa/l/18-monads/rec.html
## Part 1: Async programming
The `Exercises` module contains specifications for several functions that
operate on deferred values. Implement them. Follow the "Allowed
library functions" guidelines listed in the "Grading concerns" section above.
Write unit tests for your functions in the `tests.ml` file. You do
not need to provide unit tests for `job`.
Some of the specifications (such as `parallel_map` and `sequential_map`)
specify the order in which certain operations occur. Testing that events
occur in the right order can be tricky. Consider using mutable state or
Ivars in your tests to keep track of the order in which functions are called or
return, and then reading that state to determine whether things happen in the
right order.
## Part 2: Asynchronous Queue
Implement the asynchronous queue data abstraction defined in the `AQueue`
module. Document the abstraction function and any representation
invariants for your implementation. Follow the "Allowed library
functions" guidelines listed in the "Grading concerns" section above.
Implement unit tests for your queue in the `tests.ml` file.
## Karma
There's no karma on this small assignment—work on making your
projects awesome instead. :)