PostgreSQL Source Code  git master
xlogreader.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * xlogreader.h
4  * Definitions for the generic XLog reading facility
5  *
6  * Portions Copyright (c) 2013-2020, 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 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 
43 /* WALOpenSegment represents a WAL segment being read. */
44 typedef struct WALOpenSegment
45 {
46  int ws_file; /* segment file descriptor */
47  XLogSegNo ws_segno; /* segment number */
48  TimeLineID ws_tli; /* timeline ID of the currently open file */
50 
51 /* WALSegmentContext carries context information about WAL segments to read */
52 typedef struct WALSegmentContext
53 {
54  char ws_dir[MAXPGPATH];
57 
59 
60 /* Function type definitions for various xlogreader interactions */
62  XLogRecPtr targetPagePtr,
63  int reqLen,
64  XLogRecPtr targetRecPtr,
65  char *readBuf);
67  XLogSegNo nextSegNo,
68  TimeLineID *tli_p);
70 
71 typedef struct XLogReaderRoutine
72 {
73  /*
74  * Data input callback
75  *
76  * This callback shall read at least reqLen valid bytes of the xlog page
77  * starting at targetPagePtr, and store them in readBuf. The callback
78  * shall return the number of bytes read (never more than XLOG_BLCKSZ), or
79  * -1 on failure. The callback shall sleep, if necessary, to wait for the
80  * requested bytes to become available. The callback will not be invoked
81  * again for the same page unless more than the returned number of bytes
82  * are needed.
83  *
84  * targetRecPtr is the position of the WAL record we're reading. Usually
85  * it is equal to targetPagePtr + reqLen, but sometimes xlogreader needs
86  * to read and verify the page or segment header, before it reads the
87  * actual WAL record it's interested in. In that case, targetRecPtr can
88  * be used to determine which timeline to read the page from.
89  *
90  * The callback shall set ->seg.ws_tli to the TLI of the file the page was
91  * read from.
92  */
94 
95  /*
96  * Callback to open the specified WAL segment for reading. ->seg.ws_file
97  * shall be set to the file descriptor of the opened segment. In case of
98  * failure, an error shall be raised by the callback and it shall not
99  * return.
100  *
101  * "nextSegNo" is the number of the segment to be opened.
102  *
103  * "tli_p" is an input/output argument. WALRead() uses it to pass the
104  * timeline in which the new segment should be found, but the callback can
105  * use it to return the TLI that it actually opened.
106  */
108 
109  /*
110  * WAL segment close callback. ->seg.ws_file shall be set to a negative
111  * number.
112  */
115 
116 #define XL_ROUTINE(...) &(XLogReaderRoutine){__VA_ARGS__}
117 
118 typedef struct
119 {
120  /* Is this block ref in use? */
121  bool in_use;
122 
123  /* Identify the block this refers to */
127 
128  /* copy of the fork_flags field from the XLogRecordBlockHeader */
130 
131  /* Information on full-page image, if any */
132  bool has_image; /* has image, even for consistency checking */
133  bool apply_image; /* has image that should be restored */
134  char *bkp_image;
139 
140  /* Buffer holding the rmgr-specific data associated with this block */
141  bool has_data;
142  char *data;
146 
148 {
149  /*
150  * Operational callbacks
151  */
153 
154  /* ----------------------------------------
155  * Public parameters
156  * ----------------------------------------
157  */
158 
159  /*
160  * System identifier of the xlog files we're about to read. Set to zero
161  * (the default value) if unknown or unimportant.
162  */
164 
165  /*
166  * Opaque data for callbacks to use. Not used by XLogReader.
167  */
169 
170  /*
171  * Start and end point of last record read. EndRecPtr is also used as the
172  * position to read next. Calling XLogBeginRead() sets EndRecPtr to the
173  * starting position and ReadRecPtr to invalid.
174  */
175  XLogRecPtr ReadRecPtr; /* start of last record read */
176  XLogRecPtr EndRecPtr; /* end+1 of last record read */
177 
178 
179  /* ----------------------------------------
180  * Decoded representation of current record
181  *
182  * Use XLogRecGet* functions to investigate the record; these fields
183  * should not be accessed directly.
184  * ----------------------------------------
185  */
186  XLogRecord *decoded_record; /* currently decoded record */
187 
188  char *main_data; /* record's main data portion */
189  uint32 main_data_len; /* main data portion's length */
190  uint32 main_data_bufsz; /* allocated size of the buffer */
191 
193 
194  TransactionId toplevel_xid; /* XID of top-level transaction */
195 
196  /* information about blocks referenced by the record. */
198 
199  int max_block_id; /* highest block_id in use (-1 if none) */
200 
201  /* ----------------------------------------
202  * private/internal state
203  * ----------------------------------------
204  */
205 
206  /*
207  * Buffer for currently read page (XLOG_BLCKSZ bytes, valid up to at least
208  * readLen bytes)
209  */
210  char *readBuf;
212 
213  /* last read XLOG position for data currently in readBuf */
217 
218  /*
219  * beginning of prior page read, and its TLI. Doesn't necessarily
220  * correspond to what's in readBuf; used for timeline sanity checks.
221  */
224 
225  /* beginning of the WAL record being read. */
227  /* timeline to read it from, 0 if a lookup is required */
229 
230  /*
231  * Safe point to read to in currTLI if current TLI is historical
232  * (tliSwitchPoint) or InvalidXLogRecPtr if on current timeline.
233  *
234  * Actually set to the start of the segment containing the timeline switch
235  * that ends currTLI's validity, not the LSN of the switch its self, since
236  * we can't assume the old segment will be present.
237  */
239 
240  /*
241  * If currTLI is not the most recent known timeline, the next timeline to
242  * read from when currTLIValidUntil is reached.
243  */
245 
246  /*
247  * Buffer for current ReadRecord result (expandable), used when a record
248  * crosses a page boundary.
249  */
252 
253  /* Buffer to hold error message */
255 };
256 
257 /* Get a new XLogReader */
259  const char *waldir,
260  XLogReaderRoutine *routine,
261  void *private_data);
263 
264 /* Free an XLogReader */
265 extern void XLogReaderFree(XLogReaderState *state);
266 
267 /* Position the XLogReader to given record */
268 extern void XLogBeginRead(XLogReaderState *state, XLogRecPtr RecPtr);
269 #ifdef FRONTEND
270 extern XLogRecPtr XLogFindNextRecord(XLogReaderState *state, XLogRecPtr RecPtr);
271 #endif /* FRONTEND */
272 
273 /* Read the next XLog record. Returns NULL on end-of-WAL or failure */
275  char **errormsg);
276 
277 /* Validate a page */
279  XLogRecPtr recptr, char *phdr);
280 
281 /*
282  * Error information from WALRead that both backend and frontend caller can
283  * process. Currently only errors from pg_pread can be reported.
284  */
285 typedef struct WALReadError
286 {
287  int wre_errno; /* errno set by the last pg_pread() */
288  int wre_off; /* Offset we tried to read from. */
289  int wre_req; /* Bytes requested to be read. */
290  int wre_read; /* Bytes read by the last read(). */
291  WALOpenSegment wre_seg; /* Segment we tried to read from. */
292 } WALReadError;
293 
294 extern bool WALRead(XLogReaderState *state,
295  char *buf, XLogRecPtr startptr, Size count,
296  TimeLineID tli, WALReadError *errinfo);
297 
298 /* Functions for decoding an XLogRecord */
299 
300 extern bool DecodeXLogRecord(XLogReaderState *state, XLogRecord *record,
301  char **errmsg);
302 
303 #define XLogRecGetTotalLen(decoder) ((decoder)->decoded_record->xl_tot_len)
304 #define XLogRecGetPrev(decoder) ((decoder)->decoded_record->xl_prev)
305 #define XLogRecGetInfo(decoder) ((decoder)->decoded_record->xl_info)
306 #define XLogRecGetRmid(decoder) ((decoder)->decoded_record->xl_rmid)
307 #define XLogRecGetXid(decoder) ((decoder)->decoded_record->xl_xid)
308 #define XLogRecGetOrigin(decoder) ((decoder)->record_origin)
309 #define XLogRecGetTopXid(decoder) ((decoder)->toplevel_xid)
310 #define XLogRecGetData(decoder) ((decoder)->main_data)
311 #define XLogRecGetDataLen(decoder) ((decoder)->main_data_len)
312 #define XLogRecHasAnyBlockRefs(decoder) ((decoder)->max_block_id >= 0)
313 #define XLogRecHasBlockRef(decoder, block_id) \
314  ((decoder)->blocks[block_id].in_use)
315 #define XLogRecHasBlockImage(decoder, block_id) \
316  ((decoder)->blocks[block_id].has_image)
317 #define XLogRecBlockImageApply(decoder, block_id) \
318  ((decoder)->blocks[block_id].apply_image)
319 
320 #ifndef FRONTEND
322 #endif
323 
324 extern bool RestoreBlockImage(XLogReaderState *record, uint8 block_id, char *page);
325 extern char *XLogRecGetBlockData(XLogReaderState *record, uint8 block_id, Size *len);
326 extern bool XLogRecGetBlockTag(XLogReaderState *record, uint8 block_id,
327  RelFileNode *rnode, ForkNumber *forknum,
328  BlockNumber *blknum);
329 
330 #endif /* XLOGREADER_H */
WALOpenSegment wre_seg
Definition: xlogreader.h:291
BlockNumber blkno
Definition: xlogreader.h:126
bool RestoreBlockImage(XLogReaderState *record, uint8 block_id, char *page)
Definition: xlogreader.c:1551
struct WALSegmentContext WALSegmentContext
WALSegmentCloseCB segment_close
Definition: xlogreader.h:113
char * readRecordBuf
Definition: xlogreader.h:250
uint32 TimeLineID
Definition: xlogdefs.h:52
int wal_segment_size
Definition: xlog.c:117
uint32 TransactionId
Definition: c.h:520
bool DecodeXLogRecord(XLogReaderState *state, XLogRecord *record, char **errmsg)
Definition: xlogreader.c:1177
struct XLogReaderRoutine XLogReaderRoutine
uint16 hole_offset
Definition: xlogreader.h:135
bool XLogRecGetBlockTag(XLogReaderState *record, uint8 block_id, RelFileNode *rnode, ForkNumber *forknum, BlockNumber *blknum)
Definition: xlogreader.c:1498
unsigned char uint8
Definition: c.h:372
uint16 RepOriginId
Definition: xlogdefs.h:58
uint32 BlockNumber
Definition: block.h:31
void * private_data
Definition: xlogreader.h:168
void XLogBeginRead(XLogReaderState *state, XLogRecPtr RecPtr)
Definition: xlogreader.c:240
XLogPageReadCB page_read
Definition: xlogreader.h:93
XLogRecPtr EndRecPtr
Definition: xlogreader.h:176
WALOpenSegment seg
Definition: xlogreader.h:215
unsigned short uint16
Definition: c.h:373
XLogRecPtr latestPagePtr
Definition: xlogreader.h:222
uint16 hole_length
Definition: xlogreader.h:136
struct WALReadError WALReadError
uint32 main_data_len
Definition: xlogreader.h:189
#define MAXPGPATH
struct XLogRecord * XLogReadRecord(XLogReaderState *state, char **errormsg)
Definition: xlogreader.c:268
static char * buf
Definition: pg_test_fsync.c:68
uint64 XLogSegNo
Definition: xlogdefs.h:41
XLogRecPtr ReadRecPtr
Definition: xlogreader.h:175
XLogRecord * decoded_record
Definition: xlogreader.h:186
struct WALOpenSegment WALOpenSegment
XLogSegNo ws_segno
Definition: xlogreader.h:47
XLogRecPtr currTLIValidUntil
Definition: xlogreader.h:238
unsigned int uint32
Definition: c.h:374
void(* WALSegmentCloseCB)(XLogReaderState *xlogreader)
Definition: xlogreader.h:69
static XLogReaderState * xlogreader
Definition: walsender.c:137
void(* WALSegmentOpenCB)(XLogReaderState *xlogreader, XLogSegNo nextSegNo, TimeLineID *tli_p)
Definition: xlogreader.h:66
ForkNumber
Definition: relpath.h:40
#define XLR_MAX_BLOCK_ID
Definition: xlogrecord.h:221
uint32 readRecordBufSize
Definition: xlogreader.h:251
TimeLineID nextTLI
Definition: xlogreader.h:244
FullTransactionId XLogRecGetFullXid(XLogReaderState *record)
Definition: xlogreader.c:1604
TransactionId toplevel_xid
Definition: xlogreader.h:194
ForkNumber forknum
Definition: xlogreader.h:125
bool WALRead(XLogReaderState *state, char *buf, XLogRecPtr startptr, Size count, TimeLineID tli, WALReadError *errinfo)
Definition: xlogreader.c:1063
XLogRecPtr currRecPtr
Definition: xlogreader.h:226
TimeLineID currTLI
Definition: xlogreader.h:228
uint64 XLogRecPtr
Definition: xlogdefs.h:21
Definition: regguts.h:298
void XLogReaderFree(XLogReaderState *state)
Definition: xlogreader.c:139
bool XLogReaderValidatePageHeader(XLogReaderState *state, XLogRecPtr recptr, char *phdr)
Definition: xlogreader.c:787
uint16 data_bufsz
Definition: xlogreader.h:144
size_t Size
Definition: c.h:473
XLogReaderState * XLogReaderAllocate(int wal_segment_size, const char *waldir, XLogReaderRoutine *routine, void *private_data)
Definition: xlogreader.c:75
static int64 blocks
Definition: pg_checksums.c:35
TimeLineID ws_tli
Definition: xlogreader.h:48
char * bkp_image
Definition: xlogreader.h:134
uint32 main_data_bufsz
Definition: xlogreader.h:190
XLogReaderRoutine * LocalXLogReaderRoutine(void)
char * XLogRecGetBlockData(XLogReaderState *record, uint8 block_id, Size *len)
Definition: xlogreader.c:1522
int errmsg(const char *fmt,...)
Definition: elog.c:824
uint64 system_identifier
Definition: xlogreader.h:163
WALSegmentContext segcxt
Definition: xlogreader.h:214
WALSegmentOpenCB segment_open
Definition: xlogreader.h:107
int(* XLogPageReadCB)(XLogReaderState *xlogreader, XLogRecPtr targetPagePtr, int reqLen, XLogRecPtr targetRecPtr, char *readBuf)
Definition: xlogreader.h:61
char * errormsg_buf
Definition: xlogreader.h:254
char * main_data
Definition: xlogreader.h:188
TimeLineID latestPageTLI
Definition: xlogreader.h:223
XLogReaderRoutine routine
Definition: xlogreader.h:152
RelFileNode rnode
Definition: xlogreader.h:124
RepOriginId record_origin
Definition: xlogreader.h:192
static XLogRecPtr startptr
Definition: basebackup.c:116