Add man pageslpsm-0.1.4

1 files changed, 156 insertions, 0 deletions

diff --git a/lpsm_init.3.in b/lpsm_init.3.in
new file mode 100644
index 0000000..d77b70a
--- /dev/null
+++ b/lpsm_init.3.in
@@ -0,0 +1,156 @@
+.\" -*- nroff -*- ---------------------------------------------------------
+.\"   
+.\"   Copyright 2001 H. Peter Anvin - All Rights Reserved
+.\"
+.\"   This program is free software; you can redistribute it and/or modify
+.\"   it under the terms of the GNU Lesser General Public License as
+.\"   published by the Free Software Foundation, Inc.,
+.\"   59 Temple Place Ste 330, Bostom MA 02111-1307, USA; version 2.1,
+.\"   incorporated herein by reference.
+.\"
+.\" -----------------------------------------------------------------------
+.\" $Id$
+.TH LPSM_INIT 3  "22 October 2001" "LPSM @@VERSION@@" "Linux Persistent Memory"
+.SH NAME
+lpsm_init, lpsm_checkpoint, lpsm_shutdown \- Manage persistent memory
+.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 pmsync " "wait" ");"
+.nl
+.BI "void lpsm_shutdown(void);"
+.fi
+.SH DESCRIPTION
+These functions manage a persistent memory arena in managed mode,
+available for use with
+.B lpsm_malloc()
+and its related functions.
+.PP
+.B lpsm_init()
+opens or creates the managed persistent memory store the filenames of
+which are
+.I datafile
+and
+.IR logfile .
+On success, returns a pointer to an array of
+.B LPSM_ROOT_POINTERS
+(32) "root pointers"
+.RI ( "void\ *" ),
+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 "SEE ALSO"
+.BR lpsm_malloc (3),
+.BR lpsm_arena_init (3).
+.SH BUGS
+Checkpointing failures are currently not handled gracefully.