
				       POOLS

			   Memory Management routines on
				top of the C runtime 
			     library storage allocator.


	
Motivation:

Good if you need many small pieces of storage which are all of
the same size. Good means: less work and storage overhead than
when using the standard C runtime library storage allocator which
does not know that all the pieces of storage you need are small and
of the same size. It once made my radiosity program faster by a
factor of two!

From version 1.5 on, the pools library will also work around a
storage allocation limitation to 0.5 or 1GB on Linux systems.

 	
Documentation:

Have a look at pools.h (public interface) and poolsP.h (internal data
structures and options)

	
Author:

	Philippe Bekaert
	Computer Graphics Research Group
	Department of Computer Science - K.U.Leuven
	Celestijnenlaan, 200A
	3001 heverlee - Belgium

	Philippe.Bekaert@cs.kuleuven.ac.be
	http://www.cs.kuleuven.ac.be/~philippe/


History:

This is version 2.0.2  December 18, 2000

2000-12-18  Philippe Bekaert  <philippe@cs.kuleuven.ac.be>

	* Free() allows null-pointer argument (like C++ delete operator)

2000-12-15  Philippe Bekaert  <philippe@cs.kuleuven.ac.be>

	* return value and argument type char* of Alloc(), Free() 
	and Realloc() changed to void*

	* FakeFree(): looks like Free but just decreases our counter how
	much memory we have in use (for use in conjunction with C++ delete)

	* nr of allocated bytes now correctly initialised.	

2000-11-03  Philippe Bekaert  <philippe@cs.kuleuven.ac.be>

	* (Almost) completely re-implemented from scratch. Uses new free list
	strategy. Advantages:
	. New() and Dispose() have constant and VERY low cost now, especially
	with lazy garbage collection (see poolsP.h)
	. lower storage overhead (no "trailer" cells and copies anymore)
	. pages have same size and alignement as system memory pages

	* New feature: named pools and routine printing memory breakdown
	. cell allocation trough one routine NewPoolCell() takes additional
	argument 'name' for the pool
	. new function PrintPooledMemoryBreakdown() prints detailled overview
	of allocated and used storage + overhead in all pools.

	* ====> Version 2.0

2000-10-16  Philippe Bekaert  <philippe@cs.kuleuven.ac.be>

	* some explicit datatype casts introduced in pools.c in order to
	make it safe on 64-bit architectures. 
	NOTE: POOL_ALIGN needs to be set to 8 (8-byte pool cell alignement) 
	on such architectures!!!

2000-09-09  Philippe Bekaert  <philippe@cs.kuleuven.ac.be>

	* pages now grouped in "master blocks" of 1024 pages. By
	allocating memory in such sufficiently large chunks, we work
	work a storage allocation limitation to 0.5 or 1GB on Linux.
	(suggested by Jan Prikryl)
	====> Version 1.5

1998-08-04  Philippe Bekaert  <philippe@cs.kuleuven.ac.be>

	* new cell allocation strategy uses free cell chain instead of
	allocation bitmap. Memory overhead is reduced to <2 percent
	+ faster and cleaner AllocCell().
	====> Version 1.4

Mon Jul 28 18:54:32 1997  Philippe Bekaert  <philippe@flater.cs.kuleuven.ac.be>

	* pools.h: "C" conditionally added before function prototypes in
	order to make the library work with C++.
	====> Version 1.3.2.
	
Fri Jun 20 17:12:37 1997  Philippe Bekaert  <philippe@flater.cs.kuleuven.ac.be>

	* pools.h: allocmap field removed from the public POOL struct
	declaration as ANSI C forbids 0-length character strings.
	====> Version 1.3.1.
	
Thu May 29 16:26:47 1997  Philippe Bekaert  <philippe@flater.cs.kuleuven.ac.be>

	* Version 1.3 released.
	
	* Dispose(): check for NULL pointer introduced.

Tue May 13 14:10:19 1997  Philippe Bekaert  <philippe@flater.cs.kuleuven.ac.be>

	* pools.c: memory allocated for a new POOL in (NewPage()) is
	now cleared. This may solve a problem with FindWhichPage() on
	Solaris. The guess is that NewPage() sometimes gets the same
	storage used for a page that was disposed of previously. If not
	cleared, this storage still might contain old POOL trailer copies
	that may confuse FindWhichPage().

	* pools.c: extra check to prevent infinite loops in AllocCell()
	in case a POOL header gets damaged in certain ways.

	* pools.c: FindWhichPage(): now also checks whether the cellptr 
	belongs to the head of the chain, which is also often the case.
	Further speeds up Dispose().
	
Wed Feb 26 15:40:59 1997  Philippe Bekaert  <philippe@flater.cs.kuleuven.ac.be>

        * pools.c: several "sanity checks" implemented.

Wed Feb 12 13:28:33 1997  Philippe Bekaert  <philippe@flater.cs.kuleuven.ac.be>

	* Version 1.2 released.

	* pools.c: Bug in GetMagic() corrected + cosmetic changes.
	
Tue Feb 11 15:31:57 1997  Philippe Bekaert  <philippe@flater.cs.kuleuven.ac.be>

	* Faster Dispose() without a header per cell by using POOL trailers.
	Storage overhead is now about 4% without per-cell headers.

	* Faster Dispose() and New() by remembering the last page
	from which a cell was Dispose()-d.

Mon Feb  3 23:32:56 1997  Philippe Bekaert  <philippe@strojka.cs.kuleuven.ac.be>
	
	* Version 1.1 released.

	* Alignement: cells are aligned to an 8-byte boundary, unless
	POOL_ALIGN is defined when compiling. POOL_ALIGN must be a
	power of 2!

	* Alignment: new function NewAligned() introduced, which allows
	to specify a non-default alignement for cells in a pool. 

	* Faster Dispose() by using cell-headers fixed. Switch on by
	defining POOL_HEADERS when compiling (seems to work now unlike
	the initial release of August, 9, 1996).

	* New routine DisposeAll() to dispose of all cells in a pool:
	much faster than disposing of them one by one.
	
	* New routine GetMemoryOverhead() returns how many bytes overhead
	is caused by the storage allocator. GetMemoryUsage() now returns
 	the number of bytes asked for by the user, without overhead.
	Allows for tuning and makes more sense.

Tue Aug  6 ??:??:?? 1996  Philippe Bekaert  <philippe@flater.cs.kuleuven.ac.be>

	* Initial version 1.0 released.
