===========================================================================

	    Hoard - A fast, scalable, and memory-efficient
		    multithreaded memory allocator

			   October 26, 1999
				   
			     Emery Berger

---------------------------------------------------------------------------
emery@cs.utexas.edu                | <http://www.cs.utexas.edu/users/emery>
Department of Computer Sciences    |             <http://www.cs.utexas.edu>
University of Texas at Austin      |                <http://www.utexas.edu>
===========================================================================


What's Hoard?
-------------

The Hoard memory allocator is a fast, scalable, and memory-efficient
memory allocator for shared-memory multiprocessors.


Why Hoard?
----------

Multithreaded programs that perform dynamic memory allocation do not
scale because the heap is a bottleneck. When multiple threads
simultaneously allocate or deallocate memory from the heap, they will
be serialized while waiting for the heap lock. Programs making
intensive use of the heap actually slow down as the number of
processors increases. (Note: If you make a lot of use of the STL, you
may not know it, but you are making a lot of use of the heap.)

Hoard is a fast allocator that solves this problem. In addition, it
has very reasonable bounds on memory consumption.


How do I use it?
----------------

Using Hoard is easy. It is written to work on any variant of UNIX that
supports pthreads, and should compile out of the box using make.  (See
INSTALL for more details.)

** NOTE: To build for Windows NT under CygWin
** (http://sourceware.cygnus.com), use the following command:
** 	./configure --enable-windowsnt
** or
**	make -f Makefile.orig USE_WINDOWS=1
**

** NOTE: To build for the sproc library (on the SGI),
** 	./configure --enable-sproc
** or
**	make -f Makefile.orig USE_SPROC=1

You can build Hoard in one of two ways (see INSTALL). Below, I assume
you used the configure script.

To link Hoard with the program foo (after doing "make install"):

	g++ foo.o -L/usr/local/lib -lhoard -lpthread -o foo

You *must* add "-lpthread" to your list of libraries (except if you're
using the sproc library on the SGI). Don't forget to add
/usr/local/lib to your LD_LIBRARY_PATH environment variable.

In UNIX, you might be able to avoid relinking your application and use
Hoard just by changing the environment variable LD_PRELOAD, as in

	setenv LD_PRELOAD "/lib/libpthread.so.0 /usr/local/lib/libhoard.so"

This won't work for applications compiled with the "-static" option.


Did it work?
------------

When you compile Hoard ("make"), you'll get four test programs:
testmymalloc(-hoard) and threadtest(-hoard). The first one is just
to measure raw, uniprocessor speed. The second one lets you observe
scalability with multiple threads.

** NOTE: using the configure script dynamically links these two
** (*-hoard) to the Hoard library. Static linking (using "make -f
** Makefile.orig") improves performance (at the cost of increasing the
** size of the executable).

For instance,

	threadtest 2 100000

will create two threads that will each allocate and free 50,000 objects.
Compare this to

	threadtest-hoard 2 100000

(the same program as above, but linked with Hoard).

Hoard has been successfully built on a 2-processor x86 running Windows
NT SP4 with CygWin, a 4-processor x86 box running Linux (Red Hat 6.0,
kernel version 2.2.5-22 SMP) and a 14-processor SPARC running Solaris
7.


More information
----------------

For more information on Hoard, along with some nice performance graphs, see

	Hoard: A Fast, Scalable and Memory-Efficient Allocator
	       for Shared-Memory Multiprocessors
	September 1999
	Submitted for publication, available as UTCS Tech Report 99-22.

	(Included in this distribution in docs/UTCS-TR99-22.ps.gz)

The latest version of Hoard will always be available from my web page:

	<http://www.cs.utexas.edu/users/emery>


Feedback
--------

Please send any bug reports and information about new platforms Hoard
has been built on to emery@cs.utexas.edu.


Mailing list
------------

A low-volume mailing list has been set up for announcements of new releases
of Hoard. To subscribe, go to my home page (www.cs.utexas.edu/users/emery)
and enter your e-mail address in the "Hoard group" box.


Acknowledgements
----------------

In addition to those thanked in the paper, I'd like to thank Ganesan
Rajagopal for submitting the autoconf and automake scripts.


--
Emery Berger                           | Parallel Programming
emery@cs.utexas.edu                    | & Multiprogramming MP Groups 
<http://www.cs.utexas.edu/users/emery> | University of Texas at Austin

