aboutsummaryrefslogtreecommitdiffstats
path: root/README
diff options
context:
space:
mode:
authorH. Peter Anvin <hpa@zytor.com>2001-10-19 06:09:29 +0000
committerH. Peter Anvin <hpa@zytor.com>2001-10-19 06:09:29 +0000
commit7699ea1cbb2cbdc7a81279b23fd4eafe188d99dc (patch)
tree173e73ac01d7678be9f82bc5bfe74ce0dd5c938b /README
parent6f9d2dab5ff8d60ed805a821e9c7d2272c753e81 (diff)
downloadlpsm-7699ea1cbb2cbdc7a81279b23fd4eafe188d99dc.tar.gz
lpsm-7699ea1cbb2cbdc7a81279b23fd4eafe188d99dc.tar.xz
lpsm-7699ea1cbb2cbdc7a81279b23fd4eafe188d99dc.zip
Change names around to be more consistent; set the name of the system to
LPSM (Linux Persistent Memory); set the load address to 0x58000000 on i386 (in case we're on x86-64 in 32-bit mode, or using Andrea's 3.5G patches); change symbol names throughout. Add README file.
Diffstat (limited to 'README')
-rw-r--r--README203
1 files changed, 203 insertions, 0 deletions
diff --git a/README b/README
new file mode 100644
index 0000000..74433b9
--- /dev/null
+++ b/README
@@ -0,0 +1,203 @@
+This is a test release of the Linux Persistent Memory system.
+
+Unless otherwise noted, all files in this distributions are:
+
+ Copyright 2001 H. Peter Anvin - All Rights Reserved
+
+See the file COPYING for licensing conditions.
+
+
+If this was a real release there would be some documentation and a
+much better information in this file.
+
+IMPORTANT: I cannot at this stage guarantee that future versions of
+the LPSM will be binary compatible. These are test releases. Use at
+your own risk.
+
+Currently the persistent memory database is not sharable nor
+thread-safe. I'm hoping to resolve at least the latter condition in
+due time.
+
+
+** Functionality description:
+
+The persistent memory store can be used in two modes: managed and
+unmanaged. Unmanaged provides a flat chunk (arena) of memory without
+any further management support; managed provides management via
+malloc/free/realloc.
+
+All of these use a pair of files as backing store: a datafile, which
+is equivalent in size to the managed memory, and a logfile, which is
+used for the commit log.
+
+The LPSM library installs a signal handler for SIGSEGV.
+
+
+* Functions to use in unmanaged mode:
+
+void *lpsm_arena_init(const char *datafile, const char *logfile, size_t *arena_size)
+
+ 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.
+
+
+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;
+
+
+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:
+
+* Allocation of large blocks are always page-aligned; allocation of
+ powers of 2 is very efficient;
+
+* 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.)
+
+* 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.