aboutsummaryrefslogtreecommitdiffstats
path: root/README
diff options
context:
space:
mode:
authorH. Peter Anvin <hpa@zytor.com>2001-10-25 18:34:11 +0000
committerH. Peter Anvin <hpa@zytor.com>2001-10-25 18:34:11 +0000
commit9f4b121beb7c16b26f25a694ceba998d3d1a23c8 (patch)
tree1bdec3198144dc7dd2c846ba84ca27edab4bde64 /README
parent731beed733a3fa023eeeb63477cfbc80e0edc43a (diff)
downloadlpsm-9f4b121beb7c16b26f25a694ceba998d3d1a23c8.tar.gz
lpsm-9f4b121beb7c16b26f25a694ceba998d3d1a23c8.tar.xz
lpsm-9f4b121beb7c16b26f25a694ceba998d3d1a23c8.zip
- Clean up documentation.lpsm-0.1.8
- Add lpsm_recover(). - Add zalloc test. - Be better about returning useful error information in errno.
Diffstat (limited to 'README')
-rw-r--r--README201
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)