PostgreSQL Source Code git master
All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
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-2024, 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;
134};
135
137
138/* forward declared, to avoid having to expose buf_internals.h here */
139struct WritebackContext;
140
141/* forward declared, to avoid including smgr.h here */
142struct SMgrRelationData;
143
144/* in globals.c ... this duplicates miscadmin.h */
145extern PGDLLIMPORT int NBuffers;
146
147/* in bufmgr.c */
151extern PGDLLIMPORT bool track_io_timing;
152
153/* only applicable when prefetching is available */
154#ifdef USE_PREFETCH
155#define DEFAULT_EFFECTIVE_IO_CONCURRENCY 1
156#define DEFAULT_MAINTENANCE_IO_CONCURRENCY 10
157#else
158#define DEFAULT_EFFECTIVE_IO_CONCURRENCY 0
159#define DEFAULT_MAINTENANCE_IO_CONCURRENCY 0
160#endif
163
164#define MAX_IO_COMBINE_LIMIT PG_IOV_MAX
165#define DEFAULT_IO_COMBINE_LIMIT Min(MAX_IO_COMBINE_LIMIT, (128 * 1024) / BLCKSZ)
167
171
172/* in buf_init.c */
173extern PGDLLIMPORT char *BufferBlocks;
174
175/* in localbuf.c */
176extern PGDLLIMPORT int NLocBuffer;
179
180/* upper limit for effective_io_concurrency */
181#define MAX_IO_CONCURRENCY 1000
182
183/* special block number for ReadBuffer() */
184#define P_NEW InvalidBlockNumber /* grow the file to get a new page */
185
186/*
187 * Buffer content lock modes (mode argument for LockBuffer())
188 */
189#define BUFFER_LOCK_UNLOCK 0
190#define BUFFER_LOCK_SHARE 1
191#define BUFFER_LOCK_EXCLUSIVE 2
192
193
194/*
195 * prototypes for functions in bufmgr.c
196 */
198 ForkNumber forkNum,
199 BlockNumber blockNum);
201 BlockNumber blockNum);
202extern bool ReadRecentBuffer(RelFileLocator rlocator, ForkNumber forkNum,
203 BlockNumber blockNum, Buffer recent_buffer);
204extern Buffer ReadBuffer(Relation reln, BlockNumber blockNum);
205extern Buffer ReadBufferExtended(Relation reln, ForkNumber forkNum,
207 BufferAccessStrategy strategy);
209 ForkNumber forkNum, BlockNumber blockNum,
211 bool permanent);
212
213extern bool StartReadBuffer(ReadBuffersOperation *operation,
214 Buffer *buffer,
215 BlockNumber blocknum,
216 int flags);
217extern bool StartReadBuffers(ReadBuffersOperation *operation,
218 Buffer *buffers,
219 BlockNumber blockNum,
220 int *nblocks,
221 int flags);
222extern void WaitReadBuffers(ReadBuffersOperation *operation);
223
224extern void ReleaseBuffer(Buffer buffer);
225extern void UnlockReleaseBuffer(Buffer buffer);
226extern bool BufferIsExclusiveLocked(Buffer buffer);
227extern bool BufferIsDirty(Buffer buffer);
228extern void MarkBufferDirty(Buffer buffer);
229extern void IncrBufferRefCount(Buffer buffer);
230extern void CheckBufferIsPinnedOnce(Buffer buffer);
231extern Buffer ReleaseAndReadBuffer(Buffer buffer, Relation relation,
232 BlockNumber blockNum);
233
235 ForkNumber forkNum,
236 BufferAccessStrategy strategy,
237 uint32 flags);
239 ForkNumber fork,
240 BufferAccessStrategy strategy,
241 uint32 flags,
242 uint32 extend_by,
243 Buffer *buffers,
244 uint32 *extended_by);
246 ForkNumber fork,
247 BufferAccessStrategy strategy,
248 uint32 flags,
249 BlockNumber extend_to,
251
252extern void InitBufferManagerAccess(void);
253extern void AtEOXact_Buffers(bool isCommit);
254extern char *DebugPrintBufferRefcount(Buffer buffer);
255extern void CheckPointBuffers(int flags);
258 ForkNumber forkNum);
259extern void FlushOneBuffer(Buffer buffer);
260extern void FlushRelationBuffers(Relation rel);
261extern void FlushRelationsAllBuffers(struct SMgrRelationData **smgrs, int nrels);
262extern void CreateAndCopyRelationData(RelFileLocator src_rlocator,
263 RelFileLocator dst_rlocator,
264 bool permanent);
265extern void FlushDatabaseBuffers(Oid dbid);
266extern void DropRelationBuffers(struct SMgrRelationData *smgr_reln,
267 ForkNumber *forkNum,
268 int nforks, BlockNumber *firstDelBlock);
269extern void DropRelationsAllBuffers(struct SMgrRelationData **smgr_reln,
270 int nlocators);
271extern void DropDatabaseBuffers(Oid dbid);
272
273#define RelationGetNumberOfBlocks(reln) \
274 RelationGetNumberOfBlocksInFork(reln, MAIN_FORKNUM)
275
276extern bool BufferIsPermanent(Buffer buffer);
278
279#ifdef NOT_USED
280extern void PrintPinnedBufs(void);
281#endif
282extern void BufferGetTag(Buffer buffer, RelFileLocator *rlocator,
283 ForkNumber *forknum, BlockNumber *blknum);
284
285extern void MarkBufferDirtyHint(Buffer buffer, bool buffer_std);
286
287extern void UnlockBuffers(void);
288extern void LockBuffer(Buffer buffer, int mode);
289extern bool ConditionalLockBuffer(Buffer buffer);
290extern void LockBufferForCleanup(Buffer buffer);
291extern bool ConditionalLockBufferForCleanup(Buffer buffer);
292extern bool IsBufferCleanupOK(Buffer buffer);
293extern bool HoldingBufferPinThatDelaysRecovery(void);
294
295extern bool BgBufferSync(struct WritebackContext *wb_context);
296
297extern void LimitAdditionalPins(uint32 *additional_pins);
298extern void LimitAdditionalLocalPins(uint32 *additional_pins);
299
300extern bool EvictUnpinnedBuffer(Buffer buf);
301
302/* in buf_init.c */
303extern void BufferManagerShmemInit(void);
304extern Size BufferManagerShmemSize(void);
305
306/* in localbuf.c */
307extern void AtProcExit_LocalBuffers(void);
308
309/* in freelist.c */
310
313 int ring_size_kb);
316
317extern void FreeAccessStrategy(BufferAccessStrategy strategy);
318
319
320/* inline functions */
321
322/*
323 * Although this header file is nominally backend-only, certain frontend
324 * programs like pg_waldump include it. For compilers that emit static
325 * inline functions even when they're unused, that leads to unsatisfied
326 * external references; hence hide these with #ifndef FRONTEND.
327 */
328
329#ifndef FRONTEND
330
331/*
332 * BufferIsValid
333 * True iff the given buffer number is valid (either as a shared
334 * or local buffer).
335 *
336 * Note: For a long time this was defined the same as BufferIsPinned,
337 * that is it would say False if you didn't hold a pin on the buffer.
338 * I believe this was bogus and served only to mask logic errors.
339 * Code should always know whether it has a buffer reference,
340 * independently of the pin state.
341 *
342 * Note: For a further long time this was not quite the inverse of the
343 * BufferIsInvalid() macro, in that it also did sanity checks to verify
344 * that the buffer number was in range. Most likely, this macro was
345 * originally intended only to be used in assertions, but its use has
346 * since expanded quite a bit, and the overhead of making those checks
347 * even in non-assert-enabled builds can be significant. Thus, we've
348 * now demoted the range checks to assertions within the macro itself.
349 */
350static inline bool
352{
353 Assert(bufnum <= NBuffers);
354 Assert(bufnum >= -NLocBuffer);
355
356 return bufnum != InvalidBuffer;
357}
358
359/*
360 * BufferGetBlock
361 * Returns a reference to a disk page image associated with a buffer.
362 *
363 * Note:
364 * Assumes buffer is valid.
365 */
366static inline Block
368{
369 Assert(BufferIsValid(buffer));
370
371 if (BufferIsLocal(buffer))
372 return LocalBufferBlockPointers[-buffer - 1];
373 else
374 return (Block) (BufferBlocks + ((Size) (buffer - 1)) * BLCKSZ);
375}
376
377/*
378 * BufferGetPageSize
379 * Returns the page size within a buffer.
380 *
381 * Notes:
382 * Assumes buffer is valid.
383 *
384 * The buffer can be a raw disk block and need not contain a valid
385 * (formatted) disk page.
386 */
387/* XXX should dig out of buffer descriptor */
388static inline Size
390{
391 AssertMacro(BufferIsValid(buffer));
392 return (Size) BLCKSZ;
393}
394
395/*
396 * BufferGetPage
397 * Returns the page associated with a buffer.
398 */
399static inline Page
401{
402 return (Page) BufferGetBlock(buffer);
403}
404
405#endif /* FRONTEND */
406
407#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:5205
struct BufferManagerRelation BufferManagerRelation
void IncrBufferRefCount(Buffer buffer)
Definition: bufmgr.c:4956
void DropDatabaseBuffers(Oid dbid)
Definition: bufmgr.c:4386
bool BgBufferSync(struct WritebackContext *wb_context)
Definition: bufmgr.c:3188
PGDLLIMPORT int effective_io_concurrency
Definition: bufmgr.c:151
bool BufferIsExclusiveLocked(Buffer buffer)
Definition: bufmgr.c:2471
BlockNumber BufferGetBlockNumber(Buffer buffer)
Definition: bufmgr.c:3724
void DropRelationBuffers(struct SMgrRelationData *smgr_reln, ForkNumber *forkNum, int nforks, BlockNumber *firstDelBlock)
Buffer ReleaseAndReadBuffer(Buffer buffer, Relation relation, BlockNumber blockNum)
Definition: bufmgr.c:2594
PrefetchBufferResult PrefetchBuffer(Relation reln, ForkNumber forkNum, BlockNumber blockNum)
Definition: bufmgr.c:639
int GetAccessStrategyPinLimit(BufferAccessStrategy strategy)
Definition: freelist.c:647
bool StartReadBuffers(ReadBuffersOperation *operation, Buffer *buffers, BlockNumber blockNum, int *nblocks, int flags)
Definition: bufmgr.c:1367
PGDLLIMPORT int bgwriter_flush_after
Definition: bufmgr.c:172
PGDLLIMPORT bool zero_damaged_pages
Definition: bufmgr.c:140
PGDLLIMPORT Block * LocalBufferBlockPointers
Definition: localbuf.c:45
bool IsBufferCleanupOK(Buffer buffer)
Definition: bufmgr.c:5455
PGDLLIMPORT int bgwriter_lru_maxpages
Definition: bufmgr.c:141
Buffer ExtendBufferedRel(BufferManagerRelation bmr, ForkNumber forkNum, BufferAccessStrategy strategy, uint32 flags)
Definition: bufmgr.c:846
static Page BufferGetPage(Buffer buffer)
Definition: bufmgr.h:400
void AtEOXact_Buffers(bool isCommit)
Definition: bufmgr.c:3559
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:878
struct PrefetchBufferResult PrefetchBufferResult
Size BufferManagerShmemSize(void)
Definition: buf_init.c:159
static Block BufferGetBlock(Buffer buffer)
Definition: bufmgr.h:367
void CreateAndCopyRelationData(RelFileLocator src_rlocator, RelFileLocator dst_rlocator, bool permanent)
Definition: bufmgr.c:4798
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:910
void AtProcExit_LocalBuffers(void)
Definition: localbuf.c:830
PGDLLIMPORT bool track_io_timing
Definition: bufmgr.c:143
void BufferGetTag(Buffer buffer, RelFileLocator *rlocator, ForkNumber *forknum, BlockNumber *blknum)
Definition: bufmgr.c:3745
PGDLLIMPORT int NBuffers
Definition: globals.c:141
void LimitAdditionalLocalPins(uint32 *additional_pins)
Definition: localbuf.c:290
BufferAccessStrategy GetAccessStrategyWithSize(BufferAccessStrategyType btype, int ring_size_kb)
Definition: freelist.c:584
char * DebugPrintBufferRefcount(Buffer buffer)
Definition: bufmgr.c:3665
void CheckPointBuffers(int flags)
Definition: bufmgr.c:3710
bool BufferIsDirty(Buffer buffer)
Definition: bufmgr.c:2500
void DropRelationsAllBuffers(struct SMgrRelationData **smgr_reln, int nlocators)
bool BufferIsPermanent(Buffer buffer)
Definition: bufmgr.c:3955
void UnlockBuffers(void)
Definition: bufmgr.c:5130
void * Block
Definition: bufmgr.h:25
int GetAccessStrategyBufferCount(BufferAccessStrategy strategy)
Definition: freelist.c:624
static Size BufferGetPageSize(Buffer buffer)
Definition: bufmgr.h:389
bool ConditionalLockBuffer(Buffer buffer)
Definition: bufmgr.c:5184
BlockNumber RelationGetNumberOfBlocksInFork(Relation relation, ForkNumber forkNum)
Definition: bufmgr.c:3923
void BufferManagerShmemInit(void)
Definition: buf_init.c:67
void ReleaseBuffer(Buffer buffer)
Definition: bufmgr.c:4924
void FreeAccessStrategy(BufferAccessStrategy strategy)
Definition: freelist.c:681
PGDLLIMPORT int32 * LocalRefCount
Definition: localbuf.c:46
XLogRecPtr BufferGetLSNAtomic(Buffer buffer)
Definition: bufmgr.c:3985
bool HoldingBufferPinThatDelaysRecovery(void)
Definition: bufmgr.c:5373
void UnlockReleaseBuffer(Buffer buffer)
Definition: bufmgr.c:4941
void WaitReadBuffers(ReadBuffersOperation *operation)
Definition: bufmgr.c:1410
PrefetchBufferResult PrefetchSharedBuffer(struct SMgrRelationData *smgr_reln, ForkNumber forkNum, BlockNumber blockNum)
void MarkBufferDirty(Buffer buffer)
Definition: bufmgr.c:2532
PGDLLIMPORT int io_combine_limit
Definition: bufmgr.c:165
void LimitAdditionalPins(uint32 *additional_pins)
Definition: bufmgr.c:2116
PGDLLIMPORT int NLocBuffer
Definition: localbuf.c:42
void LockBufferForCleanup(Buffer buffer)
Definition: bufmgr.c:5238
void LockBuffer(Buffer buffer, int mode)
Definition: bufmgr.c:5158
void MarkBufferDirtyHint(Buffer buffer, bool buffer_std)
Definition: bufmgr.c:4988
void FlushRelationBuffers(Relation rel)
Definition: bufmgr.c:4492
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:830
PGDLLIMPORT int backend_flush_after
Definition: bufmgr.c:173
PGDLLIMPORT double bgwriter_lru_multiplier
Definition: bufmgr.c:142
bool ReadRecentBuffer(RelFileLocator rlocator, ForkNumber forkNum, BlockNumber blockNum, Buffer recent_buffer)
Definition: bufmgr.c:670
void FlushDatabaseBuffers(Oid dbid)
Definition: bufmgr.c:4862
void FlushRelationsAllBuffers(struct SMgrRelationData **smgrs, int nrels)
bool EvictUnpinnedBuffer(Buffer buf)
Definition: bufmgr.c:6101
PGDLLIMPORT int checkpoint_flush_after
Definition: bufmgr.c:171
bool StartReadBuffer(ReadBuffersOperation *operation, Buffer *buffer, BlockNumber blocknum, int flags)
Definition: bufmgr.c:1382
Buffer ReadBufferExtended(Relation reln, ForkNumber forkNum, BlockNumber blockNum, ReadBufferMode mode, BufferAccessStrategy strategy)
Definition: bufmgr.c:793
void InitBufferManagerAccess(void)
Definition: bufmgr.c:3576
PGDLLIMPORT char * BufferBlocks
Definition: buf_init.c:21
Buffer ReadBuffer(Relation reln, BlockNumber blockNum)
Definition: bufmgr.c:746
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:5399
void FlushOneBuffer(Buffer buffer)
Definition: bufmgr.c:4904
static bool BufferIsValid(Buffer bufnum)
Definition: bufmgr.h:351
Pointer Page
Definition: bufpage.h:81
#define AssertMacro(condition)
Definition: c.h:813
#define PGDLLIMPORT
Definition: c.h:1274
#define Assert(condition)
Definition: c.h:812
int16_t int16
Definition: c.h:480
int32_t int32
Definition: c.h:481
uint32_t uint32
Definition: c.h:485
size_t Size
Definition: c.h:559
static PgChecksumMode mode
Definition: pg_checksums.c:55
static char * buf
Definition: pg_test_fsync.c:72
unsigned int Oid
Definition: postgres_ext.h:31
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
int16 io_buffers_len
Definition: bufmgr.h:133
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