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  * After reading a record with XLogReadRecord(), it's decomposed into
21  * the per-block and main data parts, and the parts can be accessed
22  * with the XLogRec* macros and functions. You can also decode a
23  * record that's already constructed in memory, without reading from
24  * disk, by calling the DecodeXLogRecord() function.
25  *-------------------------------------------------------------------------
26  */
27 #ifndef XLOGREADER_H
28 #define XLOGREADER_H
29 
30 #ifndef FRONTEND
31 #include "access/transam.h"
32 #endif
33 
34 #include "access/xlogrecord.h"
35 
36 /* WALOpenSegment represents a WAL segment being read. */
37 typedef struct WALOpenSegment
38 {
39  int ws_file; /* segment file descriptor */
40  XLogSegNo ws_segno; /* segment number */
41  TimeLineID ws_tli; /* timeline ID of the currently open file */
43 
44 /* WALSegmentContext carries context information about WAL segments to read */
45 typedef struct WALSegmentContext
46 {
47  char ws_dir[MAXPGPATH];
50 
52 
53 /* Function type definition for the read_page callback */
54 typedef int (*XLogPageReadCB) (XLogReaderState *xlogreader,
55  XLogRecPtr targetPagePtr,
56  int reqLen,
57  XLogRecPtr targetRecPtr,
58  char *readBuf);
59 
60 typedef struct
61 {
62  /* Is this block ref in use? */
63  bool in_use;
64 
65  /* Identify the block this refers to */
69 
70  /* copy of the fork_flags field from the XLogRecordBlockHeader */
72 
73  /* Information on full-page image, if any */
74  bool has_image; /* has image, even for consistency checking */
75  bool apply_image; /* has image that should be restored */
76  char *bkp_image;
81 
82  /* Buffer holding the rmgr-specific data associated with this block */
83  bool has_data;
84  char *data;
88 
90 {
91  /* ----------------------------------------
92  * Public parameters
93  * ----------------------------------------
94  */
95 
96  /*
97  * Data input callback (mandatory).
98  *
99  * This callback shall read at least reqLen valid bytes of the xlog page
100  * starting at targetPagePtr, and store them in readBuf. The callback
101  * shall return the number of bytes read (never more than XLOG_BLCKSZ), or
102  * -1 on failure. The callback shall sleep, if necessary, to wait for the
103  * requested bytes to become available. The callback will not be invoked
104  * again for the same page unless more than the returned number of bytes
105  * are needed.
106  *
107  * targetRecPtr is the position of the WAL record we're reading. Usually
108  * it is equal to targetPagePtr + reqLen, but sometimes xlogreader needs
109  * to read and verify the page or segment header, before it reads the
110  * actual WAL record it's interested in. In that case, targetRecPtr can
111  * be used to determine which timeline to read the page from.
112  *
113  * The callback shall set ->seg.ws_tli to the TLI of the file the page was
114  * read from.
115  */
117 
118  /*
119  * System identifier of the xlog files we're about to read. Set to zero
120  * (the default value) if unknown or unimportant.
121  */
123 
124  /*
125  * Opaque data for callbacks to use. Not used by XLogReader.
126  */
128 
129  /*
130  * Start and end point of last record read. EndRecPtr is also used as the
131  * position to read next. Calling XLogBeginRead() sets EndRecPtr to the
132  * starting position and ReadRecPtr to invalid.
133  */
134  XLogRecPtr ReadRecPtr; /* start of last record read */
135  XLogRecPtr EndRecPtr; /* end+1 of last record read */
136 
137 
138  /* ----------------------------------------
139  * Decoded representation of current record
140  *
141  * Use XLogRecGet* functions to investigate the record; these fields
142  * should not be accessed directly.
143  * ----------------------------------------
144  */
145  XLogRecord *decoded_record; /* currently decoded record */
146 
147  char *main_data; /* record's main data portion */
148  uint32 main_data_len; /* main data portion's length */
149  uint32 main_data_bufsz; /* allocated size of the buffer */
150 
152 
153  /* information about blocks referenced by the record. */
155 
156  int max_block_id; /* highest block_id in use (-1 if none) */
157 
158  /* ----------------------------------------
159  * private/internal state
160  * ----------------------------------------
161  */
162 
163  /*
164  * Buffer for currently read page (XLOG_BLCKSZ bytes, valid up to at least
165  * readLen bytes)
166  */
167  char *readBuf;
169 
170  /* last read XLOG position for data currently in readBuf */
174 
175  /*
176  * beginning of prior page read, and its TLI. Doesn't necessarily
177  * correspond to what's in readBuf; used for timeline sanity checks.
178  */
181 
182  /* beginning of the WAL record being read. */
184  /* timeline to read it from, 0 if a lookup is required */
186 
187  /*
188  * Safe point to read to in currTLI if current TLI is historical
189  * (tliSwitchPoint) or InvalidXLogRecPtr if on current timeline.
190  *
191  * Actually set to the start of the segment containing the timeline switch
192  * that ends currTLI's validity, not the LSN of the switch its self, since
193  * we can't assume the old segment will be present.
194  */
196 
197  /*
198  * If currTLI is not the most recent known timeline, the next timeline to
199  * read from when currTLIValidUntil is reached.
200  */
202 
203  /*
204  * Buffer for current ReadRecord result (expandable), used when a record
205  * crosses a page boundary.
206  */
209 
210  /* Buffer to hold error message */
212 };
213 
214 /* Get a new XLogReader */
216  const char *waldir,
217  XLogPageReadCB pagereadfunc,
218  void *private_data);
219 
220 /* Free an XLogReader */
221 extern void XLogReaderFree(XLogReaderState *state);
222 
223 /*
224  * Callback to open the specified WAL segment for reading. Returns a valid
225  * file descriptor when the file was opened successfully.
226  *
227  * "nextSegNo" is the number of the segment to be opened.
228  *
229  * "segcxt" is additional information about the segment.
230  *
231  * "tli_p" is an input/output argument. XLogRead() uses it to pass the
232  * timeline in which the new segment should be found, but the callback can use
233  * it to return the TLI that it actually opened.
234  *
235  * BasicOpenFile() is the preferred way to open the segment file in backend
236  * code, whereas open(2) should be used in frontend.
237  */
238 typedef int (*WALSegmentOpen) (XLogSegNo nextSegNo, WALSegmentContext *segcxt,
239  TimeLineID *tli_p);
240 
241 /* Initialize supporting structures */
242 extern void WALOpenSegmentInit(WALOpenSegment *seg, WALSegmentContext *segcxt,
243  int segsize, const char *waldir);
244 
245 /* Position the XLogReader to given record */
246 extern void XLogBeginRead(XLogReaderState *state, XLogRecPtr RecPtr);
247 #ifdef FRONTEND
248 extern XLogRecPtr XLogFindNextRecord(XLogReaderState *state, XLogRecPtr RecPtr);
249 #endif /* FRONTEND */
250 
251 /* Read the next XLog record. Returns NULL on end-of-WAL or failure */
253  char **errormsg);
254 
255 /* Validate a page */
257  XLogRecPtr recptr, char *phdr);
258 
259 /*
260  * Error information from WALRead that both backend and frontend caller can
261  * process. Currently only errors from pg_pread can be reported.
262  */
263 typedef struct WALReadError
264 {
265  int wre_errno; /* errno set by the last pg_pread() */
266  int wre_off; /* Offset we tried to read from. */
267  int wre_req; /* Bytes requested to be read. */
268  int wre_read; /* Bytes read by the last read(). */
269  WALOpenSegment wre_seg; /* Segment we tried to read from. */
270 } WALReadError;
271 
272 extern bool WALRead(char *buf, XLogRecPtr startptr, Size count,
273  TimeLineID tli, WALOpenSegment *seg,
274  WALSegmentContext *segcxt, WALSegmentOpen openSegment,
275  WALReadError *errinfo);
276 
277 /* Functions for decoding an XLogRecord */
278 
279 extern bool DecodeXLogRecord(XLogReaderState *state, XLogRecord *record,
280  char **errmsg);
281 
282 #define XLogRecGetTotalLen(decoder) ((decoder)->decoded_record->xl_tot_len)
283 #define XLogRecGetPrev(decoder) ((decoder)->decoded_record->xl_prev)
284 #define XLogRecGetInfo(decoder) ((decoder)->decoded_record->xl_info)
285 #define XLogRecGetRmid(decoder) ((decoder)->decoded_record->xl_rmid)
286 #define XLogRecGetXid(decoder) ((decoder)->decoded_record->xl_xid)
287 #define XLogRecGetOrigin(decoder) ((decoder)->record_origin)
288 #define XLogRecGetData(decoder) ((decoder)->main_data)
289 #define XLogRecGetDataLen(decoder) ((decoder)->main_data_len)
290 #define XLogRecHasAnyBlockRefs(decoder) ((decoder)->max_block_id >= 0)
291 #define XLogRecHasBlockRef(decoder, block_id) \
292  ((decoder)->blocks[block_id].in_use)
293 #define XLogRecHasBlockImage(decoder, block_id) \
294  ((decoder)->blocks[block_id].has_image)
295 #define XLogRecBlockImageApply(decoder, block_id) \
296  ((decoder)->blocks[block_id].apply_image)
297 
298 #ifndef FRONTEND
300 #endif
301 
302 extern bool RestoreBlockImage(XLogReaderState *record, uint8 block_id, char *page);
303 extern char *XLogRecGetBlockData(XLogReaderState *record, uint8 block_id, Size *len);
304 extern bool XLogRecGetBlockTag(XLogReaderState *record, uint8 block_id,
305  RelFileNode *rnode, ForkNumber *forknum,
306  BlockNumber *blknum);
307 
308 #endif /* XLOGREADER_H */
WALOpenSegment wre_seg
Definition: xlogreader.h:269
BlockNumber blkno
Definition: xlogreader.h:68
bool RestoreBlockImage(XLogReaderState *record, uint8 block_id, char *page)
Definition: xlogreader.c:1537
struct WALSegmentContext WALSegmentContext
XLogPageReadCB read_page
Definition: xlogreader.h:116
char * readRecordBuf
Definition: xlogreader.h:207
bool WALRead(char *buf, XLogRecPtr startptr, Size count, TimeLineID tli, WALOpenSegment *seg, WALSegmentContext *segcxt, WALSegmentOpen openSegment, WALReadError *errinfo)
Definition: xlogreader.c:1057
uint32 TimeLineID
Definition: xlogdefs.h:52
int wal_segment_size
Definition: xlog.c:116
bool DecodeXLogRecord(XLogReaderState *state, XLogRecord *record, char **errmsg)
Definition: xlogreader.c:1168
uint16 hole_offset
Definition: xlogreader.h:77
bool XLogRecGetBlockTag(XLogReaderState *record, uint8 block_id, RelFileNode *rnode, ForkNumber *forknum, BlockNumber *blknum)
Definition: xlogreader.c:1484
unsigned char uint8
Definition: c.h:365
uint16 RepOriginId
Definition: xlogdefs.h:58
uint32 BlockNumber
Definition: block.h:31
void * private_data
Definition: xlogreader.h:127
void XLogBeginRead(XLogReaderState *state, XLogRecPtr RecPtr)
Definition: xlogreader.c:236
uint16 bimg_len
Definition: xlogreader.h:79
XLogRecPtr EndRecPtr
Definition: xlogreader.h:135
int(* WALSegmentOpen)(XLogSegNo nextSegNo, WALSegmentContext *segcxt, TimeLineID *tli_p)
Definition: xlogreader.h:238
WALOpenSegment seg
Definition: xlogreader.h:172
unsigned short uint16
Definition: c.h:366
XLogRecPtr latestPagePtr
Definition: xlogreader.h:179
uint16 hole_length
Definition: xlogreader.h:78
struct WALReadError WALReadError
uint32 main_data_len
Definition: xlogreader.h:148
#define MAXPGPATH
struct XLogRecord * XLogReadRecord(XLogReaderState *state, char **errormsg)
Definition: xlogreader.c:264
static char * buf
Definition: pg_test_fsync.c:67
uint64 XLogSegNo
Definition: xlogdefs.h:41
XLogRecPtr ReadRecPtr
Definition: xlogreader.h:134
XLogRecord * decoded_record
Definition: xlogreader.h:145
struct WALOpenSegment WALOpenSegment
XLogSegNo ws_segno
Definition: xlogreader.h:40
XLogRecPtr currTLIValidUntil
Definition: xlogreader.h:195
unsigned int uint32
Definition: c.h:367
ForkNumber
Definition: relpath.h:40
#define XLR_MAX_BLOCK_ID
Definition: xlogrecord.h:221
uint32 readRecordBufSize
Definition: xlogreader.h:208
TimeLineID nextTLI
Definition: xlogreader.h:201
FullTransactionId XLogRecGetFullXid(XLogReaderState *record)
Definition: xlogreader.c:1590
void WALOpenSegmentInit(WALOpenSegment *seg, WALSegmentContext *segcxt, int segsize, const char *waldir)
Definition: xlogreader.c:212
ForkNumber forknum
Definition: xlogreader.h:67
uint16 data_len
Definition: xlogreader.h:85
XLogRecPtr currRecPtr
Definition: xlogreader.h:183
TimeLineID currTLI
Definition: xlogreader.h:185
uint64 XLogRecPtr
Definition: xlogdefs.h:21
Definition: regguts.h:298
void XLogReaderFree(XLogReaderState *state)
Definition: xlogreader.c:135
bool XLogReaderValidatePageHeader(XLogReaderState *state, XLogRecPtr recptr, char *phdr)
Definition: xlogreader.c:782
uint16 data_bufsz
Definition: xlogreader.h:86
size_t Size
Definition: c.h:466
static int64 blocks
Definition: pg_checksums.c:35
TimeLineID ws_tli
Definition: xlogreader.h:41
char * bkp_image
Definition: xlogreader.h:76
uint32 main_data_bufsz
Definition: xlogreader.h:149
char * XLogRecGetBlockData(XLogReaderState *record, uint8 block_id, Size *len)
Definition: xlogreader.c:1508
int errmsg(const char *fmt,...)
Definition: elog.c:824
uint64 system_identifier
Definition: xlogreader.h:122
WALSegmentContext segcxt
Definition: xlogreader.h:171
int(* XLogPageReadCB)(XLogReaderState *xlogreader, XLogRecPtr targetPagePtr, int reqLen, XLogRecPtr targetRecPtr, char *readBuf)
Definition: xlogreader.h:54
char * errormsg_buf
Definition: xlogreader.h:211
char * main_data
Definition: xlogreader.h:147
TimeLineID latestPageTLI
Definition: xlogreader.h:180
RelFileNode rnode
Definition: xlogreader.h:66
XLogReaderState * XLogReaderAllocate(int wal_segment_size, const char *waldir, XLogPageReadCB pagereadfunc, void *private_data)
Definition: xlogreader.c:73
RepOriginId record_origin
Definition: xlogreader.h:151
static XLogRecPtr startptr
Definition: basebackup.c:168