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-2019, 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  uint32 ws_off; /* offset in the segment */
40  TimeLineID ws_tli; /* timeline ID of the currently open file */
42 
43 /* WALSegmentContext carries context information about WAL segments to read */
44 typedef struct WALSegmentContext
45 {
46  char ws_dir[MAXPGPATH];
49 
51 
52 /* Function type definition for the read_page callback */
53 typedef int (*XLogPageReadCB) (XLogReaderState *xlogreader,
54  XLogRecPtr targetPagePtr,
55  int reqLen,
56  XLogRecPtr targetRecPtr,
57  char *readBuf);
58 
59 typedef struct
60 {
61  /* Is this block ref in use? */
62  bool in_use;
63 
64  /* Identify the block this refers to */
68 
69  /* copy of the fork_flags field from the XLogRecordBlockHeader */
71 
72  /* Information on full-page image, if any */
73  bool has_image; /* has image, even for consistency checking */
74  bool apply_image; /* has image that should be restored */
75  char *bkp_image;
80 
81  /* Buffer holding the rmgr-specific data associated with this block */
82  bool has_data;
83  char *data;
87 
89 {
90  /* ----------------------------------------
91  * Public parameters
92  * ----------------------------------------
93  */
94 
95  /*
96  * Data input callback (mandatory).
97  *
98  * This callback shall read at least reqLen valid bytes of the xlog page
99  * starting at targetPagePtr, and store them in readBuf. The callback
100  * shall return the number of bytes read (never more than XLOG_BLCKSZ), or
101  * -1 on failure. The callback shall sleep, if necessary, to wait for the
102  * requested bytes to become available. The callback will not be invoked
103  * again for the same page unless more than the returned number of bytes
104  * are needed.
105  *
106  * targetRecPtr is the position of the WAL record we're reading. Usually
107  * it is equal to targetPagePtr + reqLen, but sometimes xlogreader needs
108  * to read and verify the page or segment header, before it reads the
109  * actual WAL record it's interested in. In that case, targetRecPtr can
110  * be used to determine which timeline to read the page from.
111  *
112  * The callback shall set ->seg.ws_tli to the TLI of the file the page was
113  * read from.
114  */
116 
117  /*
118  * System identifier of the xlog files we're about to read. Set to zero
119  * (the default value) if unknown or unimportant.
120  */
122 
123  /*
124  * Opaque data for callbacks to use. Not used by XLogReader.
125  */
127 
128  /*
129  * Start and end point of last record read. EndRecPtr is also used as the
130  * position to read next, if XLogReadRecord receives an invalid recptr.
131  */
132  XLogRecPtr ReadRecPtr; /* start of last record read */
133  XLogRecPtr EndRecPtr; /* end+1 of last record read */
134 
135 
136  /* ----------------------------------------
137  * Decoded representation of current record
138  *
139  * Use XLogRecGet* functions to investigate the record; these fields
140  * should not be accessed directly.
141  * ----------------------------------------
142  */
143  XLogRecord *decoded_record; /* currently decoded record */
144 
145  char *main_data; /* record's main data portion */
146  uint32 main_data_len; /* main data portion's length */
147  uint32 main_data_bufsz; /* allocated size of the buffer */
148 
150 
151  /* information about blocks referenced by the record. */
153 
154  int max_block_id; /* highest block_id in use (-1 if none) */
155 
156  /* ----------------------------------------
157  * private/internal state
158  * ----------------------------------------
159  */
160 
161  /*
162  * Buffer for currently read page (XLOG_BLCKSZ bytes, valid up to at least
163  * readLen bytes)
164  */
165  char *readBuf;
167 
168  /* 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 /* Initialize supporting structures */
221 extern void WALOpenSegmentInit(WALOpenSegment *seg, WALSegmentContext *segcxt,
222  int segsize, const char *waldir);
223 
224 /* Read the next XLog record. Returns NULL on end-of-WAL or failure */
226  XLogRecPtr recptr, char **errormsg);
227 
228 /* Validate a page */
230  XLogRecPtr recptr, char *phdr);
231 
232 #ifdef FRONTEND
233 extern XLogRecPtr XLogFindNextRecord(XLogReaderState *state, XLogRecPtr RecPtr);
234 #endif /* FRONTEND */
235 /* Functions for decoding an XLogRecord */
236 
237 extern bool DecodeXLogRecord(XLogReaderState *state, XLogRecord *record,
238  char **errmsg);
239 
240 #define XLogRecGetTotalLen(decoder) ((decoder)->decoded_record->xl_tot_len)
241 #define XLogRecGetPrev(decoder) ((decoder)->decoded_record->xl_prev)
242 #define XLogRecGetInfo(decoder) ((decoder)->decoded_record->xl_info)
243 #define XLogRecGetRmid(decoder) ((decoder)->decoded_record->xl_rmid)
244 #define XLogRecGetXid(decoder) ((decoder)->decoded_record->xl_xid)
245 #define XLogRecGetOrigin(decoder) ((decoder)->record_origin)
246 #define XLogRecGetData(decoder) ((decoder)->main_data)
247 #define XLogRecGetDataLen(decoder) ((decoder)->main_data_len)
248 #define XLogRecHasAnyBlockRefs(decoder) ((decoder)->max_block_id >= 0)
249 #define XLogRecHasBlockRef(decoder, block_id) \
250  ((decoder)->blocks[block_id].in_use)
251 #define XLogRecHasBlockImage(decoder, block_id) \
252  ((decoder)->blocks[block_id].has_image)
253 #define XLogRecBlockImageApply(decoder, block_id) \
254  ((decoder)->blocks[block_id].apply_image)
255 
256 #ifndef FRONTEND
258 #endif
259 
260 extern bool RestoreBlockImage(XLogReaderState *record, uint8 block_id, char *page);
261 extern char *XLogRecGetBlockData(XLogReaderState *record, uint8 block_id, Size *len);
262 extern bool XLogRecGetBlockTag(XLogReaderState *record, uint8 block_id,
263  RelFileNode *rnode, ForkNumber *forknum,
264  BlockNumber *blknum);
265 
266 #endif /* XLOGREADER_H */
BlockNumber blkno
Definition: xlogreader.h:67
bool RestoreBlockImage(XLogReaderState *record, uint8 block_id, char *page)
Definition: xlogreader.c:1419
struct WALSegmentContext WALSegmentContext
XLogPageReadCB read_page
Definition: xlogreader.h:115
char * readRecordBuf
Definition: xlogreader.h:204
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:1050
uint16 hole_offset
Definition: xlogreader.h:76
bool XLogRecGetBlockTag(XLogReaderState *record, uint8 block_id, RelFileNode *rnode, ForkNumber *forknum, BlockNumber *blknum)
Definition: xlogreader.c:1366
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:126
uint16 bimg_len
Definition: xlogreader.h:78
XLogRecPtr EndRecPtr
Definition: xlogreader.h:133
WALOpenSegment seg
Definition: xlogreader.h:170
unsigned short uint16
Definition: c.h:358
XLogRecPtr latestPagePtr
Definition: xlogreader.h:176
uint16 hole_length
Definition: xlogreader.h:77
uint32 main_data_len
Definition: xlogreader.h:146
#define MAXPGPATH
uint64 XLogSegNo
Definition: xlogdefs.h:41
XLogRecPtr ReadRecPtr
Definition: xlogreader.h:132
XLogRecord * decoded_record
Definition: xlogreader.h:143
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:1472
void WALOpenSegmentInit(WALOpenSegment *seg, WALSegmentContext *segcxt, int segsize, const char *waldir)
Definition: xlogreader.c:206
ForkNumber forknum
Definition: xlogreader.h:66
uint16 data_len
Definition: xlogreader.h:84
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:132
bool XLogReaderValidatePageHeader(XLogReaderState *state, XLogRecPtr recptr, char *phdr)
Definition: xlogreader.c:756
uint16 data_bufsz
Definition: xlogreader.h:85
size_t Size
Definition: c.h:467
static int64 blocks
Definition: pg_checksums.c:35
TimeLineID ws_tli
Definition: xlogreader.h:40
char * bkp_image
Definition: xlogreader.h:75
uint32 main_data_bufsz
Definition: xlogreader.h:147
char * XLogRecGetBlockData(XLogReaderState *record, uint8 block_id, Size *len)
Definition: xlogreader.c:1390
int errmsg(const char *fmt,...)
Definition: elog.c:822
struct XLogRecord * XLogReadRecord(XLogReaderState *state, XLogRecPtr recptr, char **errormsg)
Definition: xlogreader.c:236
uint64 system_identifier
Definition: xlogreader.h:121
WALSegmentContext segcxt
Definition: xlogreader.h:169
int(* XLogPageReadCB)(XLogReaderState *xlogreader, XLogRecPtr targetPagePtr, int reqLen, XLogRecPtr targetRecPtr, char *readBuf)
Definition: xlogreader.h:53
char * errormsg_buf
Definition: xlogreader.h:208
uint32 ws_off
Definition: xlogreader.h:39
char * main_data
Definition: xlogreader.h:145
TimeLineID latestPageTLI
Definition: xlogreader.h:177
RelFileNode rnode
Definition: xlogreader.h:65
XLogReaderState * XLogReaderAllocate(int wal_segment_size, const char *waldir, XLogPageReadCB pagereadfunc, void *private_data)
Definition: xlogreader.c:70
RepOriginId record_origin
Definition: xlogreader.h:149