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 
35 
36 /* Function type definition for the read_page callback */
37 typedef int (*XLogPageReadCB) (XLogReaderState *xlogreader,
38  XLogRecPtr targetPagePtr,
39  int reqLen,
40  XLogRecPtr targetRecPtr,
41  char *readBuf,
42  TimeLineID *pageTLI);
43 
44 typedef struct
45 {
46  /* Is this block ref in use? */
47  bool in_use;
48 
49  /* Identify the block this refers to */
53 
54  /* copy of the fork_flags field from the XLogRecordBlockHeader */
56 
57  /* Information on full-page image, if any */
58  bool has_image; /* has image, even for consistency checking */
59  bool apply_image; /* has image that should be restored */
60  char *bkp_image;
65 
66  /* Buffer holding the rmgr-specific data associated with this block */
67  bool has_data;
68  char *data;
72 
74 {
75  /* ----------------------------------------
76  * Public parameters
77  * ----------------------------------------
78  */
79 
80  /*
81  * Segment size of the to-be-parsed data (mandatory).
82  */
84 
85  /*
86  * Data input callback (mandatory).
87  *
88  * This callback shall read at least reqLen valid bytes of the xlog page
89  * starting at targetPagePtr, and store them in readBuf. The callback
90  * shall return the number of bytes read (never more than XLOG_BLCKSZ), or
91  * -1 on failure. The callback shall sleep, if necessary, to wait for the
92  * requested bytes to become available. The callback will not be invoked
93  * again for the same page unless more than the returned number of bytes
94  * are needed.
95  *
96  * targetRecPtr is the position of the WAL record we're reading. Usually
97  * it is equal to targetPagePtr + reqLen, but sometimes xlogreader needs
98  * to read and verify the page or segment header, before it reads the
99  * actual WAL record it's interested in. In that case, targetRecPtr can
100  * be used to determine which timeline to read the page from.
101  *
102  * The callback shall set *pageTLI to the TLI of the file the page was
103  * read from. It is currently used only for error reporting purposes, to
104  * reconstruct the name of the WAL file where an error occurred.
105  */
107 
108  /*
109  * System identifier of the xlog files we're about to read. Set to zero
110  * (the default value) if unknown or unimportant.
111  */
113 
114  /*
115  * Opaque data for callbacks to use. Not used by XLogReader.
116  */
118 
119  /*
120  * Start and end point of last record read. EndRecPtr is also used as the
121  * position to read next, if XLogReadRecord receives an invalid recptr.
122  */
123  XLogRecPtr ReadRecPtr; /* start of last record read */
124  XLogRecPtr EndRecPtr; /* end+1 of last record read */
125 
126 
127  /* ----------------------------------------
128  * Decoded representation of current record
129  *
130  * Use XLogRecGet* functions to investigate the record; these fields
131  * should not be accessed directly.
132  * ----------------------------------------
133  */
134  XLogRecord *decoded_record; /* currently decoded record */
135 
136  char *main_data; /* record's main data portion */
137  uint32 main_data_len; /* main data portion's length */
138  uint32 main_data_bufsz; /* allocated size of the buffer */
139 
141 
142  /* information about blocks referenced by the record. */
144 
145  int max_block_id; /* highest block_id in use (-1 if none) */
146 
147  /* ----------------------------------------
148  * private/internal state
149  * ----------------------------------------
150  */
151 
152  /*
153  * Buffer for currently read page (XLOG_BLCKSZ bytes, valid up to at least
154  * readLen bytes)
155  */
156  char *readBuf;
158 
159  /* last read segment, segment offset, TLI for data currently in readBuf */
163 
164  /*
165  * beginning of prior page read, and its TLI. Doesn't necessarily
166  * correspond to what's in readBuf; used for timeline sanity checks.
167  */
170 
171  /* beginning of the WAL record being read. */
173  /* timeline to read it from, 0 if a lookup is required */
175 
176  /*
177  * Safe point to read to in currTLI if current TLI is historical
178  * (tliSwitchPoint) or InvalidXLogRecPtr if on current timeline.
179  *
180  * Actually set to the start of the segment containing the timeline switch
181  * that ends currTLI's validity, not the LSN of the switch its self, since
182  * we can't assume the old segment will be present.
183  */
185 
186  /*
187  * If currTLI is not the most recent known timeline, the next timeline to
188  * read from when currTLIValidUntil is reached.
189  */
191 
192  /*
193  * Buffer for current ReadRecord result (expandable), used when a record
194  * crosses a page boundary.
195  */
198 
199  /* Buffer to hold error message */
201 };
202 
203 /* Get a new XLogReader */
205  XLogPageReadCB pagereadfunc,
206  void *private_data);
207 
208 /* Free an XLogReader */
209 extern void XLogReaderFree(XLogReaderState *state);
210 
211 /* Read the next XLog record. Returns NULL on end-of-WAL or failure */
213  XLogRecPtr recptr, char **errormsg);
214 
215 /* Validate a page */
217  XLogRecPtr recptr, char *phdr);
218 
219 #ifdef FRONTEND
220 extern XLogRecPtr XLogFindNextRecord(XLogReaderState *state, XLogRecPtr RecPtr);
221 #endif /* FRONTEND */
222 /* Functions for decoding an XLogRecord */
223 
224 extern bool DecodeXLogRecord(XLogReaderState *state, XLogRecord *record,
225  char **errmsg);
226 
227 #define XLogRecGetTotalLen(decoder) ((decoder)->decoded_record->xl_tot_len)
228 #define XLogRecGetPrev(decoder) ((decoder)->decoded_record->xl_prev)
229 #define XLogRecGetInfo(decoder) ((decoder)->decoded_record->xl_info)
230 #define XLogRecGetRmid(decoder) ((decoder)->decoded_record->xl_rmid)
231 #define XLogRecGetXid(decoder) ((decoder)->decoded_record->xl_xid)
232 #define XLogRecGetOrigin(decoder) ((decoder)->record_origin)
233 #define XLogRecGetData(decoder) ((decoder)->main_data)
234 #define XLogRecGetDataLen(decoder) ((decoder)->main_data_len)
235 #define XLogRecHasAnyBlockRefs(decoder) ((decoder)->max_block_id >= 0)
236 #define XLogRecHasBlockRef(decoder, block_id) \
237  ((decoder)->blocks[block_id].in_use)
238 #define XLogRecHasBlockImage(decoder, block_id) \
239  ((decoder)->blocks[block_id].has_image)
240 #define XLogRecBlockImageApply(decoder, block_id) \
241  ((decoder)->blocks[block_id].apply_image)
242 
243 #ifndef FRONTEND
245 #endif
246 
247 extern bool RestoreBlockImage(XLogReaderState *record, uint8 block_id, char *page);
248 extern char *XLogRecGetBlockData(XLogReaderState *record, uint8 block_id, Size *len);
249 extern bool XLogRecGetBlockTag(XLogReaderState *record, uint8 block_id,
250  RelFileNode *rnode, ForkNumber *forknum,
251  BlockNumber *blknum);
252 
253 #endif /* XLOGREADER_H */
BlockNumber blkno
Definition: xlogreader.h:52
bool RestoreBlockImage(XLogReaderState *record, uint8 block_id, char *page)
Definition: xlogreader.c:1402
XLogPageReadCB read_page
Definition: xlogreader.h:106
char * readRecordBuf
Definition: xlogreader.h:196
uint32 TimeLineID
Definition: xlogdefs.h:52
TimeLineID readPageTLI
Definition: xlogreader.h:162
bool DecodeXLogRecord(XLogReaderState *state, XLogRecord *record, char **errmsg)
Definition: xlogreader.c:1033
uint16 hole_offset
Definition: xlogreader.h:61
bool XLogRecGetBlockTag(XLogReaderState *record, uint8 block_id, RelFileNode *rnode, ForkNumber *forknum, BlockNumber *blknum)
Definition: xlogreader.c:1349
unsigned char uint8
Definition: c.h:356
uint16 RepOriginId
Definition: xlogdefs.h:58
uint32 BlockNumber
Definition: block.h:31
void * private_data
Definition: xlogreader.h:117
uint16 bimg_len
Definition: xlogreader.h:63
XLogRecPtr EndRecPtr
Definition: xlogreader.h:124
unsigned short uint16
Definition: c.h:357
XLogRecPtr latestPagePtr
Definition: xlogreader.h:168
uint16 hole_length
Definition: xlogreader.h:62
uint32 main_data_len
Definition: xlogreader.h:137
uint64 XLogSegNo
Definition: xlogdefs.h:41
XLogRecPtr ReadRecPtr
Definition: xlogreader.h:123
XLogRecord * decoded_record
Definition: xlogreader.h:134
XLogRecPtr currTLIValidUntil
Definition: xlogreader.h:184
unsigned int uint32
Definition: c.h:358
int wal_segment_size
Definition: xlogreader.h:83
ForkNumber
Definition: relpath.h:40
#define XLR_MAX_BLOCK_ID
Definition: xlogrecord.h:221
uint32 readRecordBufSize
Definition: xlogreader.h:197
TimeLineID nextTLI
Definition: xlogreader.h:190
FullTransactionId XLogRecGetFullXid(XLogReaderState *record)
Definition: xlogreader.c:1455
ForkNumber forknum
Definition: xlogreader.h:51
uint16 data_len
Definition: xlogreader.h:69
XLogRecPtr currRecPtr
Definition: xlogreader.h:172
TimeLineID currTLI
Definition: xlogreader.h:174
uint64 XLogRecPtr
Definition: xlogdefs.h:21
Definition: regguts.h:298
void XLogReaderFree(XLogReaderState *state)
Definition: xlogreader.c:131
XLogSegNo readSegNo
Definition: xlogreader.h:160
bool XLogReaderValidatePageHeader(XLogReaderState *state, XLogRecPtr recptr, char *phdr)
Definition: xlogreader.c:738
uint16 data_bufsz
Definition: xlogreader.h:70
XLogReaderState * XLogReaderAllocate(int wal_segment_size, XLogPageReadCB pagereadfunc, void *private_data)
Definition: xlogreader.c:71
size_t Size
Definition: c.h:466
int(* XLogPageReadCB)(XLogReaderState *xlogreader, XLogRecPtr targetPagePtr, int reqLen, XLogRecPtr targetRecPtr, char *readBuf, TimeLineID *pageTLI)
Definition: xlogreader.h:37
char * bkp_image
Definition: xlogreader.h:60
uint32 main_data_bufsz
Definition: xlogreader.h:138
char * XLogRecGetBlockData(XLogReaderState *record, uint8 block_id, Size *len)
Definition: xlogreader.c:1373
int errmsg(const char *fmt,...)
Definition: elog.c:784
struct XLogRecord * XLogReadRecord(XLogReaderState *state, XLogRecPtr recptr, char **errormsg)
Definition: xlogreader.c:218
uint64 system_identifier
Definition: xlogreader.h:112
char * errormsg_buf
Definition: xlogreader.h:200
char * main_data
Definition: xlogreader.h:136
TimeLineID latestPageTLI
Definition: xlogreader.h:169
RelFileNode rnode
Definition: xlogreader.h:50
RepOriginId record_origin
Definition: xlogreader.h:140
DecodedBkpBlock blocks[XLR_MAX_BLOCK_ID+1]
Definition: xlogreader.h:143