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