UMBC CMSC202, Computer Science II, Fall 1998, Sections 0101, 0102, 0103, 0104

Project 1: Managing Your Own Heap

Due: Monday September 21, 1998

Objective

The objectives of this project are 1) to practice coding in C++, 2) to review pointer manipulations and linked lists, and 3) gain greater appreciation of memory allocation issues.

Background

The premise of this project is that we are using an operating system where memory allocation can be quite slow; i.e., a call to the malloc() function could be time consuming. In this situation, we could resort to the strategy of asking the system for a lot of memory at once rather than small amounts of memory many times. The disadvantage of this strategy is that we must have some mechanism for managing the memory allocated to our program. We have to remember which blocks of memory has been used and which ones are available for future use. That is, we have to manage our own "heap" --- the term used for the portion of a system's memory used for dynamically allocated storage.

It should come as no surprise that we will use a C++ class to handle the memory management. The class declarations are given below:

#define NULLCELL (-1) class HeapCell { friend class Heap ; // gives access to member functions in heap class private: HeapCell() ; // Yes, even the constructor is private char data ; int next ; char status ; } ; class Heap { public: Heap() ; // default constructor Heap(int size) ; // alternate constructor with initial size int new_cell() ; // returns new cell or NULLCELL int new_cell(char c, int i) ; // new cell with data and next field void free_cell(int i) ; // mark as unused void set_data(int i, char c) ; // store a character in the indicated cell char get_data(int i) ; // what's in the data field? void set_next(int i, int p) ; // store a "pointer" in the indicated cell int get_next(int i) ; // what's in the next field? void debug() ; // dump heap for debugging private: HeapCell *the_heap ; // dynamically allocated array of cells int heap_size ; // number of cells int free_list ; // first free cell } ; #endif

The HeapCell and Heap classes are designed so that all access to allocated "memory" is through the public member functions of the Heap class. The storage space for data is in a dynamically allocated array whose address is stored in the data member the_heap. Space for this array is allocated when a Heap object is constructed. The data member heap_size is used to hold the size of this array. Furthermore, the data member free_list is used to maintain a linked list of array entries that are unused. When a client requests a block of memory using new_cell(), the return value is an index into the array that the_heap points to. That array entry is now considered allocated to the client. Each block of memory is in fact a HeapCell object and can hold one character and one integer. The integer member of HeapCell must be used as an index to the array. In this way, a client can use the HeapCell and Heap classes to create a singly-linked list of characters. The status member of HeapCell is used to record whether that array entry has been allocated. An example program using these classes as well as the class declarations above are available in the directory:

/afs/umbc.edu/users/c/h/chang/pub/cs202/project1/ on the UMBC GL machines.

Assignment

Project 0: as soon as you can, preferably within a day, send email from your GL account to chang@gl.umbc.edu with the subject: "CMSC202 Project 0". This is so I can collect all of your account names on GL. It is important that you do this. Otherwise, I will not be able to set up the project submission system to accept your project.

For this project, you will implement all the member functions of the Heap class. Your implementations should do error checking whenever possible. For example, if the client tries to store 103 in the next member of a HeapCell using the set_next() member function, your implementation of set_next() should check whether 103 is a legal array index. A description of each member function follows:

Heap(): the default constructor. This member function should allocate memory for the heap and do all the initial bookkeeping to set up the heap.
Heap(int size): same as the default constructor, except the client specifies the initial size of the heap.
int new_cell(): finds an unused array entry in the heap and returns its index. If no space is available, this function should return NULLCELL. A wimpy implementation of this function will simply run down the array looking for an unused entry. In a better implementation, the unused entries are kept in a singly-linked list. In an outstanding implementation of this function, when the heap is full, the function will request more memory from the system and copy the data from the old array to the new array. This way, the function will return NULLCELL only when the system is out of memory.
int new_cell(char c, int i): same as above, except the user specifies the values to be stored in the data and next members of the new HeapCell.
void free_cell(int i): record that the HeapCell in array index i is no longer being used. In a non-wimpy implementation, this cell should be added to the linked list of available cells.
void set_data(int i, char c): store a character in the data member of the cell indicated by i.
char get_data(int i): return the character stored in the data member of the cell indicated by i.
void set_next(int i, int p): store the index p in the next member of the cell indicated by i.
int get_next(int i): return the index stored in the next member of the cell indicated by i.
void debug(): print out any vital information about the heap for debugging purposes.

Implementation Issues

You must use C++ for this project. You must not change the class declarations given above in any way. The member functions the Heap class that you implement and any other supporting code should be placed in a file called heap.C.

Note that we define NULLCELL to be the value -1 above. We cannot use 0, because 0 is a legitimate index into an array. Be sure that you do not confuse NULLCELL with NULL.

Despite the remarks about wimpy implementations, you should try having a working wimpy implementation first, then upgrade to a better implementation.

Turning in your program

Due to the recent "migration" of the GL file system to AFS, the submit facility used previously is broken. Instructions for turning in your project will be given out at a later date. Be ready to submit the following 4 files, using the following filenames. Also, please make sure that you complete Part 0 of this project as soon as possible.

"ReadMe": This file should contain a paragraph or two of complete English sentences describing any substantial implementation decisions that you have made and in particular anything that a grader should know. For example, a description of what a user can expect in terms of error messages should be included in this file.
"heap.C": This file should contain all the C++ code needed to compile the Heap and HeapCell classes (i.e., do not split the implementation into several files).
"test.C": This file should contain a sample program that uses the Heap and HeapCell classes. The program must be substantially different from the sample program supplied to you. Also, this program should vigorously exercise the Heap member functions. Your project grade will depend on how well you test your implementation.
"typescript": a transcript of running your programs using the script command in UNIX. You should include tests using the sample program given to you as well as test from your own program in test.C.

Please use the exact filenames as indicated. This helps the graders sort through your projects. Also, note that you do not have to and should not submit a file called "heap.h". This is because you should not have changed the declarations of the Heap and HeapCell classes in the first place. So, your implementation should compile and run correctly using the standard copy of "heap.h".

Last Modified: 8 Sep 1998 12:48:38 EDT by Richard Chang

Back up to Fall 1998 CMSC 202 Section Homepage