PostgreSQL Source Code  git master
blkreftable.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * blkreftable.h
4  * Block reference tables.
5  *
6  * A block reference table is used to keep track of which blocks have
7  * been modified by WAL records within a certain LSN range.
8  *
9  * For each relation fork, there is a "limit block number". All existing
10  * blocks greater than or equal to the limit block number must be
11  * considered modified; for those less than the limit block number,
12  * we maintain a bitmap. When a relation fork is created or dropped,
13  * the limit block number should be set to 0. When it's truncated,
14  * the limit block number should be set to the length in blocks to
15  * which it was truncated.
16  *
17  * Portions Copyright (c) 2010-2024, PostgreSQL Global Development Group
18  *
19  * src/include/common/blkreftable.h
20  *
21  *-------------------------------------------------------------------------
22  */
23 #ifndef BLKREFTABLE_H
24 #define BLKREFTABLE_H
25 
26 #include "storage/block.h"
27 #include "storage/relfilelocator.h"
28 
29 /* Magic number for serialization file format. */
30 #define BLOCKREFTABLE_MAGIC 0x652b137b
31 
32 typedef struct BlockRefTable BlockRefTable;
36 
37 /*
38  * The return value of io_callback_fn should be the number of bytes read
39  * or written. If an error occurs, the functions should report it and
40  * not return. When used as a write callback, short writes should be retried
41  * or treated as errors, so that if the callback returns, the return value
42  * is always the request length.
43  *
44  * report_error_fn should not return.
45  */
46 typedef int (*io_callback_fn) (void *callback_arg, void *data, int length);
47 typedef void (*report_error_fn) (void *callback_arg, char *msg,...) pg_attribute_printf(2, 3);
48 
49 
50 /*
51  * Functions for manipulating an entire in-memory block reference table.
52  */
54 extern void BlockRefTableSetLimitBlock(BlockRefTable *brtab,
55  const RelFileLocator *rlocator,
56  ForkNumber forknum,
57  BlockNumber limit_block);
59  const RelFileLocator *rlocator,
60  ForkNumber forknum,
61  BlockNumber blknum);
62 extern void WriteBlockRefTable(BlockRefTable *brtab,
63  io_callback_fn write_callback,
64  void *write_callback_arg);
65 
67  const RelFileLocator *rlocator,
68  ForkNumber forknum,
69  BlockNumber *limit_block);
71  BlockNumber start_blkno,
72  BlockNumber stop_blkno,
73  BlockNumber *blocks,
74  int nblocks);
75 
76 /*
77  * Functions for reading a block reference table incrementally from disk.
78  */
80  void *read_callback_arg,
81  char *error_filename,
82  report_error_fn error_callback,
83  void *error_callback_arg);
85  RelFileLocator *rlocator,
86  ForkNumber *forknum,
87  BlockNumber *limit_block);
89  BlockNumber *blocks,
90  int nblocks);
92 
93 /*
94  * Functions for writing a block reference table incrementally to disk.
95  *
96  * Note that entries must be written in the proper order, that is, sorted by
97  * database, then tablespace, then relfilenumber, then fork number. Caller
98  * is responsible for supplying data in the correct order. If that seems hard,
99  * use an in-memory BlockRefTable instead.
100  */
102  void *write_callback_arg);
103 extern void BlockRefTableWriteEntry(BlockRefTableWriter *writer,
104  BlockRefTableEntry *entry);
106 
108  ForkNumber forknum);
110  BlockNumber limit_block);
112  ForkNumber forknum,
113  BlockNumber blknum);
114 extern void BlockRefTableFreeEntry(BlockRefTableEntry *entry);
115 
116 #endif /* BLKREFTABLE_H */
void BlockRefTableFreeEntry(BlockRefTableEntry *entry)
Definition: blkreftable.c:1122
BlockRefTableWriter * CreateBlockRefTableWriter(io_callback_fn write_callback, void *write_callback_arg)
Definition: blkreftable.c:790
void(* report_error_fn)(void *callback_arg, char *msg,...) pg_attribute_printf(2
Definition: blkreftable.h:47
BlockRefTableReader * CreateBlockRefTableReader(io_callback_fn read_callback, void *read_callback_arg, char *error_filename, report_error_fn error_callback, void *error_callback_arg)
Definition: blkreftable.c:577
bool BlockRefTableReaderNextRelation(BlockRefTableReader *reader, RelFileLocator *rlocator, ForkNumber *forknum, BlockNumber *limit_block)
Definition: blkreftable.c:613
int BlockRefTableEntryGetBlocks(BlockRefTableEntry *entry, BlockNumber start_blkno, BlockNumber stop_blkno, BlockNumber *blocks, int nblocks)
Definition: blkreftable.c:369
void BlockRefTableMarkBlockModified(BlockRefTable *brtab, const RelFileLocator *rlocator, ForkNumber forknum, BlockNumber blknum)
Definition: blkreftable.c:297
void BlockRefTableWriteEntry(BlockRefTableWriter *writer, BlockRefTableEntry *entry)
Definition: blkreftable.c:817
BlockRefTableEntry * BlockRefTableGetEntry(BlockRefTable *brtab, const RelFileLocator *rlocator, ForkNumber forknum, BlockNumber *limit_block)
Definition: blkreftable.c:340
void BlockRefTableEntryMarkBlockModified(BlockRefTableEntry *entry, ForkNumber forknum, BlockNumber blknum)
Definition: blkreftable.c:965
BlockRefTableEntry * CreateBlockRefTableEntry(RelFileLocator rlocator, ForkNumber forknum)
Definition: blkreftable.c:875
unsigned BlockRefTableReaderGetBlocks(BlockRefTableReader *reader, BlockNumber *blocks, int nblocks)
Definition: blkreftable.c:689
void BlockRefTableSetLimitBlock(BlockRefTable *brtab, const RelFileLocator *rlocator, ForkNumber forknum, BlockNumber limit_block)
Definition: blkreftable.c:262
void BlockRefTableEntrySetLimitBlock(BlockRefTableEntry *entry, BlockNumber limit_block)
Definition: blkreftable.c:894
void WriteBlockRefTable(BlockRefTable *brtab, io_callback_fn write_callback, void *write_callback_arg)
Definition: blkreftable.c:474
void DestroyBlockRefTableReader(BlockRefTableReader *reader)
Definition: blkreftable.c:773
void(*) BlockRefTable CreateEmptyBlockRefTable)(void)
int(* io_callback_fn)(void *callback_arg, void *data, int length)
Definition: blkreftable.h:46
void DestroyBlockRefTableWriter(BlockRefTableWriter *writer)
Definition: blkreftable.c:855
uint32 BlockNumber
Definition: block.h:31
#define pg_attribute_printf(f, a)
Definition: c.h:206
const void * data
ForkNumber
Definition: relpath.h:56