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
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
<!-- doc/src/sgml/generic-wal.sgml -->
<chapter id="generic-wal">
<title>Generic WAL Records</title>
<para>
Although all built-in WAL-logged modules have their own types of WAL
records, there is also a generic WAL record type, which describes changes
to pages in a generic way. This is useful for extensions that provide
custom access methods.
</para>
<para>
In comparison with <link linkend="custom-rmgr">Custom WAL Resource
Managers</link>, Generic WAL is simpler for an extension to implement and
does not require the extension library to be loaded in order to apply the
records.
</para>
<note>
<para>
Generic WAL records are ignored during <link
linkend="logicaldecoding">Logical Decoding</link>. If logical decoding is
required for your extension, consider a Custom WAL Resource Manager.
</para>
</note>
<para>
The API for constructing generic WAL records is defined in
<filename>access/generic_xlog.h</filename> and implemented
in <filename>access/transam/generic_xlog.c</filename>.
</para>
<para>
To perform a WAL-logged data update using the generic WAL record
facility, follow these steps:
<orderedlist>
<listitem>
<para>
<function>state = GenericXLogStart(relation)</function> — start
construction of a generic WAL record for the given relation.
</para>
</listitem>
<listitem>
<para>
<function>page = GenericXLogRegisterBuffer(state, buffer, flags)</function>
— register a buffer to be modified within the current generic WAL
record. This function returns a pointer to a temporary copy of the
buffer's page, where modifications should be made. (Do not modify the
buffer's contents directly.) The third argument is a bit mask of flags
applicable to the operation. Currently the only such flag is
<literal>GENERIC_XLOG_FULL_IMAGE</literal>, which indicates that a full-page
image rather than a delta update should be included in the WAL record.
Typically this flag would be set if the page is new or has been
rewritten completely.
<function>GenericXLogRegisterBuffer</function> can be repeated if the
WAL-logged action needs to modify multiple pages.
</para>
</listitem>
<listitem>
<para>
Apply modifications to the page images obtained in the previous step.
</para>
</listitem>
<listitem>
<para>
<function>GenericXLogFinish(state)</function> — apply the changes to
the buffers and emit the generic WAL record.
</para>
</listitem>
</orderedlist>
</para>
<para>
WAL record construction can be canceled between any of the above steps by
calling <function>GenericXLogAbort(state)</function>. This will discard all
changes to the page image copies.
</para>
<para>
Please note the following points when using the generic WAL record
facility:
<itemizedlist>
<listitem>
<para>
No direct modifications of buffers are allowed! All modifications must
be done in copies acquired from <function>GenericXLogRegisterBuffer()</function>.
In other words, code that makes generic WAL records should never call
<function>BufferGetPage()</function> for itself. However, it remains the
caller's responsibility to pin/unpin and lock/unlock the buffers at
appropriate times. Exclusive lock must be held on each target buffer
from before <function>GenericXLogRegisterBuffer()</function> until after
<function>GenericXLogFinish()</function>.
</para>
</listitem>
<listitem>
<para>
Registrations of buffers (step 2) and modifications of page images
(step 3) can be mixed freely, i.e., both steps may be repeated in any
sequence. Keep in mind that buffers should be registered in the same
order in which locks are to be obtained on them during replay.
</para>
</listitem>
<listitem>
<para>
The maximum number of buffers that can be registered for a generic WAL
record is <literal>MAX_GENERIC_XLOG_PAGES</literal>. An error will be thrown
if this limit is exceeded.
</para>
</listitem>
<listitem>
<para>
Generic WAL assumes that the pages to be modified have standard
layout, and in particular that there is no useful data between
<structfield>pd_lower</structfield> and <structfield>pd_upper</structfield>.
</para>
</listitem>
<listitem>
<para>
Since you are modifying copies of buffer
pages, <function>GenericXLogStart()</function> does not start a critical
section. Thus, you can safely do memory allocation, error throwing,
etc. between <function>GenericXLogStart()</function> and
<function>GenericXLogFinish()</function>. The only actual critical section is
present inside <function>GenericXLogFinish()</function>. There is no need to
worry about calling <function>GenericXLogAbort()</function> during an error
exit, either.
</para>
</listitem>
<listitem>
<para>
<function>GenericXLogFinish()</function> takes care of marking buffers dirty
and setting their LSNs. You do not need to do this explicitly.
</para>
</listitem>
<listitem>
<para>
For unlogged relations, everything works the same except that no
actual WAL record is emitted. Thus, you typically do not need to do
any explicit checks for unlogged relations.
</para>
</listitem>
<listitem>
<para>
The generic WAL redo function will acquire exclusive locks to buffers
in the same order as they were registered. After redoing all changes,
the locks will be released in the same order.
</para>
</listitem>
<listitem>
<para>
If <literal>GENERIC_XLOG_FULL_IMAGE</literal> is not specified for a
registered buffer, the generic WAL record contains a delta between
the old and the new page images. This delta is based on byte-by-byte
comparison. This is not very compact for the case of moving data
within a page, and might be improved in the future.
</para>
</listitem>
</itemizedlist>
</para>
</chapter>
|
