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