path: root/lpsm_init.3.in
diff options
authorH. Peter Anvin <hpa@zytor.com>2001-10-23 04:56:49 +0000
committerH. Peter Anvin <hpa@zytor.com>2001-10-23 04:56:49 +0000
commit03615bdc63d821a8885cda7637701619a8d61ab2 (patch)
tree21d187e51333d9bae6058fdf5e80320855fad5b3 /lpsm_init.3.in
parent7f292cecee3b603b5e1ccea57da0ba59dc113f3c (diff)
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
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"
+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
+.B lpsm_malloc()
+and its related functions.
+.B lpsm_init()
+opens or creates the managed persistent memory store the filenames of
+which are
+.I datafile
+.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
+.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
+.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,
+to specify that no log flush should happen.
+.I wait
+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
+This provides no guarantees that a checkpoint is complete
+until the
+comes back.
+.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.
+.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.
+.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.
+.B lpsm_shutdown()
+shuts down the persistent memory system, frees all resources,
+and restores the previous state of the
+signal handler.
+.IR "It does not perform a checkpoint before doing so" ;
+normally a clean shutdown is performed as:
+lpsm_checkpoint(0.0 , PSMSYNC_SYNC);
+.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.
+.B lpsm_init()
+returns the pointer to the root pointer array, or
+on failure.
+.B lpsm_checkpoint()
+returns 0 after a successful synchronous operation,
+.B "(pid_t)-1"
+on failure, or the pid of the spawned asychronous process.
+.B lpsm_shutdown()
+does not return a value.
+.BR lpsm_malloc (3),
+.BR lpsm_arena_init (3).
+Checkpointing failures are currently not handled gracefully.