summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorH. Peter Anvin <hpa@zytor.com>2001-10-23 04:56:49 (GMT)
committerH. Peter Anvin <hpa@zytor.com>2001-10-23 04:56:49 (GMT)
commit03615bdc63d821a8885cda7637701619a8d61ab2 (patch)
tree21d187e51333d9bae6058fdf5e80320855fad5b3
parent7f292cecee3b603b5e1ccea57da0ba59dc113f3c (diff)
downloadlpsm-03615bdc63d821a8885cda7637701619a8d61ab2.zip
lpsm-03615bdc63d821a8885cda7637701619a8d61ab2.tar.gz
lpsm-03615bdc63d821a8885cda7637701619a8d61ab2.tar.bz2
lpsm-03615bdc63d821a8885cda7637701619a8d61ab2.tar.xz
Add man pageslpsm-0.1.4
-rw-r--r--Makefile17
-rw-r--r--lpsm_arena_init.3.in176
-rw-r--r--lpsm_init.3.in156
-rw-r--r--lpsm_malloc.3.in144
4 files changed, 490 insertions, 3 deletions
diff --git a/Makefile b/Makefile
index 61b2243..d3ac6ae 100644
--- a/Makefile
+++ b/Makefile
@@ -7,6 +7,7 @@ CFILES = arena.c bitops.c \
mgmt.c malloc.c free.c realloc.c zalloc.c calloc.c stats.c
OSOBJ = $(patsubst %.c,%.o,$(CFILES))
OSPICOBJ = $(patsubst %.c,%.pic.o,$(CFILES))
+MANPAGES = $(patsubst %.in,%,$(wildcard *.[1-9].in))
CC = gcc
# This is a reasonable set of flags for production
@@ -35,7 +36,11 @@ man1dir = $(mandir)/man1
man3dir = $(mandir)/man3
-all: $(LIBPSM) $(TEST)
+all: $(LIBPSM) test man
+
+test: $(TEST)
+
+man: $(MANPAGES)
clean:
rm -f *.o *~ core *.dat *.log $(LIBPSM) $(TEST)
@@ -45,11 +50,14 @@ distclean: clean
rm -f *~ \#* .depend
install: all
- mkdir -p $(INSTALLROOT)$(includedir) $(INSTALLROOT)$(libdir)
- $(INSTALL) lpsm.h $(INSTALLROOT)$(includedir)
+ mkdir -p $(INSTALLROOT)$(includedir)
+ mkdir -p $(INSTALLROOT)$(libdir)
+ mkdir -p $(INSTALLROOT)$(man3dir)
$(INSTALL) $(LIBPSM) $(INSTALLROOT)$(libdir)
cd $(INSTALLROOT)$(libdir) && ln -sf libpsm.so.$(VERSION) $(SONAME)
cd $(INSTALLROOT)$(libdir) && ln -sf libpsm.so.$(VERSION) libpsm.so
+ $(INSTALL) lpsm.h $(INSTALLROOT)$(includedir)
+ $(INSTALL) $(MANPAGES) $(INSTALLROOT)$(man3dir)
ldconfig
%.o: %.c
@@ -58,6 +66,9 @@ install: all
%.pic.o: %.c
$(CC) $(PICFLAGS) -o $@ -c $<
+%: %.in
+ sed -e 's/@@VERSION@@/$(VERSION)/g' < $< > $@
+
libpsm.so.$(VERSION): $(OSPICOBJ)
$(CC) $(SOFLAGS) -Wl,-soname,$(SONAME) -o libpsm.so.$(VERSION) $(OSPICOBJ)
ln -sf libpsm.so.$(VERSION) $(SONAME)
diff --git a/lpsm_arena_init.3.in b/lpsm_arena_init.3.in
new file mode 100644
index 0000000..9d1a0ac
--- /dev/null
+++ b/lpsm_arena_init.3.in
@@ -0,0 +1,176 @@
+.\" -*- 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_ARENA_INIT 3 "22 October 2001" "LPSM @@VERSION@@" "Linux Persistent Memory"
+.SH NAME
+lpsm_arena_init, lpsm_checkpoint, lpsm_extend, lpsm_shutdown \- Control 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 pmsync " "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
+.I datafile
+with commit semantics, using the
+.I logfile
+to implement the commit semantics. These functions are not compatible
+with the use of
+.B lpsm_malloc()
+and its related functions.
+.PP
+.B lpsm_arena_init()
+opens the persistent memory arena that consists of the two
+files
+.I datafile
+and
+.IR logfile .
+If these files don't exist, they are created. The argument
+.I arena_size
+contains the minimum size of the arena (if smaller, it will be resized
+to this size.) On exit, it contains the actual size of the arena.
+.PP
+It returns a pointer to the arena, or
+.B NULL
+on error.
+.PP
+If
+.I arena_base
+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.
+.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 "SEE ALSO"
+.BR lpsm_init (3),
+.BR lpsm_malloc (3).
+.SH BUGS
+Checkpointing failures are currently not handled gracefully.
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.
diff --git a/lpsm_malloc.3.in b/lpsm_malloc.3.in
new file mode 100644
index 0000000..726b5a6
--- /dev/null
+++ b/lpsm_malloc.3.in
@@ -0,0 +1,144 @@
+.\" -*- 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_MALLOC 3 "22 October 2001" "LPSM @@VERSION@@" "Linux Persistent Memory"
+.SH NAME
+lpsm_malloc, lpsm_free, lpsm_realloc, lpsm_zalloc, lpsm_calloc \- Allocate and free persistent memory
+.SH SYNOPSIS
+.nf
+.B #include <lpsm.h>
+.sp
+.BI "void *lpsm_malloc(size_t " "size" ");"
+.nl
+.BI "void lpsm_free(void " "*ptr" ");"
+.nl
+.BI "void *lpsm_realloc(void " "*ptr" ", size_t " "size" ");"
+.nl
+.BI "void *lpsm_zalloc(size_t " "size" ");"
+.nl
+.BI "void *lpsm_calloc(size_t " "nmemb" ", size_t " "size" ");"
+.nl
+.fi
+.SH DESCRIPTION
+These functions allocate persistent memory. A persistent memory arena
+needs to be initialized with
+.B lpsm_init()
+before these functions can be called; it is subsequently managed via
+.B lpsm_checkpoint()
+and
+.BR lpsm_shutdown() .
+.PP
+.B lpsm_malloc()
+allocates
+.I size
+bytes and returns a pointer to the allocated memory.
+The memory is not cleared.
+.PP
+.B lpsm_free()
+frees the memory space pointed to by
+.IR ptr ,
+which must have been returned by a previous call to
+.BR lpsm_malloc() ,
+.B lpsm_calloc()
+or
+.BR lpsm_realloc() .
+Otherwise, or if
+.BI "lpsm_free(" "ptr" )
+has already been called before, undefined behaviour occurs.
+If
+.I ptr
+is
+.BR NULL ,
+no operation is performed.
+.PP
+.B lpsm_realloc()
+changes the size of the memory block pointed to by
+.I ptr
+to
+.I size
+bytes.
+The contents will be unchanged to the minimum of the old and new sizes;
+newly allocated memory will be uninitialized.
+If
+.I ptr
+is
+.BR NULL ,
+the call is equivalent to
+\fBlpsm_malloc(\fP\fIsize\fP\fB)\fP;
+if size is equal to zero,
+the call is equivalent to
+.BI "lpsm_free(" "ptr" ) .
+Unless
+.I ptr
+is
+.BR NULL ,
+it must have been returned by an earlier call to
+.BR lpsm_malloc() ,
+.BR lpsm_calloc()
+or
+.BR lpsm_realloc() .
+.SH "RETURN VALUES"
+For
+.BR lpsm_calloc() " and " lpsm_malloc() ,
+the value returned is a pointer to the allocated memory, which is suitably
+aligned for any kind of variable, or
+.B NULL
+if the request fails.
+.PP
+.B lpsm_free()
+returns no value.
+.PP
+.B lpsm_realloc()
+returns a pointer to the newly allocated memory, which is suitably
+aligned for any kind of variable and may be different from
+.IR ptr ,
+or
+.B NULL
+if the request fails or if size was equal to 0. If
+.B lpsm_realloc()
+fails the original block is left untouched - it is not freed or moved.
+.PP
+.B lpsm_zalloc()
+allocates
+.I size
+bytes and returns a pointer to the allocated memory.
+The memory is set to zero.
+.PP
+.B lpsm_calloc()
+allocates memory for an array of
+.I nmemb
+elements of
+.I size
+bytes each and returns a pointer to the allocated memory.
+The memory is set to zero. This is functionally equivalent to
+\fBlpsm_zalloc(\fP\fInmemb\fP\fB*\fP\fIsize\fP\fB)\fP .
+.PP
+.SH "CONFORMING TO"
+These functions mimic in as much as possible the ISO C and POSIX
+behaviour of the equivalent transient memory allocation functions.
+.SH "SEE ALSO"
+.BR malloc (3),
+.BR lpsm_init (3).
+.SH NOTES
+The allocator used can handle allocations down to single byte size
+with high efficiency. Large allocations are rounded to the nearest
+higher power of two.
+.SH BUGS
+The allocator used is very sensitive to invalid pointers passed to
+.B lpsm_free()
+or
+.BR lpsm_realloc() .
+Passing a bad pointer to one of these functions is very likely to
+result in data loss.
+.PP
+.B lpsm_calloc()
+does not check for multiplication overflow.