# 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. :)