src/include/storage/bufmgr.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * bufmgr.h
   4  *        POSTGRES buffer manager definitions.
   5  *
   6  *
   7  * Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group
   8  * Portions Copyright (c) 1994, Regents of the University of California
   9  *
  10  * src/include/storage/bufmgr.h
  11  *
  12  *-------------------------------------------------------------------------
  13  */
  14 #ifndef BUFMGR_H
  15 #define BUFMGR_H
  16
  17 #include "storage/block.h"
  18 #include "storage/buf.h"
  19 #include "storage/bufpage.h"
  20 #include "storage/relfilelocator.h"
  21 #include "utils/relcache.h"
  22 #include "utils/snapmgr.h"
  23
  24 typedef void *Block;
  25
  26 /* Possible arguments for GetAccessStrategy() */
  27 typedef enum BufferAccessStrategyType
  28 {
  29         BAS_NORMAL,                                     /* Normal random access */
  30         BAS_BULKREAD,                           /* Large read-only scan (hint bit updates are
  31                                                                  * ok) */
  32         BAS_BULKWRITE,                          /* Large multi-block write (e.g. COPY IN) */
  33         BAS_VACUUM                                      /* VACUUM */
  34 } BufferAccessStrategyType;
  35
  36 /* Possible modes for ReadBufferExtended() */
  37 typedef enum
  38 {
  39         RBM_NORMAL,                                     /* Normal read */
  40         RBM_ZERO_AND_LOCK,                      /* Don't read from disk, caller will
  41                                                                  * initialize. Also locks the page. */
  42         RBM_ZERO_AND_CLEANUP_LOCK,      /* Like RBM_ZERO_AND_LOCK, but locks the page
  43                                                                  * in "cleanup" mode */
  44         RBM_ZERO_ON_ERROR,                      /* Read, but return an all-zeros page on error */
  45         RBM_NORMAL_NO_LOG                       /* Don't log page as invalid during WAL
  46                                                                  * replay; otherwise same as RBM_NORMAL */
  47 } ReadBufferMode;
  48
  49 /*
  50  * Type returned by PrefetchBuffer().
  51  */
  52 typedef struct PrefetchBufferResult
  53 {
  54         Buffer          recent_buffer;  /* If valid, a hit (recheck needed!) */
  55         bool            initiated_io;   /* If true, a miss resulting in async I/O */
  56 } PrefetchBufferResult;
  57
  58 /* forward declared, to avoid having to expose buf_internals.h here */
  59 struct WritebackContext;
  60
  61 /* forward declared, to avoid including smgr.h here */
  62 struct SMgrRelationData;
  63
  64 /* in globals.c ... this duplicates miscadmin.h */
  65 extern PGDLLIMPORT int NBuffers;
  66
  67 /* in bufmgr.c */
  68 extern PGDLLIMPORT bool zero_damaged_pages;
  69 extern PGDLLIMPORT int bgwriter_lru_maxpages;
  70 extern PGDLLIMPORT double bgwriter_lru_multiplier;
  71 extern PGDLLIMPORT bool track_io_timing;
  72 extern PGDLLIMPORT int effective_io_concurrency;
  73 extern PGDLLIMPORT int maintenance_io_concurrency;
  74
  75 extern PGDLLIMPORT int checkpoint_flush_after;
  76 extern PGDLLIMPORT int backend_flush_after;
  77 extern PGDLLIMPORT int bgwriter_flush_after;
  78
  79 /* in buf_init.c */
  80 extern PGDLLIMPORT char *BufferBlocks;
  81
  82 /* in localbuf.c */
  83 extern PGDLLIMPORT int NLocBuffer;
  84 extern PGDLLIMPORT Block *LocalBufferBlockPointers;
  85 extern PGDLLIMPORT int32 *LocalRefCount;
  86
  87 /* upper limit for effective_io_concurrency */
  88 #define MAX_IO_CONCURRENCY 1000
  89
  90 /* special block number for ReadBuffer() */
  91 #define P_NEW   InvalidBlockNumber      /* grow the file to get a new page */
  92
  93 /*
  94  * Buffer content lock modes (mode argument for LockBuffer())
  95  */
  96 #define BUFFER_LOCK_UNLOCK              0
  97 #define BUFFER_LOCK_SHARE               1
  98 #define BUFFER_LOCK_EXCLUSIVE   2
  99
 100
 101 /*
 102  * prototypes for functions in bufmgr.c
 103  */
 104 extern PrefetchBufferResult PrefetchSharedBuffer(struct SMgrRelationData *smgr_reln,
 105                                                                                                  ForkNumber forkNum,
 106                                                                                                  BlockNumber blockNum);
 107 extern PrefetchBufferResult PrefetchBuffer(Relation reln, ForkNumber forkNum,
 108                                                                                    BlockNumber blockNum);
 109 extern bool ReadRecentBuffer(RelFileLocator rlocator, ForkNumber forkNum,
 110                                                          BlockNumber blockNum, Buffer recent_buffer);
 111 extern Buffer ReadBuffer(Relation reln, BlockNumber blockNum);
 112 extern Buffer ReadBufferExtended(Relation reln, ForkNumber forkNum,
 113                                                                  BlockNumber blockNum, ReadBufferMode mode,
 114                                                                  BufferAccessStrategy strategy);
 115 extern Buffer ReadBufferWithoutRelcache(RelFileLocator rlocator,
 116                                                                                 ForkNumber forkNum, BlockNumber blockNum,
 117                                                                                 ReadBufferMode mode, BufferAccessStrategy strategy,
 118                                                                                 bool permanent);
 119 extern void ReleaseBuffer(Buffer buffer);
 120 extern void UnlockReleaseBuffer(Buffer buffer);
 121 extern void MarkBufferDirty(Buffer buffer);
 122 extern void IncrBufferRefCount(Buffer buffer);
 123 extern Buffer ReleaseAndReadBuffer(Buffer buffer, Relation relation,
 124                                                                    BlockNumber blockNum);
 125
 126 extern void InitBufferPoolAccess(void);
 127 extern void AtEOXact_Buffers(bool isCommit);
 128 extern void PrintBufferLeakWarning(Buffer buffer);
 129 extern void CheckPointBuffers(int flags);
 130 extern BlockNumber BufferGetBlockNumber(Buffer buffer);
 131 extern BlockNumber RelationGetNumberOfBlocksInFork(Relation relation,
 132                                                                                                    ForkNumber forkNum);
 133 extern void FlushOneBuffer(Buffer buffer);
 134 extern void FlushRelationBuffers(Relation rel);
 135 extern void FlushRelationsAllBuffers(struct SMgrRelationData **smgrs, int nrels);
 136 extern void CreateAndCopyRelationData(RelFileLocator src_rlocator,
 137                                                                           RelFileLocator dst_rlocator,
 138                                                                           bool permanent);
 139 extern void FlushDatabaseBuffers(Oid dbid);
 140 extern void DropRelationBuffers(struct SMgrRelationData *smgr_reln,
 141                                                                 ForkNumber *forkNum,
 142                                                                 int nforks, BlockNumber *firstDelBlock);
 143 extern void DropRelationsAllBuffers(struct SMgrRelationData **smgr_reln,
 144                                                                         int nlocators);
 145 extern void DropDatabaseBuffers(Oid dbid);
 146
 147 #define RelationGetNumberOfBlocks(reln) \
 148         RelationGetNumberOfBlocksInFork(reln, MAIN_FORKNUM)
 149
 150 extern bool BufferIsPermanent(Buffer buffer);
 151 extern XLogRecPtr BufferGetLSNAtomic(Buffer buffer);
 152
 153 #ifdef NOT_USED
 154 extern void PrintPinnedBufs(void);
 155 #endif
 156 extern void BufferGetTag(Buffer buffer, RelFileLocator *rlocator,
 157                                                  ForkNumber *forknum, BlockNumber *blknum);
 158
 159 extern void MarkBufferDirtyHint(Buffer buffer, bool buffer_std);
 160
 161 extern void UnlockBuffers(void);
 162 extern void LockBuffer(Buffer buffer, int mode);
 163 extern bool ConditionalLockBuffer(Buffer buffer);
 164 extern void LockBufferForCleanup(Buffer buffer);
 165 extern bool ConditionalLockBufferForCleanup(Buffer buffer);
 166 extern bool IsBufferCleanupOK(Buffer buffer);
 167 extern bool HoldingBufferPinThatDelaysRecovery(void);
 168
 169 extern void AbortBufferIO(void);
 170
 171 extern void BufmgrCommit(void);
 172 extern bool BgBufferSync(struct WritebackContext *wb_context);
 173
 174 extern void TestForOldSnapshot_impl(Snapshot snapshot, Relation relation);
 175
 176 /* in buf_init.c */
 177 extern void InitBufferPool(void);
 178 extern Size BufferShmemSize(void);
 179
 180 /* in localbuf.c */
 181 extern void AtProcExit_LocalBuffers(void);
 182
 183 /* in freelist.c */
 184 extern BufferAccessStrategy GetAccessStrategy(BufferAccessStrategyType btype);
 185 extern void FreeAccessStrategy(BufferAccessStrategy strategy);
 186
 187
 188 /* inline functions */
 189
 190 /*
 191  * Although this header file is nominally backend-only, certain frontend
 192  * programs like pg_waldump include it.  For compilers that emit static
 193  * inline functions even when they're unused, that leads to unsatisfied
 194  * external references; hence hide these with #ifndef FRONTEND.
 195  */
 196
 197 #ifndef FRONTEND
 198
 199 /*
 200  * BufferIsValid
 201  *              True iff the given buffer number is valid (either as a shared
 202  *              or local buffer).
 203  *
 204  * Note: For a long time this was defined the same as BufferIsPinned,
 205  * that is it would say False if you didn't hold a pin on the buffer.
 206  * I believe this was bogus and served only to mask logic errors.
 207  * Code should always know whether it has a buffer reference,
 208  * independently of the pin state.
 209  *
 210  * Note: For a further long time this was not quite the inverse of the
 211  * BufferIsInvalid() macro, in that it also did sanity checks to verify
 212  * that the buffer number was in range.  Most likely, this macro was
 213  * originally intended only to be used in assertions, but its use has
 214  * since expanded quite a bit, and the overhead of making those checks
 215  * even in non-assert-enabled builds can be significant.  Thus, we've
 216  * now demoted the range checks to assertions within the macro itself.
 217  */
 218 static inline bool
 219 BufferIsValid(Buffer bufnum)
 220 {
 221         Assert(bufnum <= NBuffers);
 222         Assert(bufnum >= -NLocBuffer);
 223
 224         return bufnum != InvalidBuffer;
 225 }
 226
 227 /*
 228  * BufferGetBlock
 229  *              Returns a reference to a disk page image associated with a buffer.
 230  *
 231  * Note:
 232  *              Assumes buffer is valid.
 233  */
 234 static inline Block
 235 BufferGetBlock(Buffer buffer)
 236 {
 237         Assert(BufferIsValid(buffer));
 238
 239         if (BufferIsLocal(buffer))
 240                 return LocalBufferBlockPointers[-buffer - 1];
 241         else
 242                 return (Block) (BufferBlocks + ((Size) (buffer - 1)) * BLCKSZ);
 243 }
 244
 245 /*
 246  * BufferGetPageSize
 247  *              Returns the page size within a buffer.
 248  *
 249  * Notes:
 250  *              Assumes buffer is valid.
 251  *
 252  *              The buffer can be a raw disk block and need not contain a valid
 253  *              (formatted) disk page.
 254  */
 255 /* XXX should dig out of buffer descriptor */
 256 static inline Size
 257 BufferGetPageSize(Buffer buffer)
 258 {
 259         AssertMacro(BufferIsValid(buffer));
 260         return (Size) BLCKSZ;
 261 }
 262
 263 /*
 264  * BufferGetPage
 265  *              Returns the page associated with a buffer.
 266  *
 267  * When this is called as part of a scan, there may be a need for a nearby
 268  * call to TestForOldSnapshot().  See the definition of that for details.
 269  */
 270 static inline Page
 271 BufferGetPage(Buffer buffer)
 272 {
 273         return (Page) BufferGetBlock(buffer);
 274 }
 275
 276 /*
 277  * Check whether the given snapshot is too old to have safely read the given
 278  * page from the given table.  If so, throw a "snapshot too old" error.
 279  *
 280  * This test generally needs to be performed after every BufferGetPage() call
 281  * that is executed as part of a scan.  It is not needed for calls made for
 282  * modifying the page (for example, to position to the right place to insert a
 283  * new index tuple or for vacuuming).  It may also be omitted where calls to
 284  * lower-level functions will have already performed the test.
 285  *
 286  * Note that a NULL snapshot argument is allowed and causes a fast return
 287  * without error; this is to support call sites which can be called from
 288  * either scans or index modification areas.
 289  *
 290  * For best performance, keep the tests that are fastest and/or most likely to
 291  * exclude a page from old snapshot testing near the front.
 292  */
 293 static inline void
 294 TestForOldSnapshot(Snapshot snapshot, Relation relation, Page page)
 295 {
 296         Assert(relation != NULL);
 297
 298         if (old_snapshot_threshold >= 0
 299                 && (snapshot) != NULL
 300                 && ((snapshot)->snapshot_type == SNAPSHOT_MVCC
 301                         || (snapshot)->snapshot_type == SNAPSHOT_TOAST)
 302                 && !XLogRecPtrIsInvalid((snapshot)->lsn)
 303                 && PageGetLSN(page) > (snapshot)->lsn)
 304                 TestForOldSnapshot_impl(snapshot, relation);
 305 }
 306
 307 #endif                                                  /* FRONTEND */
 308
 309 #endif                                                  /* BUFMGR_H */