summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorH. Peter Anvin <hpa@zytor.com>2001-10-26 01:58:29 (GMT)
committerH. Peter Anvin <hpa@zytor.com>2001-10-26 01:58:29 (GMT)
commit4bd929b8e7ca1b8b7d4b2479216eb9120b8b7350 (patch)
treed47d6232353ac73108753c753b124501a9702b9b
parent9f4b121beb7c16b26f25a694ceba998d3d1a23c8 (diff)
downloadlpsm-4bd929b8e7ca1b8b7d4b2479216eb9120b8b7350.zip
lpsm-4bd929b8e7ca1b8b7d4b2479216eb9120b8b7350.tar.gz
lpsm-4bd929b8e7ca1b8b7d4b2479216eb9120b8b7350.tar.bz2
lpsm-4bd929b8e7ca1b8b7d4b2479216eb9120b8b7350.tar.xz
Split up documentation further. Add lpsm_need_checkpoint local variable.
-rw-r--r--CHANGES5
-rw-r--r--Makefile8
-rw-r--r--arena.c13
-rw-r--r--lpsm.h1
-rw-r--r--lpsm_arena_init.3.in134
-rw-r--r--lpsm_checkpoint.3.in119
-rw-r--r--lpsm_init.3.in118
-rw-r--r--lpsm_shutdown.3.in55
8 files changed, 212 insertions, 241 deletions
diff --git a/CHANGES b/CHANGES
index 156c32c..c6f5448 100644
--- a/CHANGES
+++ b/CHANGES
@@ -1,3 +1,8 @@
+Changes in 0.1.9:
+-----------------
+* Further documentation improvements.
+* Add lpsm_need_checkpoint external variable.
+
Changes in 0.1.8:
-----------------
* Add lpsm_recover()
diff --git a/Makefile b/Makefile
index 8ab7e8d..ebada37 100644
--- a/Makefile
+++ b/Makefile
@@ -14,7 +14,7 @@
TEST = teststore testbuddy testalloc testrecovery zallocevil \
test_mmap ftrunctest
SONAME = libpsm.so.0
-VERSION = 0.1.8
+VERSION = 0.1.9
LIBPSM = libpsm.so.$(VERSION) libpsm.a
CFILES = arena.c bitops.c \
@@ -51,7 +51,7 @@ includedir = $(prefix)/include
mandir = $(prefix)/man
man1dir = $(mandir)/man1
man3dir = $(mandir)/man3
-
+man7dir = $(mandir)/man7
all: $(LIBPSM) test man
@@ -75,9 +75,7 @@ install: all
cd $(INSTALLROOT)$(libdir) && ln -sf libpsm.so.$(VERSION) libpsm.so
$(INSTALL) lpsm.h $(INSTALLROOT)$(includedir)
$(INSTALL) $(MANPAGES) $(INSTALLROOT)$(man3dir)
- cd $(INSTALLROOT)$(man3dir) && ln -sf lpsm_init.3 lpsm_checkpoint.3
- cd $(INSTALLROOT)$(man3dir) && ln -sf lpsm_init.3 lpsm_shutdown.3
- cd $(INSTALLROOT)$(man3dir) && ln -sf lpsm_arena_init.3 lpsm_extend.3
+ cd $(INSTALLROOT)$(man3dir) && ln -sf lpsm_checkpoint.3 lpsm_need_checkpoint.3
cd $(INSTALLROOT)$(man3dir) && ln -sf lpsm_malloc.3 lpsm_free.3
cd $(INSTALLROOT)$(man3dir) && ln -sf lpsm_malloc.3 lpsm_realloc.3
cd $(INSTALLROOT)$(man3dir) && ln -sf lpsm_malloc.3 lpsm_zalloc.3
diff --git a/arena.c b/arena.c
index 6c5a1b0..335400c 100644
--- a/arena.c
+++ b/arena.c
@@ -47,6 +47,11 @@
*/
struct lpsm_arena *lpsm_memory_info = NULL;
+/*
+ * This variable is set when the persistent memory is dirty.
+ */
+sig_atomic_t lpsm_need_checkpoint;
+
/* Wrappers for read() and write() which retries if incomplete */
static ssize_t lpsm_read(int fd, void *buf, size_t count)
{
@@ -159,6 +164,7 @@ static void lpsm_sigsegv(int signal, siginfo_t *siginfo, void *ptr)
case page_clean:
*pageinfo = page_dirty; /* Page now dirty */
PM->dirty_count++; /* For accounting purposes */
+ lpsm_need_checkpoint = 1; /* For user programs */
/* Leave page r/w */
break;
@@ -407,6 +413,7 @@ void *lpsm_arena_init(const char *main_file, const char *log_file,
/* All pages clean at this time */
memset(PM->pageinfo, page_clean, len_pages);
+ lpsm_need_checkpoint = 0;
sigact.sa_sigaction = lpsm_sigsegv;
sigemptyset(&sigact.sa_mask);
@@ -512,6 +519,9 @@ pid_t lpsm_checkpoint(double gc_factor, enum psmsync wait)
}
}
+ if ( !lpsm_need_checkpoint )
+ return 0; /* If not dirty, don't fork */
+
f = fork();
if ( f == (pid_t)-1 )
return (pid_t)-1; /* Checkpoint failed! */
@@ -522,7 +532,8 @@ pid_t lpsm_checkpoint(double gc_factor, enum psmsync wait)
array for a while. */
mprotect(PM->arena, PM->arena_len, PROT_READ);
memset(PM->pageinfo, page_clean, PM->arena_len >> PM->pageshift);
-
+ lpsm_need_checkpoint = 0;
+
PM->dirty_count = 0; /* No pages dirty */
PM->fork_seq++; /* Increase next sequence number */
diff --git a/lpsm.h b/lpsm.h
index d458f18..a9d6153 100644
--- a/lpsm.h
+++ b/lpsm.h
@@ -44,6 +44,7 @@ pid_t lpsm_checkpoint(double, enum psmsync);
int lpsm_extend(size_t);
void lpsm_shutdown(void);
int lpsm_recover(const char *, const char *);
+extern sig_atomic_t lpsm_need_checkpoint;
/* Arena management routines */
diff --git a/lpsm_arena_init.3.in b/lpsm_arena_init.3.in
index 138dde4..70b3f20 100644
--- a/lpsm_arena_init.3.in
+++ b/lpsm_arena_init.3.in
@@ -10,28 +10,22 @@
.\"
.\" -----------------------------------------------------------------------
.\" $Id$
-.TH LPSM_ARENA_INIT 3 "22 October 2001" "LPSM @@VERSION@@" "Linux Persistent Memory"
+.TH LPSM_ARENA_INIT 3 "25 October 2001" "LPSM @@VERSION@@" "Linux Persistent Memory"
.SH NAME
-lpsm_arena_init, lpsm_checkpoint, lpsm_extend, lpsm_shutdown \- Control persistent memory in unmanaged mode
+lpsm_arena_init \- Open persistent memory in unmanaged mode
.SH SYNOPSIS
.nf
.B #include <lpsm.h>
.sp
.BI "void *lpsm_arena_init(const char " "*datafile" ", const char " "*logfile" ", size_t *" "arena_size" ", void *" "arena_base" ");"
-.nl
-.BI "pid_t lpsm_checkpoint(double " "ratio" ", enum psmsync " "wait" ");"
-.nl
-.BI "int lpsm_extend(size_t" "newsize" ");"
-.nl
-.BI "void lpsm_shutdown(void);"
.fi
.SH DESCRIPTION
-These functions control a persistent memory arena in unmanaged mode.
-They provide an in-memory snapshot of the
+This function opens an LPSM persistent memory arena in unmanaged mode.
+It provides an in-memory snapshot of the
.I datafile
with commit semantics, using the
.I logfile
-to implement the commit semantics. These functions are not compatible
+to implement the commit semantics. This function is not compatible
with the use of
.B lpsm_malloc()
and its related functions.
@@ -56,119 +50,13 @@ If
is set, try to map the arena at that particular
base address. If arena_base is
.IR NULL ,
-use an architecture-specific default value.
-.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
-lpsm_extend()
-extends the size of the arena to
-.IR newsize .
-.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
-.in +.5i
-.sp
-lpsm_checkpoint(0.0 , PSMSYNC_SYNC);
-.nl
-lpsm_shutdown();
-.nl
-.fi
-.PP
-Calling
-.B lpsm_shutdown()
-followed by
-.B lpsm_arena_init()
-can be used in exceptional events to reinitialize the arena to the
-last checkpointed state. This is a very slow operation.
+use an architecture-specific default value. Only one arena can be
+opened at any one time.
.SH "RETURN VALUES"
.B lpsm_arena_init()
returns the pointer to the arena, 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.
-.B lpsm_extend()
-returns 0 on success and -1 on failure.
-.PP
-.B lpsm_shutdown()
-does not return a value.
.SH "ERRORS"
On failure,
.B lpsm_arena_init()
@@ -177,9 +65,9 @@ will set
to the appropriate value for the error that occurred.
.SH "SEE ALSO"
.BR lpsm_init (3),
-.BR lpsm_recover (3),
-.BR lpsm_malloc (3).
+.BR lpsm_checkpoint (3),
+.BR lpsm_extend (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.
diff --git a/lpsm_checkpoint.3.in b/lpsm_checkpoint.3.in
new file mode 100644
index 0000000..62356d2
--- /dev/null
+++ b/lpsm_checkpoint.3.in
@@ -0,0 +1,119 @@
+.\" -*- 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_CHECKPOINT 3 "25 October 2001" "LPSM @@VERSION@@" "Linux Persistent Memory"
+.SH NAME
+lpsm_checkpoint \- Checkpoint persistent memory
+.SH SYNOPSIS
+.nf
+.B #include <lpsm.h>
+.sp
+.BI "extern sig_atomic_t " lpsm_need_checkpoint ";"
+.nl
+.BI "pid_t lpsm_checkpoint(double " ratio ", enum psmsync " wait ");"
+.fi
+.SH DESCRIPTION
+.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
+The external variable
+.B lpsm_need_checkpoint
+can be used to determine if there is currently any checkpointable
+changes to persistent memory. It is set to 0 on initialization and on
+checkpoint, and set to 1 when persistent memory is modified.
+.SH "RETURN VALUES"
+.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"
+Due to the asynchronous nature of
+.BR lpsm_checkpoint() ,
+.I errno
+cannot be relied upon to contain meaningful information on error.
+.SH "SEE ALSO"
+.BR lpsm_init (3),
+.BR lpsm_arena_init (3),
+.BR lpsm_shutdown (3).
+.SH "BUGS"
+Failures within the checkpoint process are currently not handled
+very gracefully.
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.
diff --git a/lpsm_shutdown.3.in b/lpsm_shutdown.3.in
new file mode 100644
index 0000000..772e60d
--- /dev/null
+++ b/lpsm_shutdown.3.in
@@ -0,0 +1,55 @@
+.\" -*- 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_SHUTDOWN 3 "25 October 2001" "LPSM @@VERSION@@" "Linux Persistent Memory"
+.SH NAME
+lpsm_shutdown \- Terminate access to persistent memory
+.SH SYNOPSIS
+.nf
+.B #include <lpsm.h>
+.sp
+.BI "void lpsm_shutdown(void);"
+.fi
+.SH DESCRIPTION
+.B lpsm_shutdown()
+shuts down the LPSM 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()
+or
+.BR lpsm_arena_init() ,
+as appropriate, 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_shutdown()
+does not return a value.
+.SH "SEE ALSO"
+.BR lpsm_init (3),
+.BR lpsm_arena_init (3).
+.SH BUGS
+The persistent memory system is not currently thread-safe.