[svn-r467] Restructuring documentation.

1 files changed, 72 insertions, 0 deletions

diff --git a/doc/html/heap.txt b/doc/html/heap.txt
new file mode 100644
index 0000000..6b4c058
--- /dev/null
+++ b/doc/html/heap.txt
@@ -0,0 +1,72 @@
+		       HEAP MANAGEMENT IN HDF5
+		       ------------------------
+
+Heap functions are in the H5H package.
+
+
+off_t
+H5H_new (hdf5_file_t *f, size_t size_hint, size_t realloc_hint);
+
+	Creates a new heap in the specified file which can efficiently
+	store at least SIZE_HINT bytes.  The heap can store more than
+	that, but doing so may cause the heap to become less efficient
+	(for instance, a heap implemented as a B-tree might become
+	discontigous).  The REALLOC_HINT is the minimum number of bytes
+	by which the heap will grow when it must be resized. The hints
+	may be zero in which case reasonable (but probably not
+	optimal) values will be chosen.
+
+	The return value is the address of the new heap relative to
+	the beginning of the file boot block.
+
+off_t
+H5H_insert (hdf5_file_t *f, off_t addr, size_t size, const void *buf);
+
+	Copies SIZE bytes of data from BUF into the heap whose address
+	is ADDR in file F.  BUF must be the _entire_ heap object.  The
+	return value is the byte offset of the new data in the heap.
+
+void *
+H5H_read (hdf5_file_t *f, off_t addr, off_t offset, size_t size, void *buf);
+
+	Copies SIZE bytes of data from the heap whose address is ADDR
+	in file F into BUF and then returns the address of BUF.  If
+	BUF is the null pointer then a new buffer will be malloc'd by
+	this function and its address is returned.
+
+	Returns buffer address or null.
+
+const void *
+H5H_peek (hdf5_file_t *f, off_t addr, off_t offset)
+
+	A more efficient version of H5H_read that returns a pointer
+	directly into the cache; the data is not copied from the cache
+	to a buffer.  The pointer is valid until the next call to an
+	H5AC function directly or indirectly.
+
+	Returns a pointer or null.  Do not free the pointer.
+
+void *
+H5H_write (hdf5_file_t *f, off_t addr, off_t offset, size_t size,
+           const void *buf);
+
+	Modifies (part of) an object in the heap at address ADDR of
+	file F by copying SIZE bytes from the beginning of BUF to the
+	file.  OFFSET is the address withing the heap where the output
+	is to occur.
+
+	This function can fail if the combination of OFFSET and SIZE
+	would write over a boundary between two heap objects.
+
+herr_t
+H5H_remove (hdf5_file_t *f, off_t addr, off_t offset, size_t size);
+
+	Removes an object or part of an object which begins at byte
+	OFFSET within a heap whose address is ADDR in file F.  SIZE
+	bytes are returned to the free list.  Removing the middle of
+	an object has the side effect that one object is now split
+	into two objects.
+
+	Returns success or failure.
+
+