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