Skip to content

Commit

Permalink
Added documentation to the test file and updated README so users can …
Browse files Browse the repository at this point in the history 
…easily extend the test suite if so desired. Also renamed the test file from testCHENEY.c -> cheney.c and updated the Makefile and README links accordingly. Was also able to remove the library section in the Makefile and cleanup some test names as well as fixing a small description error about atomic data in the README.
  • Loading branch information
@rrozansk
rrozansk committed Dec 28, 2017
1 parent 4752601 commit ee91121
Show file tree
Hide file tree
Showing 3 changed files with 55 additions and 48 deletions.
12 changes: 4 additions & 8 deletions Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,12 @@ CC = gcc
CFLAGS = -Wall -O3
# includes (header file locations)
INCLUDES = -I/include/ -Iinclude/
# libraries (library file location)
LFLAGS = -L/lib/
# libraries to link
LIBS = -lm
# all the files to include in the generated .tar
# all the files to include in the generated .tar (core project files)
TAR_FILES = include/*.h src/*.c test/*.c LICENSE.txt Makefile README.md
# name of generated tar
TAR_NAME = cheney
# garbage collection table driven tests executable
TEST_DEPS = include/cheney.h src/cheney.c test/testCHENEY.c
# garbage collection table driven testing executable dependencies
TEST_DEPS = include/cheney.h src/cheney.c test/cheney.c
# auto-generate the object files
TEST_OBJS = $(TEST_DEPS:.c=.o)
# define the executable file
Expand All @@ -40,6 +36,6 @@ tar:
\tar -cvf $(TAR_NAME).tar $(TAR_FILES)

$(TEST): $(TEST_OBJS)
$(CC) $(CFLAGS) $(INCLUDES) -o $(TEST) $(TEST_OBJS) $(LFLAGS) $(LIBS)
$(CC) $(CFLAGS) $(INCLUDES) -o $(TEST) $(TEST_OBJS)
./$(TEST)
\rm -f *.o *~ src/*.o src/*~ include/*.o include/*~ test/*.o test/*~ $(TEST)
4 changes: 2 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,11 @@

[![LICENSE](https://img.shields.io/badge/LICENSE-MIT-green.svg)](https://github.com/rrozansk/Cheney-GC/blob/master/LICENSE.txt) [![RELEASES](https://img.shields.io/badge/Releases-current-green.svg)](https://github.com/rrozansk/Cheney-GC/releases)

An [implementation](https://github.com/rrozansk/Cheney-GC/blob/master/src/cheney.c) of [Cheney](https://en.wikipedia.org/wiki/Cheney%27s_algorithm) style garbage collection allowing the allocation of [cons cells](https://en.wikipedia.org/wiki/Cons). These cells are capable of storing pointers to other cells, NULL, or atomic data (represented as a [tagged pointer](https://en.wikipedia.org/wiki/Tagged_pointer)). This allows the storage of any other data type's pointer or even possibly encoding the information itself directly into a pointer.
An [implementation](https://github.com/rrozansk/Cheney-GC/blob/master/src/cheney.c#L1) of [Cheney](https://en.wikipedia.org/wiki/Cheney%27s_algorithm) style garbage collection allowing the allocation of [cons cells](https://en.wikipedia.org/wiki/Cons). These cells are capable of storing pointers to other cells or atomic data (represented as a [tagged pointer](https://en.wikipedia.org/wiki/Tagged_pointer) or NULL). This allows the storage of any other data type's pointer or even possibly encoding the information itself directly into a pointer.

Furthermore, the heap has been encapsulated into a structure allowing multiple garbage collected heaps to exist simultaneously. Ultimately, this allows clean interaction through a well defined API. However, this could be useful for other reasons, one of which may be to maintain different memory pools if computing on threads. It is also possible, if permitted, for the heap to expand dynamically. Dynamic expansion can only happen when a collection fails in reclaiming memory or through the exposed 'resize' API call. For a more thorough explanation of all the libraries capabilities and exposed API's see the [documentation](https://github.com/rrozansk/Cheney-GC/blob/master/include/cheney.h#L6).

Finally, table driven testing is deployed to ensure correctness and compatability while allowing expansion of test cases with minimal effort. A Makefile is included to help automate and run the [tests](https://github.com/rrozansk/Cheney-GC/blob/master/test/testCHENEY.c) using the commands listed below. If any test fails, or the program exits abnormally, then the implementation is not compatible with the choosen system.
Finally, table driven testing is deployed to ensure correctness and compatability while allowing expansion of test cases with minimal effort. A Makefile is included to help automate and run the [test suite](https://github.com/rrozansk/Cheney-GC/blob/master/test/cheney.c#L6) using the commands listed below. If any test fails or the program exits abnormally then the implementation is not compatible with the choosen system. Following the link above will lead you to directions for adding your own tests to the suite if so desired.

## Prerequisites
- gcc (Ubuntu/Linaro 4.6.3-1ubuntu5) 4.6.3 or equivalent C compiler
Expand Down
87 changes: 49 additions & 38 deletions test/testCHENEY.c → test/cheney.c
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,18 @@
/******************************************************************************
* FILE: testCHENEY.c *
* FILE: cheney.c *
* AUTHOR: Ryan Rozanski *
* CREATED: 10/31/17 *
* EDITED: 11/14/17 *
* INFO: Test file for implementation of the interface located in cheney.h *
* EDITED: 12/28/17 *
* INFO: Table driven testing for the interface located at cheney.h. *
* Extending the test suite is possible if so desired and can be *
* done with minimal effort. First, it requires defining a new test. *
* A test is just a function which takes no arguments and returns a *
* 'testResult_t' type as defined below. Second, an entry must be *
* added to the table. A table entry is an array literal containing *
* two items. Index zero contains the name of test function just *
* written. Index one contains a short string description to print *
* when ran which identifies the specific test. Third, and finally, *
* the integer value of 'TOTAL_TESTS' must be incremeted by one. *
* *
******************************************************************************/

