Project 1

From CS415

Table of contents

1 Overview 2 How to Get Started 3 How to Test Your Code 4 Submission 5 For the Adventurous 6 Final Word

Overview

Your task in this project is to write a non-preemptive user-level threads package. Most operating systems, e.g. Solaris, Mach and DEC OSF, provide such a lightweight thread abstraction because, as you might recall from the lectures and the reading, user-level threads provide concurrency with very low-overhead. NT does not have a user-level threads library. Your task is to write one.

We have provided you with some skeletal code that creates an environment on top of NT that closely resembles the environment on top of raw hardware shortly after booting. We use NT to provide us with a virtual processor and memory. NT also bootstraps our kernel; that is, it loads it into memory and starts executing it at its entry point. Your task is to build high-level abstractions on top of this environment in the same manner NT builds its abstractions on top of the hardware.

There are a few distinct components to this project.

• First, you will have to write some generic FIFO (first-in, first-out) enqueue and dequeue operations. We will be relying on this queue implementation throughout the rest of the semester, so it's important that the implementation be efficient. Specifically, enqueue and dequeue operations should both work in O(1) time.
• Second, you need to define and implement thread control blocks, and the functions that operate on them. We suggest you start with minithread_create and minithread_yield, and go on to implement the scheduler. Once you have those two working, you can come back to implement the rest of the functionality.
• Third, you need to implement a scheduler. For this assignment, all you need is a first-come, first-served scheduler. You can assume that your threads will voluntarily give up the CPU, which means that your test programs should make occasional calls to minithread_yield().
• Fourth, you need to implement semaphores in order to be able to synchronize multiple threads.
• Finally, you need to demonstrate your threads package by implementing a solution to the "food services" problem. This is actually an instance of the better-known multiple-producer, multiple-consumer problem. There are N cooks (each a separate minithread) that constantly produce burgers. We'll assume for debugging purposes that each burger has a unique id assigned to it at the time it is created. The cooks place their burgers on a stack (at the front of the queue you built earlier in this assignment). There are M hungry students (each a separate minithread) that constantly grab burgers from the stack and eat them. Each time a student eats a burger, she prints a message containing the id of the burger she just ate. Ensure, for health and sanity reasons, that a given burger is consumed at most once by at most one student.

How to Get Started

To unpack and set up minithreads in Visual Studio under Windows NT, do the following:

• Download the code from the course management website.
• Open Microsoft Visual Studio C++.
• Select "New" from the File menu to create a new project. Choose to create a new Makefile, enter "minithreads" for the project name, and whatever location you want, and click "Ok".
• For Visual Studio .NET:
  • click application settings tab
  • enter the following for build command line: nmake /f "Makefile.VSNET"
  • enter the following for rebuild command line: nmake /f "Makefile.VSNET" /a
• For Visual Studio 6.0:
  • In the dialog box, replace "minithreads.mak" with "Makefile" in the "Command line" text box and click "Finish".
• Unzip the "minithreads.zip" file in the directory for your project. Make sure the Makefiles and code are in the same directory as the VS project files.
• Click on the "FileView" tab to get the list of the files. Go to the "Source Files" folder and right-click to get "Add Files to Folder", then select all the .c files. Do the same in the "Header Files" folder, and add all the .h files.
• If you are NOT working in the undergraduate lab, and the computer you are using does not have Visual Studio installed in the usual place (c:\Program Files\Microsoft Visual Studio), then change the line VISUALSTUDIO = c:\Program Files\Microsoft Visual Studio in "Makefile" to point to the correct location.
• Select "Build minithreads.exe" from the "Build" menu. It should compile and link with a bunch of warnings. If you execute minithreads.exe, it will terminate immediately.

If you decide not to use the integrated development environment (visual studio), you can use any other editor you like and compile the code from the command line. To compile the code from the command line, go to the directory where you unpacked the project and type make to compile the project incrementally (will detect which files have been modified and recompile them) or nmake clean to delete all of the intermediate files. Advanced students wishing to use the Jornadas early can do a nmake wince once they have all of the necessary software installed, and run their code on the Jornadas. Note that for this assignment, your code does not need to run on the Jornadas - we'll start to use these devices starting with the next project.

Three small test programs, test1.c, test2.c, and test3.c, are included in the minithreads.zip file. They test spawning a thread, spawning multiple threads, and ping-ponging between threads. They should be useful when you are implementing minithreads. Two larger test programs, buffer.c, a bounded buffer, and sieve.c, a sieve for finding primes, are more complicated. Ideally, you should test your minithreads implementation against these.

If you have problems with the project or questions, please send mail to the course mailing list and come to office hours for one of the TAs.

How to Test Your Code

It's crucial that systems code be correct and robust. You must test your code with reasonable and unreasonable test cases, and ensure that it behaves correctly. Note that you should maintain some separation between the minithread package and minithread applications. Most notably, your minithread applications should not contain any dependencies on the scheduling algorithm or on the lack of preemption.

To facilitate testing, we provided you with some test programs. It's a good idea to start with these, and develop your own tests as you need them. The simplest test cases are test1.c, test2.c and test3.c, which test single thread creation, multiple thread creation, and ping-pong between two threads. buffer.c provides a bounded buffer implementation. A producer and consumer keep producing values and consuming them across a buffer of finite length. sieve.c is a Sieve of Eratosthenes for concurrently searching for primes. It has a single thread on one end, injecting the numbers 1, 2, 3, 4, 5, 6, 7, 8, ... into a pipe. For each prime p, there is a thread in the middle of the pipe that consumes a number from the pipe if that number is divisible by p. Otherwise, it passes the value on to the next thread in the pipe. At the very end, there is a thread that prints the values that emerge from the pipe. Note that this assembly will only print out prime numbers, because the threads in the pipe will consume all non-primes.

Since we will soon make the threads package preemptive, all code you write should be properly synchronized. That is, everything should work no matter where in the application thread you place a minithread_yield. Consequently, it's a good idea to test your code with minithread_yield's inserted at random locations throughout the application code (note that we don't expect the system code in minithread.c or synch.c to be yield-safe for this project - just the applications).

Do not forget to check for memory leaks. Your threads package should not run out of memory when large numbers of threads are created and destroyed.

Submission

Submit all your code (everything you wrote or used, including sources, Makefile, documentation and extraneous testing code) through CMS. Everything should be in a single ZIP file that unpacks into a single minithreads[projectnumber] directory, with no subdirectories. By default, your Makefile should have the MAIN symbol set to "prodcons", and running nmake in your project directory should produce prodcons.exe, your producer-consumer program.

For the Adventurous

Note: These suggestions for an extra challenge will be examined but not graded. They will have no impact on the class grades. They are here to provide some direction to those who finish their assignments early and are looking for a way to impress friends and family.

Implement the barber shop problem. That is:

• the barber shop has two rooms: the waiting room and the barber room. At any given time there can be at most one customer in the barber room but any number of customers in the waiting room.
• if the barber is busy (shaving a customer) and another customer arrives, he will wait in the waiting room
• if a customer arrives and the barber is sleeping in the waiting room, he wakes the barber
• when the barber finishes shaving a customer and no other customer is waiting in the waiting room, the barber goes to sleep in the waiting room

Add preemption and implement a multilevel feedback queue with four levels, with round-robin at each level, and where the time quanta doubles at every level. Demonstrate that it works as intended.

Final Word

Here are the frequently asked questions about Project 1. If you need help with any part of the assignment, we are here to help. If you start early, this should be an incredibly fun project.