src/include/common/blkreftable.h

   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;
  33 typedef struct BlockRefTableEntry BlockRefTableEntry;
  34 typedef struct BlockRefTableReader BlockRefTableReader;
  35 typedef struct BlockRefTableWriter BlockRefTableWriter;
  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  */
  53 extern BlockRefTable *CreateEmptyBlockRefTable(void);
  54 extern void BlockRefTableSetLimitBlock(BlockRefTable *brtab,
  55                                                                            const RelFileLocator *rlocator,
  56                                                                            ForkNumber forknum,
  57                                                                            BlockNumber limit_block);
  58 extern void BlockRefTableMarkBlockModified(BlockRefTable *brtab,
  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
  66 extern BlockRefTableEntry *BlockRefTableGetEntry(BlockRefTable *brtab,
  67                                                                                                  const RelFileLocator *rlocator,
  68                                                                                                  ForkNumber forknum,
  69                                                                                                  BlockNumber *limit_block);
  70 extern int      BlockRefTableEntryGetBlocks(BlockRefTableEntry *entry,
  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  */
  79 extern BlockRefTableReader *CreateBlockRefTableReader(io_callback_fn read_callback,
  80                                                                                                           void *read_callback_arg,
  81                                                                                                           char *error_filename,
  82                                                                                                           report_error_fn error_callback,
  83                                                                                                           void *error_callback_arg);
  84 extern bool BlockRefTableReaderNextRelation(BlockRefTableReader *reader,
  85                                                                                         RelFileLocator *rlocator,
  86                                                                                         ForkNumber *forknum,
  87                                                                                         BlockNumber *limit_block);
  88 extern unsigned BlockRefTableReaderGetBlocks(BlockRefTableReader *reader,
  89                                                                                          BlockNumber *blocks,
  90                                                                                          int nblocks);
  91 extern void DestroyBlockRefTableReader(BlockRefTableReader *reader);
  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  */
 101 extern BlockRefTableWriter *CreateBlockRefTableWriter(io_callback_fn write_callback,
 102                                                                                                           void *write_callback_arg);
 103 extern void BlockRefTableWriteEntry(BlockRefTableWriter *writer,
 104                                                                         BlockRefTableEntry *entry);
 105 extern void DestroyBlockRefTableWriter(BlockRefTableWriter *writer);
 106
 107 extern BlockRefTableEntry *CreateBlockRefTableEntry(RelFileLocator rlocator,
 108                                                                                                         ForkNumber forknum);
 109 extern void BlockRefTableEntrySetLimitBlock(BlockRefTableEntry *entry,
 110                                                                                         BlockNumber limit_block);
 111 extern void BlockRefTableEntryMarkBlockModified(BlockRefTableEntry *entry,
 112                                                                                                 ForkNumber forknum,
 113                                                                                                 BlockNumber blknum);
 114 extern void BlockRefTableFreeEntry(BlockRefTableEntry *entry);
 115
 116 #endif                                                  /* BLKREFTABLE_H */