- Clean up documentation.lpsm-0.1.8

- Add lpsm_recover().
- Add zalloc test.
- Be better about returning useful error information in errno.

1 files changed, 20 insertions, 181 deletions

diff --git a/README b/README
index 4d2aa35..a4ec808 100644
--- a/README
+++ b/README
@@ -1,4 +1,15 @@
 This is a test release of the Linux Persistent Memory system.
+The LPSM is a C library with a simple interface that manages a segment
+of memory backed by a persistent file. LPSM differs from ordinary
+mmap() in two ways: it can optionally offer heap management
+(malloc()/free()/realloc()) within the arena; more importantly, a
+transaction log is used to ensure the consistency of the persistent
+representation. The application notifies LPSM whenever the arena is in
+a consistent state, suitable for "checkpointing". If the application
+or system crashes, the arena will always be recovered to a consistent
+checkpoint.
+
+
 
 Unless otherwise noted, all files in this distributions are:
 
@@ -51,188 +62,16 @@ used for the commit log.
 
 The LPSM library installs a signal handler for SIGSEGV.
 
+Please see the following man pages included with this distribution:
 
-* Functions to use in unmanaged mode:
-
-void *lpsm_arena_init(const char *datafile, const char *logfile,
-                      size_t *arena_size, void *arena_base)
-
-	Open the persistent memory arena that consists of the two
-	files datafile and logfile.  If these files don't exist, they
-	are created.  The argument "arena_size" contains the minimum
-	size of the arena (if smaller, it will be resized to this
-	size.)  On exit, it contains the actual size of the arena.
-
-	It returns a pointer to the arena, or NULL on error.
-
-	If arena_base is set, try to map the arena at that particular
-	base address.  If arena_base is NULL, use an
-	architecture-specific default value.
-
-
-pid_t lpsm_checkpoint(double ratio, enum psmsync wait)
-
-	Called to indicate that the memory arena is currently in a
-	consistent state and is safe to checkpoint.  On a crash, the
-	memory arena is ALWAYS guaranteed to be returned to the state
-	as of one of the calls to lpsm_checkpoint(); which exact one
-	depends on the "wait" argument.
-
-	The "ratio" parameter indicates if a log flush should take
-	place; if the logfile is at least "ratio" times the size of
-	the datafile, a log flush (replay the log into the datafile
-	and truncate the logfile) will happen once the log has been
-	written.  Specify 0.0 to do a log flush every time, HUGE_VAL
-	to specify that no log flush should happen.
-
-	The "wait" parameter controls the level of asynchronicity of
-	the checkpoint process:
-
-	PSMSYNC_NONE    - A checkpoint is unconditionally forked, and
-	not waited for.  The application is responsible for handing
-	or ignoring the resulting SIGCHLD.  This provides no
-	guarantees that a checkpoint is complete until the SIGCHLD
-	comes back.
-
-	PSMSYNC_SKIP	- wait() for the previous checkpoint process,
-	if it is still running, skip this checkpoint opportunity.
-	This provides no guarantees for which checkpoint opportunity
-	will be used in the event of a crash, but is useful if
-	checkpoint opportunities are very frequent, and continued
-	execution of the master process is important.
-
-	PSMSYNC_WAIT	- wait() for the previous checkpoint process,
-	if it is still running, sleep until the previous checkpoint
-	process has finished.  This guarantees that in the event of a
-	crash, the recovery point will be no later that one checkpoint
-	*before* the latest checkpoint executed.
-
-	PSMSYNC_SYNC	- wait() for the previous *and* current
-	checkpoint processes.  This guarantees that upon exit of
-	lpsm_checkpoint() the persistent memory is fully consistent on
-	disk.  This guarantees that in the event of a crash, the
-	recovery point will be no later than the latest checkpoint
-	executed.  This is typically used with a "ratio" argument of
-	0.0 to perform a clean shutdown.
-
-	lpsm_checkpoint() returns (pid_t)-1 on error; on success, it returns
-	0 if no asynchronous checkpoint process is pending, otherwise
-	the pid of the asynchronous checkpoint process.
-	
-
-int lpsm_extend(size_t newsize)
-
-	Extends the size of the arena to "newsize".  Returns 0 on
-	success, -1 on error.
-
-
-void lpsm_shutdown(void)
-
-	Shuts down the persistent memory system, frees all resources,
-	and restores the previous state of the SIGSEGV signal handler.
-	IT DOES NOT PERFORM A CHECKPOINT BEFORE DOING SO -- normally a
-	clean shutdown is performed as:
-
-		lpsm_checkpoint(0.0, PSMSYNC_SYNC);
-		lpsm_shutdown();
-
-	Calling lpsm_shutdown() followed by lpsm_arena_init() or
-	lpsm_init() can be used in exceptional events to reinitialize
-	the arena to the last checkpointed state.  This is very slow,
-	however.
-
-
-* Functions to use in managed mode:
-
-void **lpsm_init(const char *datafile, const char *logfile)
-
-	Opens/creates the managed persistent memory store defined by
-	datafile and logfile.  On success, returns a pointer to an
-	array of LPSM_ROOT_POINTERS (32) "root pointers" (void *),
-	which are available for the application to point to its
-	fundamental data structures.  On failure, returns NULL.
-
-
-void *lpsm_malloc(size_t size)
-
-	Allocates "size" bytes of persistent memory.  Returns a
-	pointer to the newly allocated memory, or NULL on failure.
-	The memory is uninitialized.
-
-
-void lpsm_free(void *ptr)
-
-	Frees the allocation pointed to by ptr.
-
-
-void *lpsm_realloc(void *ptr, size_t new_size)
-
-	Attempts to resize the allocation pointed to by ptr to size
-	"new_size".  Returns a pointer to the new allocation on
-	success, NULL on failure.  If the returned pointer is
-	different from ptr, the contents of the old allocation is
-	copied into the new allocation.  If new_size is greater than
-	the old size, the bytes beyond the old allocation size are
-	uninitialized.
-
-	If ptr == NULL, this call is equivalent to lpsm_malloc().
-
-	If new_size is zero, this call is equivalent to:
-
-	   lpsm_free(ptr);
-	   return NULL;
-
-void *lpsm_zalloc(size_t size)
-void *lpsm_calloc(size_t nmemb, size_t size)
-
-	Same as lpsm_malloc(), but returns memory that is initialized
-	to zero.  The implementation attempts to be smart, and for
-	large blocks can be significantly more efficient than
-	lpsm_malloc() followed by memset().
-
-	lpsm_calloc() is implemented as an inline or macro which
-	returns lpsm_zalloc(nmemb*size).
-
-
-struct lpsm_alloc_stats {
-  size_t size;
-  size_t free;
-  size_t alloc;
-};
-struct lpsm_alloc_stats *lpsm_alloc_stats(void);
-
-	Returns an array, malloc()'d in conventional (transient)
-	memory, containing allocation statistics: for each block size,
-	the size in bytes, number of blocks free, and number of blocks
-	allocated (in use).  The list terminates with an entry with
-	size == 0.  It is the responsibility of the application to
-	free() the allocated list.
-
-	Returns NULL on failure.
-
-
-pid_t lpsm_checkpoint(double ratio, enum psmsync wait)
-
-	Identical function as in unmanaged mode.
-
-
-void lpsm_shutdown(void)
-
-	Identical function as in unmanaged mode.
-
-
-The memory allocator used is a hybrid buddy system/slab allocator,
-which has the following properties:
+Unmanaged mode:
 
-* Allocation of large blocks are always page-aligned; allocation of
-  powers of 2 is very efficient;
+	lpsm_arena_init(3)
+	lpsm_recover(3)
 
-* Allocation of small blocks can be done efficiently down to single
-  bytes.  Allocation of small blocks (2032 bytes or less in the
-  current implementation) are aligned to a 16-byte datum unless they
-  are 8 bytes or smaller in size (in which case they are aligned to
-  the nearest higher power of 2.)
+Managed mode:
 
-* The allocator is very sensitive to bogus pointers passed to
-  lpsm_free() or lpsm_realloc().  Passing bogus pointers to these
-  routines is very likely to result in arena corruption or crash.
+	lpsm_init(3)
+	lpsm_malloc(3)
+	lpsm_arena_stats(3)
+	lpsm_recover(3)