summaryrefslogtreecommitdiffstats
path: root/lpsm_checkpoint.3.in
blob: 9cb94c339c911034cab1c0c4348b8054459d34c0 (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
115
116
.\" -*- nroff -*- ---------------------------------------------------------
.\"   
.\"   Copyright 2001-2008 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.
.\"
.\" -----------------------------------------------------------------------
.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.
.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),
.BR lpsm (7).
.SH "BUGS"
Failures within the checkpoint process are currently not handled
very gracefully.