Split up documentation further. Add lpsm_need_checkpoint local variable.

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.