Branch data Line data Source code
1 : : /*-------------------------------------------------------------------------
2 : : *
3 : : * xlogreader.h
4 : : * Definitions for the generic XLog reading facility
5 : : *
6 : : * Portions Copyright (c) 2013-2026, PostgreSQL Global Development Group
7 : : *
8 : : * IDENTIFICATION
9 : : * src/include/access/xlogreader.h
10 : : *
11 : : * NOTES
12 : : * See the definition of the XLogReaderState struct for instructions on
13 : : * how to use the XLogReader infrastructure.
14 : : *
15 : : * The basic idea is to allocate an XLogReaderState via
16 : : * XLogReaderAllocate(), position the reader to the first record with
17 : : * XLogBeginRead() or XLogFindNextRecord(), and call XLogReadRecord()
18 : : * until it returns NULL.
19 : : *
20 : : * Callers supply a page_read callback if they want to call
21 : : * XLogReadRecord or XLogFindNextRecord; it can be passed in as NULL
22 : : * otherwise. The WALRead function can be used as a helper to write
23 : : * page_read callbacks, but it is not mandatory; callers that use it,
24 : : * must supply segment_open callbacks. The segment_close callback
25 : : * must always be supplied.
26 : : *
27 : : * After reading a record with XLogReadRecord(), it's decomposed into
28 : : * the per-block and main data parts, and the parts can be accessed
29 : : * with the XLogRec* macros and functions. You can also decode a
30 : : * record that's already constructed in memory, without reading from
31 : : * disk, by calling the DecodeXLogRecord() function.
32 : : *-------------------------------------------------------------------------
33 : : */
34 : : #ifndef XLOGREADER_H
35 : : #define XLOGREADER_H
36 : :
37 : : #ifndef FRONTEND
38 : : #include "access/transam.h"
39 : : #endif
40 : :
41 : : #include "access/xlogrecord.h"
42 : : #include "storage/buf.h"
43 : :
44 : : /* WALOpenSegment represents a WAL segment being read. */
45 : : typedef struct WALOpenSegment
46 : : {
47 : : int ws_file; /* segment file descriptor */
48 : : XLogSegNo ws_segno; /* segment number */
49 : : TimeLineID ws_tli; /* timeline ID of the currently open file */
50 : : } WALOpenSegment;
51 : :
52 : : /* WALSegmentContext carries context information about WAL segments to read */
53 : : typedef struct WALSegmentContext
54 : : {
55 : : char ws_dir[MAXPGPATH];
56 : : int ws_segsize;
57 : : } WALSegmentContext;
58 : :
59 : : typedef struct XLogReaderState XLogReaderState;
60 : :
61 : : /* Function type definitions for various xlogreader interactions */
62 : : typedef int (*XLogPageReadCB) (XLogReaderState *xlogreader,
63 : : XLogRecPtr targetPagePtr,
64 : : int reqLen,
65 : : XLogRecPtr targetRecPtr,
66 : : char *readBuf);
67 : : typedef void (*WALSegmentOpenCB) (XLogReaderState *xlogreader,
68 : : XLogSegNo nextSegNo,
69 : : TimeLineID *tli_p);
70 : : typedef void (*WALSegmentCloseCB) (XLogReaderState *xlogreader);
71 : :
72 : : typedef struct XLogReaderRoutine
73 : : {
74 : : /*
75 : : * Data input callback
76 : : *
77 : : * This callback shall read at least reqLen valid bytes of the xlog page
78 : : * starting at targetPagePtr, and store them in readBuf. The callback
79 : : * shall return the number of bytes read (never more than XLOG_BLCKSZ), or
80 : : * -1 on failure. The callback shall sleep, if necessary, to wait for the
81 : : * requested bytes to become available. The callback will not be invoked
82 : : * again for the same page unless more than the returned number of bytes
83 : : * are needed.
84 : : *
85 : : * targetRecPtr is the position of the WAL record we're reading. Usually
86 : : * it is equal to targetPagePtr + reqLen, but sometimes xlogreader needs
87 : : * to read and verify the page or segment header, before it reads the
88 : : * actual WAL record it's interested in. In that case, targetRecPtr can
89 : : * be used to determine which timeline to read the page from.
90 : : *
91 : : * The callback shall set ->seg.ws_tli to the TLI of the file the page was
92 : : * read from.
93 : : */
94 : : XLogPageReadCB page_read;
95 : :
96 : : /*
97 : : * Callback to open the specified WAL segment for reading. ->seg.ws_file
98 : : * shall be set to the file descriptor of the opened segment. In case of
99 : : * failure, an error shall be raised by the callback and it shall not
100 : : * return.
101 : : *
102 : : * "nextSegNo" is the number of the segment to be opened.
103 : : *
104 : : * "tli_p" is an input/output argument. WALRead() uses it to pass the
105 : : * timeline in which the new segment should be found, but the callback can
106 : : * use it to return the TLI that it actually opened.
107 : : */
108 : : WALSegmentOpenCB segment_open;
109 : :
110 : : /*
111 : : * WAL segment close callback. ->seg.ws_file shall be set to a negative
112 : : * number.
113 : : */
114 : : WALSegmentCloseCB segment_close;
115 : : } XLogReaderRoutine;
116 : :
117 : : #define XL_ROUTINE(...) &(XLogReaderRoutine){__VA_ARGS__}
118 : :
119 : : typedef struct
120 : : {
121 : : /* Is this block ref in use? */
122 : : bool in_use;
123 : :
124 : : /* Identify the block this refers to */
125 : : RelFileLocator rlocator;
126 : : ForkNumber forknum;
127 : : BlockNumber blkno;
128 : :
129 : : /* Prefetching workspace. */
130 : : Buffer prefetch_buffer;
131 : :
132 : : /* copy of the fork_flags field from the XLogRecordBlockHeader */
133 : : uint8 flags;
134 : :
135 : : /* Information on full-page image, if any */
136 : : bool has_image; /* has image, even for consistency checking */
137 : : bool apply_image; /* has image that should be restored */
138 : : char *bkp_image;
139 : : uint16 hole_offset;
140 : : uint16 hole_length;
141 : : uint16 bimg_len;
142 : : uint8 bimg_info;
143 : :
144 : : /* Buffer holding the rmgr-specific data associated with this block */
145 : : bool has_data;
146 : : char *data;
147 : : uint16 data_len;
148 : : } DecodedBkpBlock;
149 : :
150 : : /*
151 : : * The decoded contents of a record. This occupies a contiguous region of
152 : : * memory, with main_data and blocks[n].data pointing to memory after the
153 : : * members declared here.
154 : : */
155 : : typedef struct DecodedXLogRecord
156 : : {
157 : : /* Private member used for resource management. */
158 : : size_t size; /* total size of decoded record */
159 : : bool oversized; /* outside the regular decode buffer? */
160 : : struct DecodedXLogRecord *next; /* decoded record queue link */
161 : :
162 : : /* Public members. */
163 : : XLogRecPtr lsn; /* location */
164 : : XLogRecPtr next_lsn; /* location of next record */
165 : : XLogRecord header; /* header */
166 : : RepOriginId record_origin;
167 : : TransactionId toplevel_xid; /* XID of top-level transaction */
168 : : char *main_data; /* record's main data portion */
169 : : uint32 main_data_len; /* main data portion's length */
170 : : int max_block_id; /* highest block_id in use (-1 if none) */
171 : : DecodedBkpBlock blocks[FLEXIBLE_ARRAY_MEMBER];
172 : : } DecodedXLogRecord;
173 : :
174 : : struct XLogReaderState
175 : : {
176 : : /*
177 : : * Operational callbacks
178 : : */
179 : : XLogReaderRoutine routine;
180 : :
181 : : /* ----------------------------------------
182 : : * Public parameters
183 : : * ----------------------------------------
184 : : */
185 : :
186 : : /*
187 : : * System identifier of the xlog files we're about to read. Set to zero
188 : : * (the default value) if unknown or unimportant.
189 : : */
190 : : uint64 system_identifier;
191 : :
192 : : /*
193 : : * Opaque data for callbacks to use. Not used by XLogReader.
194 : : */
195 : : void *private_data;
196 : :
197 : : /*
198 : : * Start and end point of last record read. EndRecPtr is also used as the
199 : : * position to read next. Calling XLogBeginRead() sets EndRecPtr to the
200 : : * starting position and ReadRecPtr to invalid.
201 : : *
202 : : * Start and end point of last record returned by XLogReadRecord(). These
203 : : * are also available as record->lsn and record->next_lsn.
204 : : */
205 : : XLogRecPtr ReadRecPtr; /* start of last record read */
206 : : XLogRecPtr EndRecPtr; /* end+1 of last record read */
207 : :
208 : : /*
209 : : * Set at the end of recovery: the start point of a partial record at the
210 : : * end of WAL (InvalidXLogRecPtr if there wasn't one), and the start
211 : : * location of its first contrecord that went missing.
212 : : */
213 : : XLogRecPtr abortedRecPtr;
214 : : XLogRecPtr missingContrecPtr;
215 : : /* Set when XLP_FIRST_IS_OVERWRITE_CONTRECORD is found */
216 : : XLogRecPtr overwrittenRecPtr;
217 : :
218 : :
219 : : /* ----------------------------------------
220 : : * Decoded representation of current record
221 : : *
222 : : * Use XLogRecGet* functions to investigate the record; these fields
223 : : * should not be accessed directly.
224 : : * ----------------------------------------
225 : : * Start and end point of the last record read and decoded by
226 : : * XLogReadRecord(). NextRecPtr is also used as the position to decode
227 : : * next. Calling XLogBeginRead() sets NextRecPtr and EndRecPtr to the
228 : : * requested starting position.
229 : : */
230 : : XLogRecPtr DecodeRecPtr; /* start of last record decoded */
231 : : XLogRecPtr NextRecPtr; /* end+1 of last record decoded */
232 : : XLogRecPtr PrevRecPtr; /* start of previous record decoded */
233 : :
234 : : /* Last record returned by XLogReadRecord(). */
235 : : DecodedXLogRecord *record;
236 : :
237 : : /* ----------------------------------------
238 : : * private/internal state
239 : : * ----------------------------------------
240 : : */
241 : :
242 : : /*
243 : : * Buffer for decoded records. This is a circular buffer, though
244 : : * individual records can't be split in the middle, so some space is often
245 : : * wasted at the end. Oversized records that don't fit in this space are
246 : : * allocated separately.
247 : : */
248 : : char *decode_buffer;
249 : : size_t decode_buffer_size;
250 : : bool free_decode_buffer; /* need to free? */
251 : : char *decode_buffer_head; /* data is read from the head */
252 : : char *decode_buffer_tail; /* new data is written at the tail */
253 : :
254 : : /*
255 : : * Queue of records that have been decoded. This is a linked list that
256 : : * usually consists of consecutive records in decode_buffer, but may also
257 : : * contain oversized records allocated with palloc().
258 : : */
259 : : DecodedXLogRecord *decode_queue_head; /* oldest decoded record */
260 : : DecodedXLogRecord *decode_queue_tail; /* newest decoded record */
261 : :
262 : : /*
263 : : * Buffer for currently read page (XLOG_BLCKSZ bytes, valid up to at least
264 : : * readLen bytes)
265 : : */
266 : : char *readBuf;
267 : : uint32 readLen;
268 : :
269 : : /* last read XLOG position for data currently in readBuf */
270 : : WALSegmentContext segcxt;
271 : : WALOpenSegment seg;
272 : : uint32 segoff;
273 : :
274 : : /*
275 : : * beginning of prior page read, and its TLI. Doesn't necessarily
276 : : * correspond to what's in readBuf; used for timeline sanity checks.
277 : : */
278 : : XLogRecPtr latestPagePtr;
279 : : TimeLineID latestPageTLI;
280 : :
281 : : /* beginning of the WAL record being read. */
282 : : XLogRecPtr currRecPtr;
283 : : /* timeline to read it from, 0 if a lookup is required */
284 : : TimeLineID currTLI;
285 : :
286 : : /*
287 : : * Safe point to read to in currTLI if current TLI is historical
288 : : * (tliSwitchPoint) or InvalidXLogRecPtr if on current timeline.
289 : : *
290 : : * Actually set to the start of the segment containing the timeline switch
291 : : * that ends currTLI's validity, not the LSN of the switch its self, since
292 : : * we can't assume the old segment will be present.
293 : : */
294 : : XLogRecPtr currTLIValidUntil;
295 : :
296 : : /*
297 : : * If currTLI is not the most recent known timeline, the next timeline to
298 : : * read from when currTLIValidUntil is reached.
299 : : */
300 : : TimeLineID nextTLI;
301 : :
302 : : /*
303 : : * Buffer for current ReadRecord result (expandable), used when a record
304 : : * crosses a page boundary.
305 : : */
306 : : char *readRecordBuf;
307 : : uint32 readRecordBufSize;
308 : :
309 : : /* Buffer to hold error message */
310 : : char *errormsg_buf;
311 : : bool errormsg_deferred;
312 : :
313 : : /*
314 : : * Flag to indicate to XLogPageReadCB that it should not block waiting for
315 : : * data.
316 : : */
317 : : bool nonblocking;
318 : : };
319 : :
320 : : /*
321 : : * Check if XLogNextRecord() has any more queued records or an error to return.
322 : : */
323 : : static inline bool
324 : 16 : XLogReaderHasQueuedRecordOrError(XLogReaderState *state)
325 : : {
326 [ + + ]: 16 : return (state->decode_queue_head != NULL) || state->errormsg_deferred;
327 : : }
328 : :
329 : : /* Get a new XLogReader */
330 : : extern XLogReaderState *XLogReaderAllocate(int wal_segment_size,
331 : : const char *waldir,
332 : : XLogReaderRoutine *routine,
333 : : void *private_data);
334 : :
335 : : /* Free an XLogReader */
336 : : extern void XLogReaderFree(XLogReaderState *state);
337 : :
338 : : /* Optionally provide a circular decoding buffer to allow readahead. */
339 : : extern void XLogReaderSetDecodeBuffer(XLogReaderState *state,
340 : : void *buffer,
341 : : size_t size);
342 : :
343 : : /* Position the XLogReader to given record */
344 : : extern void XLogBeginRead(XLogReaderState *state, XLogRecPtr RecPtr);
345 : : extern XLogRecPtr XLogFindNextRecord(XLogReaderState *state, XLogRecPtr RecPtr);
346 : :
347 : : /* Return values from XLogPageReadCB. */
348 : : typedef enum XLogPageReadResult
349 : : {
350 : : XLREAD_SUCCESS = 0, /* record is successfully read */
351 : : XLREAD_FAIL = -1, /* failed during reading a record */
352 : : XLREAD_WOULDBLOCK = -2, /* nonblocking mode only, no data */
353 : : } XLogPageReadResult;
354 : :
355 : : /* Read the next XLog record. Returns NULL on end-of-WAL or failure */
356 : : extern struct XLogRecord *XLogReadRecord(XLogReaderState *state,
357 : : char **errormsg);
358 : :
359 : : /* Consume the next record or error. */
360 : : extern DecodedXLogRecord *XLogNextRecord(XLogReaderState *state,
361 : : char **errormsg);
362 : :
363 : : /* Release the previously returned record, if necessary. */
364 : : extern XLogRecPtr XLogReleasePreviousRecord(XLogReaderState *state);
365 : :
366 : : /* Try to read ahead, if there is data and space. */
367 : : extern DecodedXLogRecord *XLogReadAhead(XLogReaderState *state,
368 : : bool nonblocking);
369 : :
370 : : /* Validate a page */
371 : : extern bool XLogReaderValidatePageHeader(XLogReaderState *state,
372 : : XLogRecPtr recptr, char *phdr);
373 : :
374 : : /* Forget error produced by XLogReaderValidatePageHeader(). */
375 : : extern void XLogReaderResetError(XLogReaderState *state);
376 : :
377 : : /*
378 : : * Error information from WALRead that both backend and frontend caller can
379 : : * process. Currently only errors from pg_pread can be reported.
380 : : */
381 : : typedef struct WALReadError
382 : : {
383 : : int wre_errno; /* errno set by the last pg_pread() */
384 : : int wre_off; /* Offset we tried to read from. */
385 : : int wre_req; /* Bytes requested to be read. */
386 : : int wre_read; /* Bytes read by the last read(). */
387 : : WALOpenSegment wre_seg; /* Segment we tried to read from. */
388 : : } WALReadError;
389 : :
390 : : extern bool WALRead(XLogReaderState *state,
391 : : char *buf, XLogRecPtr startptr, Size count,
392 : : TimeLineID tli, WALReadError *errinfo);
393 : :
394 : : /* Functions for decoding an XLogRecord */
395 : :
396 : : extern size_t DecodeXLogRecordRequiredSpace(size_t xl_tot_len);
397 : : extern bool DecodeXLogRecord(XLogReaderState *state,
398 : : DecodedXLogRecord *decoded,
399 : : XLogRecord *record,
400 : : XLogRecPtr lsn,
401 : : char **errormsg);
402 : :
403 : : /*
404 : : * Macros that provide access to parts of the record most recently returned by
405 : : * XLogReadRecord() or XLogNextRecord().
406 : : */
407 : : #define XLogRecGetTotalLen(decoder) ((decoder)->record->header.xl_tot_len)
408 : : #define XLogRecGetPrev(decoder) ((decoder)->record->header.xl_prev)
409 : : #define XLogRecGetInfo(decoder) ((decoder)->record->header.xl_info)
410 : : #define XLogRecGetRmid(decoder) ((decoder)->record->header.xl_rmid)
411 : : #define XLogRecGetXid(decoder) ((decoder)->record->header.xl_xid)
412 : : #define XLogRecGetOrigin(decoder) ((decoder)->record->record_origin)
413 : : #define XLogRecGetTopXid(decoder) ((decoder)->record->toplevel_xid)
414 : : #define XLogRecGetData(decoder) ((decoder)->record->main_data)
415 : : #define XLogRecGetDataLen(decoder) ((decoder)->record->main_data_len)
416 : : #define XLogRecHasAnyBlockRefs(decoder) ((decoder)->record->max_block_id >= 0)
417 : : #define XLogRecMaxBlockId(decoder) ((decoder)->record->max_block_id)
418 : : #define XLogRecGetBlock(decoder, i) (&(decoder)->record->blocks[(i)])
419 : : #define XLogRecHasBlockRef(decoder, block_id) \
420 : : (((decoder)->record->max_block_id >= (block_id)) && \
421 : : ((decoder)->record->blocks[block_id].in_use))
422 : : #define XLogRecHasBlockImage(decoder, block_id) \
423 : : ((decoder)->record->blocks[block_id].has_image)
424 : : #define XLogRecBlockImageApply(decoder, block_id) \
425 : : ((decoder)->record->blocks[block_id].apply_image)
426 : : #define XLogRecHasBlockData(decoder, block_id) \
427 : : ((decoder)->record->blocks[block_id].has_data)
428 : :
429 : : #ifndef FRONTEND
430 : : extern FullTransactionId XLogRecGetFullXid(XLogReaderState *record);
431 : : #endif
432 : :
433 : : extern bool RestoreBlockImage(XLogReaderState *record, uint8 block_id, char *page);
434 : : extern char *XLogRecGetBlockData(XLogReaderState *record, uint8 block_id, Size *len);
435 : : extern void XLogRecGetBlockTag(XLogReaderState *record, uint8 block_id,
436 : : RelFileLocator *rlocator, ForkNumber *forknum,
437 : : BlockNumber *blknum);
438 : : extern bool XLogRecGetBlockTagExtended(XLogReaderState *record, uint8 block_id,
439 : : RelFileLocator *rlocator, ForkNumber *forknum,
440 : : BlockNumber *blknum,
441 : : Buffer *prefetch_buffer);
442 : :
443 : : #endif /* XLOGREADER_H */
|
