diff options
| -rw-r--r-- | CHANGES | 5 | ||||
| -rw-r--r-- | Makefile | 8 | ||||
| -rw-r--r-- | arena.c | 13 | ||||
| -rw-r--r-- | lpsm.h | 1 | ||||
| -rw-r--r-- | lpsm_arena_init.3.in | 134 | ||||
| -rw-r--r-- | lpsm_checkpoint.3.in | 119 | ||||
| -rw-r--r-- | lpsm_init.3.in | 118 | ||||
| -rw-r--r-- | lpsm_shutdown.3.in | 55 |
8 files changed, 212 insertions, 241 deletions
@@ -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() @@ -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 @@ -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 */ @@ -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. |