aboutsummaryrefslogtreecommitdiffstats
path: root/lpsm.7.in
blob: 683fa5edc1cdd398fc2343d35889507a977b2cd0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
.\" -*- 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 7 "25 October 2001" "@@VERSION@@" "Linux Persistent Memory"
.SH "NAME"
lpsm \- A persistent memory library for Linux
.SH "DESCRIPTION"
LPSM is a C library with a simple interface that manages a segment of
memory backed by a persistent file. LPSM differs from ordinary
.B mmap()
in two ways: it can optionally offer heap management
(malloc/free/realloc) within the arena, and, more importantly, a
transaction log is used to ensure the consistency of the persistent
representation. The application notifies LPSM whenever the arena is in
a consistent state, suitable for checkpointing. If the application or
system crashes, the arena will always be recovered to a consistent
checkpoint.
.SH "USAGE"
An LPSM database consists of two files, the
.IR datafile ,
which contains the bulk storage, and the
.IR logfile ,
which contains the recent changes.  The logfile is constructed in such
a way that data loss is unlikely.
.PP
In
.IR "unmanaged mode" ,
the contents of the mapped memory is simply the contents of the
datafile, quite similarly to the way a file can be mapped into memory
by
.BR mmap() .
However, unlike
.BR mmap() ,
the application can use
.B lpsm_checkpoint()
to control when it is safe for data to get written back to the data
store.  In that way, it provides a combination of the semantics
offered by the
.B MAP_SHARED
and
.B MAP_PRIVATE
options to
.BR mmap() .
.PP
In
.IR "managed mode" ,
the contents of the data store is managed in a way very similar to the
way conventional memory is managed by
.B malloc()
and its associated functions.
.PP
It is expected that most applications will use managed mode.
.SH "FUNCTIONS USED IN UNMANAGED MODE"
In unmanaged mode, a data store is opened with
.BR lpsm_arena_init() .
The function
.B lpsm_checkpoint()
is called to checkpoint,
.B lpsm_extend() 
to increase the size of the memory arena, and
.B lpsm_shutdown()
to close the data store.  The function
.B lpsm_recover()
can be called to do offline log recovery, i.e. bring the
.I datafile
fully up to date with the contents of the data store and truncate the
.I logfile
to its minimum size.
.SH "FUNCTIONS USED IN MANAGED MODE"
In managed mode, a data store is opened with
.BR lpsm_init() .
The functions
.BR lpsm_malloc() ,
.BR lpsm_free() ,
.BR lpsm_realloc() ,
.BR lpsm_zalloc() ,
and
.B lpsm_calloc()
provide memory management very similar to the equivalent conventional
memory functions
.RB ( lpsm_zalloc()
is similar to
.B calloc()
but with a different interface.)
The function
.B lpsm_alloc_stats()
provide extended statistics on the memory allocation.
As in unmanaged mode,
.B lpsm_checkpoint()
is used to checkpoint the data store, and
.B lpsm_shutdown()
to close.  As with unmanaged mode,
.B lpsm_recover()
can be used to do offline log recovery.
.SH "SEE ALSO"
.BR lpsm_init (3),
.BR lpsm_malloc (3),
.BR lpsm_alloc_stats (3),
.BR lpsm_arena_init (3),
.BR lpsm_extend (3),
.BR lpsm_checkpoint (3),
.BR lpsm_shutdown (3),
.BR lpsm_recover (3),
.BR mmap (2),
.BR malloc (3).