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

	      The Hoard Multiprocessor Memory Allocator
			 http://www.hoard.org

			   by Emery Berger
		    http://www.cs.mass.edu/~emery
			  emery@cs.umass.edu

  Copyright (c) 1998 - 2003, The University of Texas at Austin.

---------------------------------------------------------------------------


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 Windows and any variant
of UNIX that supports pthreads, and should compile out of the box
using make. You may need to choose your operating system as follows:

	make USE_LINUX=1
	make USE_WINDOWS=1
	make USE_SOLARIS=1
	make USE_HPUX=1

See Makefile.common for more options. Note that you *must* use the GNU
version of make (standard with Linux).

*****************
UNIX Instructions
*****************

In UNIX, you can use the LD_PRELOAD variable to use Hoard instead of
the system allocator for any program not linked with the -static
option (that's most programs).

*** Solaris (with the Sun Workshop compilers) ***

  setenv LD_PRELOAD "/path/to/libhoard.so /usr/lib/libthread.so /usr/lib/librt.so /usr/lib/libCrun.so.1"

Note: For some security-sensitive applications, Solaris requires that
libraries used in LD_PRELOAD be placed in the /usr/lib/secure
directory. In that event, after copying these libraries into
/usr/lib/secure, set LD_PRELOAD as below:

  setenv LD_PRELOAD "libhoard.so:libthread.so"


*** Linux ***

  setenv LD_PRELOAD "/usr/lib/libdl.so /path/to/libhoard.so /usr/lib/libpthread.so"

NOTE for Debian users: a Debian package for Hoard is available at:

   http://packages.debian.org/libhoard

********************
Windows Instructions
********************

When you build Hoard under Windows, you'll get a libhoard.dll and
libhoard.lib. Put the following into your code as the very first lines:

  #if defined(USE_HOARD) && defined(_WIN32)
  #pragma comment(lib, "libhoard.lib")
  #endif

The best approach is to put this stanza into the first part of a
header file included by all of your code. The pragma ensures that
Hoard loads before any other library (you will need libhoard.lib in
your path). When you execute your program, as long as libhoard.dll is
in your path, your program will run with Hoard instead of the system
allocator.

Note that you MUST compile your program with the /MD flag, as in:

	cl /MD /G6 /Ox /DUSE_HOARD=1 myprogram.cpp

For instance, Hoard will not work if you use the /MT switch to compile
your program.

License information
-------------------

The use and distribution of Hoard is governed by a modified version of
the GNU Lesser General Public License version 2.1 as published by the
Free Software Foundation, http://www.fsf.org: see COPYING for more
details.

Notice that distribution of Hoard requires that you provide a link to
the Hoard website (http://www.hoard.org) in your program's
documentation and/or that you include the source code for Hoard. If
you link with Hoard, you must provide complete object files for your
code to the recipients. Any modifications you make to the source code
must be provided to me. This license further requires that, if you
include the source code of Hoard in your source base, you must make
your entire source base publicly available. If you distribute your
program with Hoard, you must "show" your users these licensing
terms as described in the file COPYING.

Alternatively, you may purchase a commercial license for Hoard that does
not include the above restrictions. Please visit http://www.hoard.org
for more information.


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

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

	Hoard: A Scalable Memory Allocator for Multithreaded Applications
	ASPLOS-IX
	Emery Berger, Kathryn McKinley, Paul Wilson, Robert Blumofe

	(Included in this distribution in docs/asplos2000.pdf).

This version of Hoard was built using the Heap Layers framework:

	Composing High-Performance Memory Allocators
	PLDI 2001
	Emery Berger, Benjamin Zorn, Kathryn McKinley

	(Included in this distribution in docs/pldi2001.pdf).

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

	<http://www.hoard.org>


Feedback
--------

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


Mailing lists
-------------

There are two mailing lists for Hoard:

	hoard-announce@yahoogroups.com: a low-volume mailing list for
	announcements of new releases of Hoard. Only I can post to this list.

	hoard@yahoogroups.com: a mailing list for Hoard-related discussions.
	Any member of the mailing list may post to it.

To subscribe, go to the Hoard home page (www.hoard.org) and enter your
e-mail address in the appropriate box, or just send a message to the
mailing list address to get further instructions on subscribing.

--
Emery Berger
Assistant Professor
Dept. of Computer Science
University of Massachusetts, Amherst
www.cs.umass.edu/~emery
