|author||H. Peter Anvin <email@example.com>||2001-10-23 04:56:49 +0000|
|committer||H. Peter Anvin <firstname.lastname@example.org>||2001-10-23 04:56:49 +0000|
Add man pageslpsm-0.1.4
Diffstat (limited to 'lpsm_init.3.in')
1 files changed, 156 insertions, 0 deletions
diff --git a/lpsm_init.3.in b/lpsm_init.3.in
new file mode 100644
@@ -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.
+.TH LPSM_INIT 3 "22 October 2001" "LPSM @@VERSION@@" "Linux Persistent Memory"
+lpsm_init, lpsm_checkpoint, lpsm_shutdown \- Manage persistent memory
+.B #include <lpsm.h>
+.BI "void **lpsm_init(const char " "*datafile" ", const char " "*logfile" ");"
+.BI "pid_t lpsm_checkpoint(double " "ratio" ", enum pmsync " "wait" ");"
+.BI "void lpsm_shutdown(void);"
+These functions manage a persistent memory arena in managed mode,
+available for use with
+and its related functions.
+opens or creates the managed persistent memory store the filenames of
+.IR logfile .
+On success, returns a pointer to an array of
+(32) "root pointers"
+.RI ( "void\ *" ),
+which are available for the application to point to its
+fundamental data structures. On failure, returns
+.BR NULL .
+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
+guaranteed to be returned to the state
+as of one of the calls to
+.BR lpsm_checkpoint() ;
+which exact one depends on the
+parameter indicates if a log flush should take
+place; if the logfile is at least
+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
+to do a log flush every time,
+to specify that no log flush should happen.
+parameter controls the level of asynchronicity of the checkpoint process:
+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
+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.
+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
+the latest checkpoint executed.
+for the previous
+current checkpoint processes. This guarantees that upon exit of
+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
+to perform a clean shutdown.
+shuts down the persistent memory system, frees all resources,
+and restores the previous state of the
+.IR "It does not perform a checkpoint before doing so" ;
+normally a clean shutdown is performed as:
+lpsm_checkpoint(0.0 , PSMSYNC_SYNC);
+can be used in exceptional events to reinitialize the arena to the
+last checkpointed state. This is a very slow operation.
+.SH "RETURN VALUES"
+returns the pointer to the root pointer array, or
+returns 0 after a successful synchronous operation,
+on failure, or the pid of the spawned asychronous process.
+does not return a value.
+.SH "SEE ALSO"
+.BR lpsm_malloc (3),
+.BR lpsm_arena_init (3).
+Checkpointing failures are currently not handled gracefully.