Expand Down Expand Up @@ -36,15 +45,16 @@ unsigned long custom_expander(unsigned long size) { return size + 20; }
* T E S T S *
* *
******************************************************************************/
testResult_t MakeHeapOddCells() {
return make_heap(9) ? PASS : FAIL;
}
testResult_t MakeFreeHeapOddCells() {
heap_t *heap = make_heap(9);
if(!heap) { return FAIL; }

testResult_t MakeHeapEvenCells() {
return make_heap(8) ? PASS : FAIL;
free_heap(&heap);

return !heap ? PASS : FAIL;
}

testResult_t FreeHeapDefault() {
testResult_t MakeFreeHeapEvenCells() {
heap_t *heap = make_heap(8);
if(!heap) { return FAIL; }

Expand All @@ -63,7 +73,7 @@ testResult_t GetDynamicDefault() {
return !dynamic ? PASS : FAIL;
}

testResult_t SetDynamicOn() {
testResult_t SetGetDynamicOn() {
heap_t *heap = make_heap(8);
if(!heap) { return FAIL; }

Expand All @@ -74,7 +84,7 @@ testResult_t SetDynamicOn() {
return dynamic ? PASS : FAIL;
}

testResult_t SetDynamicOnOff() {
testResult_t SetGetDynamicOnOff() {
heap_t *heap = make_heap(8);
if(!heap) { return FAIL; }

Expand All @@ -97,7 +107,7 @@ testResult_t GetDefaultExpander() {
return !expander ? PASS : FAIL;
}

testResult_t SetCustomExpander() {
testResult_t SetGetCustomExpander() {
heap_t *heap = make_heap(8);
if(!heap) { return FAIL; }

Expand All @@ -119,7 +129,7 @@ testResult_t GetDefaultRoot() {
return !root ? PASS : FAIL;
}

testResult_t SetCustomRoot() {
testResult_t SetGetCustomRoot() {
heap_t *heap = make_heap(8);
if(!heap) { return FAIL; }

Expand All @@ -142,7 +152,7 @@ testResult_t EmptyCollections() {
return PASS;
}

testResult_t HeapSizeDefault() {
testResult_t HeapSize() {
heap_t *heap = make_heap(8);
if(!heap) { return FAIL; }

Expand All @@ -152,7 +162,7 @@ testResult_t HeapSizeDefault() {
return size == 8 ? PASS : FAIL;
}

testResult_t HeapSemiSizeDefault() {
testResult_t HeapSemiSize() {
heap_t *heap = make_heap(8);
if(!heap) { return FAIL; }

Expand All @@ -162,7 +172,7 @@ testResult_t HeapSemiSizeDefault() {
return size == 4 ? PASS : FAIL;
}

testResult_t HeapSemiUsedDefault() {
testResult_t HeapSemiUsed() {
heap_t *heap = make_heap(8);
if(!heap) { return FAIL; }

Expand All @@ -172,7 +182,7 @@ testResult_t HeapSemiUsedDefault() {
return size == 0 ? PASS : FAIL;
}

testResult_t HeapSemiLeftDefault() {
testResult_t HeapSemiLeft() {
heap_t *heap = make_heap(8);
if(!heap) { return FAIL; }

Expand All @@ -182,24 +192,26 @@ testResult_t HeapSemiLeftDefault() {
return size == 4 ? PASS : FAIL;
}

testResult_t HeapResizeSmallerDefault() {
testResult_t HeapResizeSmaller() {
heap_t *heap = make_heap(8);
if(!heap) { return FAIL; }

int successful = resize(heap, 4);
int size = heap_size(heap);
free_heap(&heap);

return successful ? PASS : FAIL;
return successful && size == 4 ? PASS : FAIL;
}

testResult_t HeapResizeLallerDefault() {
testResult_t HeapResizeLarger() {
heap_t *heap = make_heap(8);
if(!heap) { return FAIL; }

int successful = resize(heap, 16);
int size = heap_size(heap);
free_heap(&heap);

return successful ? PASS : FAIL;
return successful && size == 16 ? PASS : FAIL;
}

testResult_t EmptyCellAllocation() {
Expand Down Expand Up @@ -344,7 +356,7 @@ testResult_t CorrectAmountCollected() {
return (semi_used(heap) == 1 && semi_left(heap) == 4) ? PASS : FAIL;
}

testResult_t StaticHeapAllocationFailure() {
testResult_t StaticHeapCellAllocationFailure() {
heap_t *heap = make_heap(8); // non-dynamic by default
if(!heap) { return FAIL; }

Expand Down Expand Up @@ -531,26 +543,25 @@ testResult_t DynamicHeapOnOff() {
******************************************************************************/
#define FUNCTION 0 // function ptr @idx 0
#define NAME 1 // test name @idx 1
#define TOTAL_TESTS 38 // # tests in array
#define TOTAL_TESTS 37 // # tests in array/table

void *TESTS[TOTAL_TESTS][2] = {
{ MakeHeapOddCells, "MakeHeapOddCells" },
{ MakeHeapEvenCells, "MakeHeapEvenCell" },
{ FreeHeapDefault, "FreeHeapDefault" },
{ MakeFreeHeapOddCells, "MakeFreeHeapOddCells" },
{ MakeFreeHeapEvenCells, "MakeFreeHeapEvenCells" },
{ GetDynamicDefault, "GetDynamicDefault" },
{ SetDynamicOn, "SetDynamicOn" },
{ SetDynamicOnOff, "SetDynamicOnOff" },
{ GetDefaultExpander, "GetDefaultExpand" },
{ SetCustomExpander, "SetCustomExpande" },
{ SetGetDynamicOn, "SetGetDynamicOn" },
{ SetGetDynamicOnOff, "SetGetDynamicOnOff" },
{ GetDefaultExpander, "GetDefaultExpander" },
{ SetGetCustomExpander, "SetGetCustomExpander" },
{ GetDefaultRoot, "GetDefaultRoot" },
{ SetCustomRoot, "SetCustomRoot" },
{ SetGetCustomRoot, "SetGetCustomRoot" },
{ EmptyCollections, "EmptyCollections" },
{ HeapSizeDefault, "HeapSizeDefault" },
{ HeapSemiSizeDefault, "HeapSemiSizeDefault" },
{ HeapSemiUsedDefault, "HeapSemiUsedDefault" },
{ HeapSemiLeftDefault, "HeapSemiLeftDefault" },
{ HeapResizeSmallerDefault, "HeapResizeSmallerDefault" },
{ HeapResizeLallerDefault, "HeapResizeLallerDefault" },
{ HeapSize, "HeapSize" },
{ HeapSemiSize, "HeapSemiSize" },
{ HeapSemiUsed, "HeapSemiUsed" },
{ HeapSemiLeft, "HeapSemiLeft" },
{ HeapResizeSmaller, "HeapResizeSmaller" },
{ HeapResizeLarger, "HeapResizeLarger" },
{ EmptyCellAllocation, "EmptyCellAllocation" },
{ InitializedCellAllocation, "InitializedCellAllocation" },
{ CellFirstFieldGetter, "CellFirstFieldGetter" },
Expand All @@ -564,7 +575,7 @@ void *TESTS[TOTAL_TESTS][2] = {
{ CellDataFail, "CellDataFail" },
{ CellDataNull, "CellDataNull" },
{ CorrectAmountCollected, "CorrectAmountCollected" },
{ StaticHeapAllocationFailure, "StaticHeapAllocationFailure" },
{ StaticHeapCellAllocationFailure, "StaticHeapCellAllocationFailure" },
{ DynamicHeapDefaultExpand, "DynamicHeapDefaultExpand" },
{ DynamicHeapCustomExpand, "DynamicHeapCustomExpand" },
{ SafeRootedObjects, "SafeRootedObjects" },
Expand Down

0 comments on commit ee91121

Please sign in to comment.