nhmalloc README
AUTHOR: Nick Mosier
10/18/2018


FILES:
 * nhmalloc.c: contains implementations of malloc(), free(), calloc(), realloc()
 * memblock.c (memblock.h): contains underlying functions for handling 'memblocks', the
      fundamental type of chunks of memory that malloc allocates. These functions them-
      selves wrap more specialized functions in btree.c and list.c
 * btree.c (btree.h): contains functions for modifying the binary tree of free memblocks
 * list.c (list.h): contains functions for modifying the (reverse) linked list of all
      memblocks.
 * test.c: standalone program for testing nhmalloc
 * tests.sh: runs test program on multiple different configurations


OVERVIEW:
The fundamental type of a memory block managed by nhmalloc is 'memblock_t'. These memory
blocks are in the heap (data segment) and end at the program break.
The memory blocks are organized in two structures:
 * the FREE TREE: a binary search tree that contains all free memory blocks, sorted by size
 * the MEMBLOCK LIST: a (reverse) linked list containing all memory blocks (free and used)
When memory is requested through malloc(), the free tree is searched for the memory block
with the best-fit size for the amount requested (minimum size block_size such that
block_size ≥ size_requested). Before allocation, the memory block is split in two (if there
is enough room for the overhead) such that any extra space is reinserted into the free tree
as a new memblock. The (pointer to the non-reserved memory after the header of the) split
memblock of the requested size is then returned by malloc().

SYSTEM REQUIREMENTS:
 * compatible with UNIX-based systems
 * tested on macOS 10.14.1 (Darwin Kernel Version 18.2.0) and Linux (Fedora 27)

INVARIANTS:
The invariants of the underlying nhmalloc memblock structures upon entry and exit of malloc(),
free(), calloc(), and realloc() are the following:
 * the free tree never contains allocated memory blocks
 * the memblock list never contains two adjacent free memory blocks
 * there are no memory gaps, i.e. each node of the memblock list
   borders two other nodes (except for the end nodes)
 * all memblocks and pointers returned by malloc/calloc/realloc are 16-byte aligned


DEBUGGING:
Enable DEBUG mode:
* DEBUG FLAG: there is a DEBUG flag in "debug.h" -- to enable debug mode, change
   >   #define DEBUG 0
              to
  >    #define DEBUG 1

Compiling with nhmalloc debug mode enabled will have malloc() and free() validate the
state of the free tree and memblock list just before returning. The validation functions,
wrapped in memblocks_validate(), verify the structures and enforce all the invariants
listed under INVARIANTS.

If an inconsistency is detected, then nhmalloc will print out the free tree and the
memblock list in full (it can be quite long...). You'll definitely need a wide screen
to view the free tree properly if there are more than say 30 free memblocks. The functions
for printing out the list and tree manually are:
 * btree_print()
 * list_print()


TESTING:
The file test.c contains a program that tests nhmalloc and is configurable through
command-line arguments. Here's the usage:
       usage: ./test [-n maxsize] [-p nptrs] [-o noperations] [-s seed]
              -n: maximum size (in bytes) per allocation using malloc()
              -p: maximum number of pointers referencing any allocated memory in heap
              -o: number of "operations", defined as a call to malloc() or free()
              -s: seed for pseudorandom number generator used for randomizing test
Note that all command-line arguments are optional (there are presets in the program).

Update: I added a new 'make' target called 'ls' -- the command 'make ls' runs the following:
        LD_PRELOAD=./nhmalloc.so ls -l -R ~
It recursively lists all files in the user's directory.

KNOWN BUGS: (none)

UPDATE:
* nhmalloc now only returns 16-byte aligned pointers. This fixed the crash that would
  occur with the command
  $ ls -l /home
  nhmalloc now displays the entire long listing of the /home directiory, if you wait
  a couple minutes. I also tried compiling parts of my program using gcc with nhmalloc
  preloaded, and that seemed to work.

* nhmalloc also now allocates the last 3 fields of the block header, which are only used
  when the block is free.

* realloc() tries to merge the memory with adjacent blocks before allocating a new one



FUTURE WORK:
* balancing of free tree