PostgreSQL Source Code git master
bufmgr.h
Go to the documentation of this file.
1/*-------------------------------------------------------------------------
2 *
3 * bufmgr.h
4 * POSTGRES buffer manager definitions.
5 *
6 *
7 * Portions Copyright (c) 1996-2025, 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 "port/pg_iovec.h"
18#include "storage/block.h"
19#include "storage/buf.h"
20#include "storage/bufpage.h"
22#include "utils/relcache.h"
23#include "utils/snapmgr.h"
24
25typedef void *Block;
26
27/*
28 * Possible arguments for GetAccessStrategy().
29 *
30 * If adding a new BufferAccessStrategyType, also add a new IOContext so
31 * IO statistics using this strategy are tracked.
32 */
34{
35 BAS_NORMAL, /* Normal random access */
36 BAS_BULKREAD, /* Large read-only scan (hint bit updates are
37 * ok) */
38 BAS_BULKWRITE, /* Large multi-block write (e.g. COPY IN) */
39 BAS_VACUUM, /* VACUUM */
41
42/* Possible modes for ReadBufferExtended() */
43typedef enum
44{
45 RBM_NORMAL, /* Normal read */
46 RBM_ZERO_AND_LOCK, /* Don't read from disk, caller will
47 * initialize. Also locks the page. */
48 RBM_ZERO_AND_CLEANUP_LOCK, /* Like RBM_ZERO_AND_LOCK, but locks the page
49 * in "cleanup" mode */
50 RBM_ZERO_ON_ERROR, /* Read, but return an all-zeros page on error */
51 RBM_NORMAL_NO_LOG, /* Don't log page as invalid during WAL
52 * replay; otherwise same as RBM_NORMAL */
54
55/*
56 * Type returned by PrefetchBuffer().
57 */
59{
60 Buffer recent_buffer; /* If valid, a hit (recheck needed!) */
61 bool initiated_io; /* If true, a miss resulting in async I/O */
63
64/*
65 * Flags influencing the behaviour of ExtendBufferedRel*
66 */
68{
69 /*
70 * Don't acquire extension lock. This is safe only if the relation isn't
71 * shared, an access exclusive lock is held or if this is the startup
72 * process.
73 */
75
76 /* Is this extension part of recovery? */
78
79 /*
80 * Should the fork be created if it does not currently exist? This likely
81 * only ever makes sense for relation forks.
82 */
84
85 /* Should the first (possibly only) return buffer be returned locked? */
86 EB_LOCK_FIRST = (1 << 3),
87
88 /* Should the smgr size cache be cleared? */
90
91 /* internal flags follow */
92 EB_LOCK_TARGET = (1 << 5),
94
95/*
96 * Some functions identify relations either by relation or smgr +
97 * relpersistence. Used via the BMR_REL()/BMR_SMGR() macros below. This
98 * allows us to use the same function for both recovery and normal operation.
99 */
101{
106
107#define BMR_REL(p_rel) ((BufferManagerRelation){.rel = p_rel})
108#define BMR_SMGR(p_smgr, p_relpersistence) ((BufferManagerRelation){.smgr = p_smgr, .relpersistence = p_relpersistence})
109
110/* Zero out page if reading fails. */
111#define READ_BUFFERS_ZERO_ON_ERROR (1 << 0)
112/* Call smgrprefetch() if I/O necessary. */
113#define READ_BUFFERS_ISSUE_ADVICE (1 << 1)
114
116{
117 /* The following members should be set by the caller. */
118 Relation rel; /* optional */
123
124 /*
125 * The following private members are private state for communication
126 * between StartReadBuffers() and WaitReadBuffers(), initialized only if
127 * an actual read is required, and should not be modified.
128 */
131 int flags;
133};
134
136
137/* forward declared, to avoid having to expose buf_internals.h here */
138struct WritebackContext;
139
140/* forward declared, to avoid including smgr.h here */
141struct SMgrRelationData;
142
143/* in globals.c ... this duplicates miscadmin.h */
144extern PGDLLIMPORT int NBuffers;
145
146/* in bufmgr.c */
150extern PGDLLIMPORT bool track_io_timing;
151
152/* only applicable when prefetching is available */
153#ifdef USE_PREFETCH
154#define DEFAULT_EFFECTIVE_IO_CONCURRENCY 16
155#define DEFAULT_MAINTENANCE_IO_CONCURRENCY 16
156#else
157#define DEFAULT_EFFECTIVE_IO_CONCURRENCY 0
158#define DEFAULT_MAINTENANCE_IO_CONCURRENCY 0
159#endif
162
163#define MAX_IO_COMBINE_LIMIT PG_IOV_MAX
164#define DEFAULT_IO_COMBINE_LIMIT Min(MAX_IO_COMBINE_LIMIT, (128 * 1024) / BLCKSZ)
165extern PGDLLIMPORT int io_combine_limit; /* min of the two GUCs below */
168
172
173/* in buf_init.c */
174extern PGDLLIMPORT char *BufferBlocks;
175
176/* in localbuf.c */
177extern PGDLLIMPORT int NLocBuffer;
180
181/* upper limit for effective_io_concurrency */
182#define MAX_IO_CONCURRENCY 1000
183
184/* special block number for ReadBuffer() */
185#define P_NEW InvalidBlockNumber /* grow the file to get a new page */
186
187/*
188 * Buffer content lock modes (mode argument for LockBuffer())
189 */
190#define BUFFER_LOCK_UNLOCK 0
191#define BUFFER_LOCK_SHARE 1
192#define BUFFER_LOCK_EXCLUSIVE 2
193
194
195/*
196 * prototypes for functions in bufmgr.c
197 */
199 ForkNumber forkNum,
200 BlockNumber blockNum);
202 BlockNumber blockNum);
203extern bool ReadRecentBuffer(RelFileLocator rlocator, ForkNumber forkNum,
204 BlockNumber blockNum, Buffer recent_buffer);
205extern Buffer ReadBuffer(Relation reln, BlockNumber blockNum);
206extern Buffer ReadBufferExtended(Relation reln, ForkNumber forkNum,
208 BufferAccessStrategy strategy);
210 ForkNumber forkNum, BlockNumber blockNum,
212 bool permanent);
213
214extern bool StartReadBuffer(ReadBuffersOperation *operation,
215 Buffer *buffer,
216 BlockNumber blocknum,
217 int flags);
218extern bool StartReadBuffers(ReadBuffersOperation *operation,
219 Buffer *buffers,
220 BlockNumber blockNum,
221 int *nblocks,
222 int flags);
223extern void WaitReadBuffers(ReadBuffersOperation *operation);
224
225extern void ReleaseBuffer(Buffer buffer);
226extern void UnlockReleaseBuffer(Buffer buffer);
227extern bool BufferIsExclusiveLocked(Buffer buffer);
228extern bool BufferIsDirty(Buffer buffer);
229extern void MarkBufferDirty(Buffer buffer);
230extern void IncrBufferRefCount(Buffer buffer);
231extern void CheckBufferIsPinnedOnce(Buffer buffer);
232extern Buffer ReleaseAndReadBuffer(Buffer buffer, Relation relation,
233 BlockNumber blockNum);
234
236 ForkNumber forkNum,
237 BufferAccessStrategy strategy,
238 uint32 flags);
240 ForkNumber fork,
241 BufferAccessStrategy strategy,
242 uint32 flags,
243 uint32 extend_by,
244 Buffer *buffers,
245 uint32 *extended_by);
247 ForkNumber fork,
248 BufferAccessStrategy strategy,
249 uint32 flags,
250 BlockNumber extend_to,
252
253extern void InitBufferManagerAccess(void);
254extern void AtEOXact_Buffers(bool isCommit);
255extern char *DebugPrintBufferRefcount(Buffer buffer);
256extern void CheckPointBuffers(int flags);
259 ForkNumber forkNum);
260extern void FlushOneBuffer(Buffer buffer);
261extern void FlushRelationBuffers(Relation rel);
262extern void FlushRelationsAllBuffers(struct SMgrRelationData **smgrs, int nrels);
263extern void CreateAndCopyRelationData(RelFileLocator src_rlocator,
264 RelFileLocator dst_rlocator,
265 bool permanent);
266extern void FlushDatabaseBuffers(Oid dbid);
267extern void DropRelationBuffers(struct SMgrRelationData *smgr_reln,
268 ForkNumber *forkNum,
269 int nforks, BlockNumber *firstDelBlock);
270extern void DropRelationsAllBuffers(struct SMgrRelationData **smgr_reln,
271 int nlocators);
272extern void DropDatabaseBuffers(Oid dbid);
273
274#define RelationGetNumberOfBlocks(reln) \
275 RelationGetNumberOfBlocksInFork(reln, MAIN_FORKNUM)
276
277extern bool BufferIsPermanent(Buffer buffer);
279extern void BufferGetTag(Buffer buffer, RelFileLocator *rlocator,
280 ForkNumber *forknum, BlockNumber *blknum);
281
282extern void MarkBufferDirtyHint(Buffer buffer, bool buffer_std);
283
284extern void UnlockBuffers(void);
285extern void LockBuffer(Buffer buffer, int mode);
286extern bool ConditionalLockBuffer(Buffer buffer);
287extern void LockBufferForCleanup(Buffer buffer);
288extern bool ConditionalLockBufferForCleanup(Buffer buffer);
289extern bool IsBufferCleanupOK(Buffer buffer);
290extern bool HoldingBufferPinThatDelaysRecovery(void);
291
292extern bool BgBufferSync(struct WritebackContext *wb_context);
293
294extern uint32 GetPinLimit(void);
295extern uint32 GetLocalPinLimit(void);
296extern uint32 GetAdditionalPinLimit(void);
298extern void LimitAdditionalPins(uint32 *additional_pins);
299extern void LimitAdditionalLocalPins(uint32 *additional_pins);
300
301extern bool EvictUnpinnedBuffer(Buffer buf);
302
303/* in buf_init.c */
304extern void BufferManagerShmemInit(void);
305extern Size BufferManagerShmemSize(void);
306
307/* in localbuf.c */
308extern void AtProcExit_LocalBuffers(void);
309
310/* in freelist.c */
311
314 int ring_size_kb);
317
318extern void FreeAccessStrategy(BufferAccessStrategy strategy);
319
320
321/* inline functions */
322
323/*
324 * Although this header file is nominally backend-only, certain frontend
325 * programs like pg_waldump include it. For compilers that emit static
326 * inline functions even when they're unused, that leads to unsatisfied
327 * external references; hence hide these with #ifndef FRONTEND.
328 */
329
330#ifndef FRONTEND
331
332/*
333 * BufferIsValid
334 * True iff the given buffer number is valid (either as a shared
335 * or local buffer).
336 *
337 * Note: For a long time this was defined the same as BufferIsPinned,
338 * that is it would say False if you didn't hold a pin on the buffer.
339 * I believe this was bogus and served only to mask logic errors.
340 * Code should always know whether it has a buffer reference,
341 * independently of the pin state.
342 *
343 * Note: For a further long time this was not quite the inverse of the
344 * BufferIsInvalid() macro, in that it also did sanity checks to verify
345 * that the buffer number was in range. Most likely, this macro was
346 * originally intended only to be used in assertions, but its use has
347 * since expanded quite a bit, and the overhead of making those checks
348 * even in non-assert-enabled builds can be significant. Thus, we've
349 * now demoted the range checks to assertions within the macro itself.
350 */
351static inline bool
353{
354 Assert(bufnum <= NBuffers);
355 Assert(bufnum >= -NLocBuffer);
356
357 return bufnum != InvalidBuffer;
358}
359
360/*
361 * BufferGetBlock
362 * Returns a reference to a disk page image associated with a buffer.
363 *
364 * Note:
365 * Assumes buffer is valid.
366 */
367static inline Block
369{
370 Assert(BufferIsValid(buffer));
371
372 if (BufferIsLocal(buffer))
373 return LocalBufferBlockPointers[-buffer - 1];
374 else
375 return (Block) (BufferBlocks + ((Size) (buffer - 1)) * BLCKSZ);
376}
377
378/*
379 * BufferGetPageSize
380 * Returns the page size within a buffer.
381 *
382 * Notes:
383 * Assumes buffer is valid.
384 *
385 * The buffer can be a raw disk block and need not contain a valid
386 * (formatted) disk page.
387 */
388/* XXX should dig out of buffer descriptor */
389static inline Size
391{
392 Assert(BufferIsValid(buffer));
393 return (Size) BLCKSZ;
394}
395
396/*
397 * BufferGetPage
398 * Returns the page associated with a buffer.
399 */
400static inline Page
402{
403 return (Page) BufferGetBlock(buffer);
404}
405
406#endif /* FRONTEND */
407
408#endif /* BUFMGR_H */
uint32 BlockNumber
Definition: block.h:31
int Buffer
Definition: buf.h:23
#define InvalidBuffer
Definition: buf.h:25
#define BufferIsLocal(buffer)
Definition: buf.h:37
BufferAccessStrategyType
Definition: bufmgr.h:34
@ BAS_BULKREAD
Definition: bufmgr.h:36
@ BAS_NORMAL
Definition: bufmgr.h:35
@ BAS_VACUUM
Definition: bufmgr.h:39
@ BAS_BULKWRITE
Definition: bufmgr.h:38
void CheckBufferIsPinnedOnce(Buffer buffer)
Definition: bufmgr.c:5198
struct BufferManagerRelation BufferManagerRelation
void IncrBufferRefCount(Buffer buffer)
Definition: bufmgr.c:4949
void DropDatabaseBuffers(Oid dbid)
Definition: bufmgr.c:4458
bool BgBufferSync(struct WritebackContext *wb_context)
Definition: bufmgr.c:3252
PGDLLIMPORT int effective_io_concurrency
Definition: bufmgr.c:151
bool BufferIsExclusiveLocked(Buffer buffer)
Definition: bufmgr.c:2535
BlockNumber BufferGetBlockNumber(Buffer buffer)
Definition: bufmgr.c:3795
void DropRelationBuffers(struct SMgrRelationData *smgr_reln, ForkNumber *forkNum, int nforks, BlockNumber *firstDelBlock)
Buffer ReleaseAndReadBuffer(Buffer buffer, Relation relation, BlockNumber blockNum)
Definition: bufmgr.c:2658
PrefetchBufferResult PrefetchBuffer(Relation reln, ForkNumber forkNum, BlockNumber blockNum)
Definition: bufmgr.c:644
int GetAccessStrategyPinLimit(BufferAccessStrategy strategy)
Definition: freelist.c:647
bool StartReadBuffers(ReadBuffersOperation *operation, Buffer *buffers, BlockNumber blockNum, int *nblocks, int flags)
Definition: bufmgr.c:1419
PGDLLIMPORT int bgwriter_flush_after
Definition: bufmgr.c:175
PGDLLIMPORT bool zero_damaged_pages
Definition: bufmgr.c:140
PGDLLIMPORT Block * LocalBufferBlockPointers
Definition: localbuf.c:45
bool IsBufferCleanupOK(Buffer buffer)
Definition: bufmgr.c:5448
PGDLLIMPORT int bgwriter_lru_maxpages
Definition: bufmgr.c:141
Buffer ExtendBufferedRel(BufferManagerRelation bmr, ForkNumber forkNum, BufferAccessStrategy strategy, uint32 flags)
Definition: bufmgr.c:851
uint32 GetAdditionalLocalPinLimit(void)
Definition: localbuf.c:304
static Page BufferGetPage(Buffer buffer)
Definition: bufmgr.h:401
void AtEOXact_Buffers(bool isCommit)
Definition: bufmgr.c:3623
BufferAccessStrategy GetAccessStrategy(BufferAccessStrategyType btype)
Definition: freelist.c:541
BlockNumber ExtendBufferedRelBy(BufferManagerRelation bmr, ForkNumber fork, BufferAccessStrategy strategy, uint32 flags, uint32 extend_by, Buffer *buffers, uint32 *extended_by)
Definition: bufmgr.c:883
struct PrefetchBufferResult PrefetchBufferResult
Size BufferManagerShmemSize(void)
Definition: buf_init.c:159
static Block BufferGetBlock(Buffer buffer)
Definition: bufmgr.h:368
void CreateAndCopyRelationData(RelFileLocator src_rlocator, RelFileLocator dst_rlocator, bool permanent)
Definition: bufmgr.c:4791
PGDLLIMPORT int maintenance_io_concurrency
Definition: bufmgr.c:158
Buffer ExtendBufferedRelTo(BufferManagerRelation bmr, ForkNumber fork, BufferAccessStrategy strategy, uint32 flags, BlockNumber extend_to, ReadBufferMode mode)
Definition: bufmgr.c:915
void AtProcExit_LocalBuffers(void)
Definition: localbuf.c:911
PGDLLIMPORT bool track_io_timing
Definition: bufmgr.c:143
void BufferGetTag(Buffer buffer, RelFileLocator *rlocator, ForkNumber *forknum, BlockNumber *blknum)
Definition: bufmgr.c:3816
PGDLLIMPORT int NBuffers
Definition: globals.c:141
void LimitAdditionalLocalPins(uint32 *additional_pins)
Definition: localbuf.c:312
uint32 GetLocalPinLimit(void)
Definition: localbuf.c:296
BufferAccessStrategy GetAccessStrategyWithSize(BufferAccessStrategyType btype, int ring_size_kb)
Definition: freelist.c:584
char * DebugPrintBufferRefcount(Buffer buffer)
Definition: bufmgr.c:3738
void CheckPointBuffers(int flags)
Definition: bufmgr.c:3781
bool BufferIsDirty(Buffer buffer)
Definition: bufmgr.c:2563
void DropRelationsAllBuffers(struct SMgrRelationData **smgr_reln, int nlocators)
bool BufferIsPermanent(Buffer buffer)
Definition: bufmgr.c:4026
void UnlockBuffers(void)
Definition: bufmgr.c:5123
void * Block
Definition: bufmgr.h:25
PGDLLIMPORT int io_combine_limit_guc
Definition: bufmgr.c:167
int GetAccessStrategyBufferCount(BufferAccessStrategy strategy)
Definition: freelist.c:624
static Size BufferGetPageSize(Buffer buffer)
Definition: bufmgr.h:390
bool ConditionalLockBuffer(Buffer buffer)
Definition: bufmgr.c:5177
BlockNumber RelationGetNumberOfBlocksInFork(Relation relation, ForkNumber forkNum)
Definition: bufmgr.c:3994
void BufferManagerShmemInit(void)
Definition: buf_init.c:67
void ReleaseBuffer(Buffer buffer)
Definition: bufmgr.c:4917
void FreeAccessStrategy(BufferAccessStrategy strategy)
Definition: freelist.c:681
PGDLLIMPORT int32 * LocalRefCount
Definition: localbuf.c:46
XLogRecPtr BufferGetLSNAtomic(Buffer buffer)
Definition: bufmgr.c:4056
bool HoldingBufferPinThatDelaysRecovery(void)
Definition: bufmgr.c:5366
void UnlockReleaseBuffer(Buffer buffer)
Definition: bufmgr.c:4934
void WaitReadBuffers(ReadBuffersOperation *operation)
Definition: bufmgr.c:1463
PrefetchBufferResult PrefetchSharedBuffer(struct SMgrRelationData *smgr_reln, ForkNumber forkNum, BlockNumber blockNum)
void MarkBufferDirty(Buffer buffer)
Definition: bufmgr.c:2596
PGDLLIMPORT int io_combine_limit
Definition: bufmgr.c:166
void LimitAdditionalPins(uint32 *additional_pins)
Definition: bufmgr.c:2192
PGDLLIMPORT int NLocBuffer
Definition: localbuf.c:42
void LockBufferForCleanup(Buffer buffer)
Definition: bufmgr.c:5231
void LockBuffer(Buffer buffer, int mode)
Definition: bufmgr.c:5151
void MarkBufferDirtyHint(Buffer buffer, bool buffer_std)
Definition: bufmgr.c:4981
void FlushRelationBuffers(Relation rel)
Definition: bufmgr.c:4506
ExtendBufferedFlags
Definition: bufmgr.h:68
@ EB_LOCK_TARGET
Definition: bufmgr.h:92
@ EB_CLEAR_SIZE_CACHE
Definition: bufmgr.h:89
@ EB_PERFORMING_RECOVERY
Definition: bufmgr.h:77
@ EB_CREATE_FORK_IF_NEEDED
Definition: bufmgr.h:83
@ EB_SKIP_EXTENSION_LOCK
Definition: bufmgr.h:74
@ EB_LOCK_FIRST
Definition: bufmgr.h:86
Buffer ReadBufferWithoutRelcache(RelFileLocator rlocator, ForkNumber forkNum, BlockNumber blockNum, ReadBufferMode mode, BufferAccessStrategy strategy, bool permanent)
Definition: bufmgr.c:835
PGDLLIMPORT int backend_flush_after
Definition: bufmgr.c:176
PGDLLIMPORT double bgwriter_lru_multiplier
Definition: bufmgr.c:142
bool ReadRecentBuffer(RelFileLocator rlocator, ForkNumber forkNum, BlockNumber blockNum, Buffer recent_buffer)
Definition: bufmgr.c:675
void FlushDatabaseBuffers(Oid dbid)
Definition: bufmgr.c:4855
void FlushRelationsAllBuffers(struct SMgrRelationData **smgrs, int nrels)
bool EvictUnpinnedBuffer(Buffer buf)
Definition: bufmgr.c:6086
PGDLLIMPORT int checkpoint_flush_after
Definition: bufmgr.c:174
bool StartReadBuffer(ReadBuffersOperation *operation, Buffer *buffer, BlockNumber blocknum, int flags)
Definition: bufmgr.c:1438
Buffer ReadBufferExtended(Relation reln, ForkNumber forkNum, BlockNumber blockNum, ReadBufferMode mode, BufferAccessStrategy strategy)
Definition: bufmgr.c:798
void InitBufferManagerAccess(void)
Definition: bufmgr.c:3640
PGDLLIMPORT char * BufferBlocks
Definition: buf_init.c:21
uint32 GetAdditionalPinLimit(void)
Definition: bufmgr.c:2166
PGDLLIMPORT int io_max_combine_limit
Definition: bufmgr.c:168
Buffer ReadBuffer(Relation reln, BlockNumber blockNum)
Definition: bufmgr.c:751
ReadBufferMode
Definition: bufmgr.h:44
@ RBM_ZERO_ON_ERROR
Definition: bufmgr.h:50
@ RBM_ZERO_AND_CLEANUP_LOCK
Definition: bufmgr.h:48
@ RBM_ZERO_AND_LOCK
Definition: bufmgr.h:46
@ RBM_NORMAL
Definition: bufmgr.h:45
@ RBM_NORMAL_NO_LOG
Definition: bufmgr.h:51
bool ConditionalLockBufferForCleanup(Buffer buffer)
Definition: bufmgr.c:5392
uint32 GetPinLimit(void)
Definition: bufmgr.c:2154
void FlushOneBuffer(Buffer buffer)
Definition: bufmgr.c:4897
static bool BufferIsValid(Buffer bufnum)
Definition: bufmgr.h:352
PageData * Page
Definition: bufpage.h:82
#define PGDLLIMPORT
Definition: c.h:1291
int16_t int16
Definition: c.h:497
int32_t int32
Definition: c.h:498
uint32_t uint32
Definition: c.h:502
size_t Size
Definition: c.h:576
Assert(PointerIsAligned(start, uint64))
static PgChecksumMode mode
Definition: pg_checksums.c:55
static char * buf
Definition: pg_test_fsync.c:72
unsigned int Oid
Definition: postgres_ext.h:32
ForkNumber
Definition: relpath.h:56
struct SMgrRelationData * smgr
Definition: bufmgr.h:103
Buffer recent_buffer
Definition: bufmgr.h:60
ForkNumber forknum
Definition: bufmgr.h:121
Buffer * buffers
Definition: bufmgr.h:129
BufferAccessStrategy strategy
Definition: bufmgr.h:122
BlockNumber blocknum
Definition: bufmgr.h:130
struct SMgrRelationData * smgr
Definition: bufmgr.h:119
uint64 XLogRecPtr
Definition: xlogdefs.h:21