aboutsummaryrefslogtreecommitdiffstats
path: root/lpsm_init.3.in
diff options
context:
space:
mode:
authorH. Peter Anvin <hpa@zytor.com>2001-10-26 01:58:29 +0000
committerH. Peter Anvin <hpa@zytor.com>2001-10-26 01:58:29 +0000
commit4bd929b8e7ca1b8b7d4b2479216eb9120b8b7350 (patch)
treed47d6232353ac73108753c753b124501a9702b9b /lpsm_init.3.in
parent9f4b121beb7c16b26f25a694ceba998d3d1a23c8 (diff)
downloadlpsm-4bd929b8e7ca1b8b7d4b2479216eb9120b8b7350.tar.gz
lpsm-4bd929b8e7ca1b8b7d4b2479216eb9120b8b7350.tar.xz
lpsm-4bd929b8e7ca1b8b7d4b2479216eb9120b8b7350.zip
Split up documentation further. Add lpsm_need_checkpoint local variable.
Diffstat (limited to 'lpsm_init.3.in')
-rw-r--r--lpsm_init.3.in118
1 files changed, 6 insertions, 112 deletions
diff --git a/lpsm_init.3.in b/lpsm_init.3.in
index e07473a..abd87c5 100644
--- a/lpsm_init.3.in
+++ b/lpsm_init.3.in
@@ -10,22 +10,18 @@
.\"
.\" -----------------------------------------------------------------------
.\" $Id$
-.TH LPSM_INIT 3 "22 October 2001" "LPSM @@VERSION@@" "Linux Persistent Memory"
+.TH LPSM_INIT 3 "25 October 2001" "LPSM @@VERSION@@" "Linux Persistent Memory"
.SH NAME
-lpsm_init, lpsm_checkpoint, lpsm_shutdown \- Manage persistent memory
+lpsm_init \- Open persistent memory in managed mode
.SH SYNOPSIS
.nf
.B #include <lpsm.h>
.sp
.BI "void **lpsm_init(const char " "*datafile" ", const char " "*logfile" ");"
-.nl
-.BI "pid_t lpsm_checkpoint(double " "ratio" ", enum psmsync " "wait" ");"
-.nl
-.BI "void lpsm_shutdown(void);"
.fi
.SH DESCRIPTION
-These functions manage a persistent memory arena in managed mode,
-available for use with
+This function is used to manage an LPSM persistent memory arena in
+managed mode, available for use with
.B lpsm_malloc()
and its related functions.
.PP
@@ -42,113 +38,11 @@ On success, returns a pointer to an array of
which are available for the application to point to its
fundamental data structures. On failure, returns
.BR NULL .
-.PP
-.B lpsm_checkpoint()
-is 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
-.I always
-guaranteed to be returned to the state
-as of one of the calls to
-.BR lpsm_checkpoint() ;
-which exact one depends on the
-.I wait
-argument.
-.PP
-The
-.I ratio
-parameter indicates if a log flush should take
-place; if the logfile is at least
-.I 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
-.B 0.0
-to do a log flush every time,
-.B HUGE_VAL
-to specify that no log flush should happen.
-.PP
-The
-.I wait
-parameter controls the level of asynchronicity of the checkpoint process:
-.TP
-.B PSMSYNC_NONE
-A checkpoint is unconditionally forked, and
-not waited for. The application is responsible for handing
-or ignoring the resulting
-.BR SIGCHLD .
-This provides no guarantees that a checkpoint is complete
-until the
-.B SIGCHLD
-comes back.
-.TP
-.B PSMSYNC_SKIP
-.B 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.
-.TP
-.B PSMSYNC_WAIT
-.B 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
-.I before
-the latest checkpoint executed.
-.TP
-.B PSMSYNC_SYNC
-.B wait()
-for the previous
-.I and
-current checkpoint processes. This guarantees that upon exit of
-.B 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
-.I ratio
-argument of
-.B 0.0
-to perform a clean shutdown.
-.PP
-.B lpsm_shutdown()
-shuts down the persistent memory system, frees all resources,
-and restores the previous state of the
-.B SIGSEGV
-signal handler.
-.IR "It does not perform a checkpoint before doing so" ;
-normally a clean shutdown is performed as:
-.nf
-.RS
-.sp
-lpsm_checkpoint(0.0 , PSMSYNC_SYNC);
-.nl
-lpsm_shutdown();
-.nl
-.RE
-.fi
-.PP
-Calling
-.B lpsm_shutdown()
-followed by
-.B lpsm_init()
-can be used in exceptional events to reinitialize the arena to the
-last checkpointed state. This is a very slow operation.
.SH "RETURN VALUES"
.B lpsm_init()
returns the pointer to the root pointer array, or
.B NULL
on failure.
-.PP
-.B lpsm_checkpoint()
-returns 0 after a successful synchronous operation,
-.B "(pid_t)-1"
-on failure, or the pid of the spawned asychronous process.
-.PP
-.B lpsm_shutdown()
-does not return a value.
.SH "ERRORS"
On error,
.B lpsm_init()
@@ -163,8 +57,8 @@ is set to
.SH "SEE ALSO"
.BR lpsm_malloc (3),
.BR lpsm_arena_init (3),
+.BR lpsm_checkpoint (3),
+.BR lpsm_shutdown (3),
.BR lpsm_recover (3).
.SH BUGS
-Checkpointing failures are currently not handled gracefully.
-.PP
The persistent memory system is not currently thread-safe.