Skip to content

Commit 13453ee

Browse files
macdicemacdice
committed
Add pg_buffercache_evict() function for testing.
When testing buffer pool logic, it is useful to be able to evict arbitrary blocks. This function can be used in SQL queries over the pg_buffercache view to set up a wide range of buffer pool states. Of course, buffer mappings might change concurrently so you might evict a block other than the one you had in mind, and another session might bring it back in at any time. That's OK for the intended purpose of setting up developer testing scenarios, and more complicated interlocking schemes to give stronger guararantees about that would likely be less flexible for actual testing work anyway. Superuser-only. Author: Palak Chaturvedi <chaturvedipalak1911@gmail.com> Author: Thomas Munro <thomas.munro@gmail.com> (docs, small tweaks) Reviewed-by: Nitin Jadhav <nitinjadhavpostgres@gmail.com> Reviewed-by: Andres Freund <andres@anarazel.de> Reviewed-by: Cary Huang <cary.huang@highgo.ca> Reviewed-by: Cédric Villemain <cedric.villemain+pgsql@abcsql.com> Reviewed-by: Jim Nasby <jim.nasby@gmail.com> Reviewed-by: Maxim Orlov <orlovmg@gmail.com> Reviewed-by: Thomas Munro <thomas.munro@gmail.com> Reviewed-by: Melanie Plageman <melanieplageman@gmail.com> Discussion: https://postgr.es/m/CALfch19pW48ZwWzUoRSpsaV9hqt0UPyaBPC4bOZ4W+c7FF566A@mail.gmail.com
1 parent 0ea51ba commit 13453ee

File tree

8 files changed

+127
-8
lines changed

8 files changed

+127
-8
lines changed

‎contrib/pg_buffercache/Makefile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ OBJS = \
88
EXTENSION = pg_buffercache
99
DATA = pg_buffercache--1.2.sql pg_buffercache--1.2--1.3.sql \
1010
pg_buffercache--1.1--1.2.sql pg_buffercache--1.0--1.1.sql \
11-
pg_buffercache--1.3--1.4.sql
11+
pg_buffercache--1.3--1.4.sql pg_buffercache--1.4--1.5.sql
1212
PGFILEDESC = "pg_buffercache - monitoring of shared buffer cache in real-time"
1313

1414
REGRESS = pg_buffercache

‎contrib/pg_buffercache/meson.build‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ install_data(
2222
'pg_buffercache--1.2--1.3.sql',
2323
'pg_buffercache--1.2.sql',
2424
'pg_buffercache--1.3--1.4.sql',
25+
'pg_buffercache--1.4--1.5.sql',
2526
'pg_buffercache.control',
2627
kwargs: contrib_data_args,
2728
)

‎contrib/pg_buffercache/pg_buffercache--1.4--1.5.sql‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
\echo Use "ALTER EXTENSION pg_buffercache UPDATE TO '1.5'" to load this file. \quit
2+
3+
CREATE FUNCTION pg_buffercache_evict(IN int)
4+
RETURNS bool
5+
AS 'MODULE_PATHNAME', 'pg_buffercache_evict'
6+
LANGUAGE C PARALLEL SAFE VOLATILE STRICT;

‎contrib/pg_buffercache/pg_buffercache.control‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# pg_buffercache extension
22
comment = 'examine the shared buffer cache'
3-
default_version = '1.4'
3+
default_version = '1.5'
44
module_pathname = '$libdir/pg_buffercache'
55
relocatable = true

‎contrib/pg_buffercache/pg_buffercache_pages.c‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,7 @@ typedef struct
6363
PG_FUNCTION_INFO_V1(pg_buffercache_pages);
6464
PG_FUNCTION_INFO_V1(pg_buffercache_summary);
6565
PG_FUNCTION_INFO_V1(pg_buffercache_usage_counts);
66+
PG_FUNCTION_INFO_V1(pg_buffercache_evict);
6667

6768
Datum
6869
pg_buffercache_pages(PG_FUNCTION_ARGS)
@@ -347,3 +348,22 @@ pg_buffercache_usage_counts(PG_FUNCTION_ARGS)
347348

348349
return (Datum) 0;
349350
}
351+
352+
/*
353+
* Try to evict a shared buffer.
354+
*/
355+
Datum
356+
pg_buffercache_evict(PG_FUNCTION_ARGS)
357+
{
358+
Buffer buf = PG_GETARG_INT32(0);
359+
360+
if (!superuser())
361+
ereport(ERROR,
362+
(errcode(ERRCODE_INSUFFICIENT_PRIVILEGE),
363+
errmsg("must be superuser to use pg_buffercache_evict function")));
364+
365+
if (buf < 1 || buf > NBuffers)
366+
elog(ERROR, "bad buffer ID: %d", buf);
367+
368+
PG_RETURN_BOOL(EvictUnpinnedBuffer(buf));
369+
}

‎doc/src/sgml/pgbuffercache.sgml‎

Lines changed: 33 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@
1111
<para>
1212
The <filename>pg_buffercache</filename> module provides a means for
1313
examining what's happening in the shared buffer cache in real time.
14+
It also offers a low-level way to evict data from it, for testing
15+
purposes.
1416
</para>
1517

1618
<indexterm>
@@ -21,11 +23,16 @@
2123
<primary>pg_buffercache_summary</primary>
2224
</indexterm>
2325

26+
<indexterm>
27+
<primary>pg_buffercache_evict</primary>
28+
</indexterm>
29+
2430
<para>
2531
This module provides the <function>pg_buffercache_pages()</function>
2632
function (wrapped in the <structname>pg_buffercache</structname> view),
27-
the <function>pg_buffercache_summary()</function> function, and the
28-
<function>pg_buffercache_usage_counts()</function> function.
33+
the <function>pg_buffercache_summary()</function> function, the
34+
<function>pg_buffercache_usage_counts()</function> function and
35+
the <function>pg_buffercache_evict()</function> function.
2936
</para>
3037

3138
<para>
@@ -47,9 +54,15 @@
4754
</para>
4855

4956
<para>
50-
By default, use is restricted to superusers and roles with privileges of the
51-
<literal>pg_monitor</literal> role. Access may be granted to others
52-
using <command>GRANT</command>.
57+
By default, use of the above functions is restricted to superusers and roles
58+
with privileges of the <literal>pg_monitor</literal> role. Access may be
59+
granted to others using <command>GRANT</command>.
60+
</para>
61+
62+
<para>
63+
The <function>pg_buffercache_evict()</function> function allows a block to
64+
be evicted from the buffer pool given a buffer identifier. Use of this
65+
function is restricted to superusers only.
5366
</para>
5467

5568
<sect2 id="pgbuffercache-pg-buffercache">
@@ -351,7 +364,21 @@
351364
</para>
352365
</sect2>
353366

354-
<sect2 id="pgbuffercache-sample-output">
367+
<sect2 id="pgbuffercache-pg-buffercache-evict">
368+
<title>The <structname>pg_buffercache_evict</structname> Function</title>
369+
<para>
370+
The <function>pg_buffercache_evict()</function> function takes a buffer
371+
identifier, as shown in the <structfield>bufferid</structfield> column of
372+
the <structname>pg_buffercache</structname> view. It returns true on success,
373+
and false if the buffer wasn't valid, if it couldn't be evicted because it
374+
was pinned, or if it became dirty again after an attempt to write it out.
375+
The result is immediately out of date upon return, as the buffer might
376+
become valid again at any time due to concurrent activity. The function is
377+
intended for developer testing only.
378+
</para>
379+
</sect2>
380+
381+
<sect2 id="pgbuffercache-sample-output">
355382
<title>Sample Output</title>
356383

357384
<screen>

‎src/backend/storage/buffer/bufmgr.c‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6003,3 +6003,66 @@ ResOwnerPrintBufferPin(Datum res)
60036003
{
60046004
return DebugPrintBufferRefcount(DatumGetInt32(res));
60056005
}
6006+
6007+
/*
6008+
* Try to evict the current block in a shared buffer.
6009+
*
6010+
* This function is intended for testing/development use only!
6011+
*
6012+
* To succeed, the buffer must not be pinned on entry, so if the caller had a
6013+
* particular block in mind, it might already have been replaced by some other
6014+
* block by the time this function runs. It's also unpinned on return, so the
6015+
* buffer might be occupied again by the time control is returned, potentially
6016+
* even by the same block. This inherent raciness without other interlocking
6017+
* makes the function unsuitable for non-testing usage.
6018+
*
6019+
* Returns true if the buffer was valid and it has now been made invalid.
6020+
* Returns false if it wasn't valid, if it couldn't be evicted due to a pin,
6021+
* or if the buffer becomes dirty again while we're trying to write it out.
6022+
*/
6023+
bool
6024+
EvictUnpinnedBuffer(Buffer buf)
6025+
{
6026+
BufferDesc *desc;
6027+
uint32 buf_state;
6028+
bool result;
6029+
6030+
/* Make sure we can pin the buffer. */
6031+
ResourceOwnerEnlarge(CurrentResourceOwner);
6032+
ReservePrivateRefCountEntry();
6033+
6034+
Assert(!BufferIsLocal(buf));
6035+
desc = GetBufferDescriptor(buf - 1);
6036+
6037+
/* Lock the header and check if it's valid. */
6038+
buf_state = LockBufHdr(desc);
6039+
if ((buf_state & BM_VALID) == 0)
6040+
{
6041+
UnlockBufHdr(desc, buf_state);
6042+
return false;
6043+
}
6044+
6045+
/* Check that it's not pinned already. */
6046+
if (BUF_STATE_GET_REFCOUNT(buf_state) > 0)
6047+
{
6048+
UnlockBufHdr(desc, buf_state);
6049+
return false;
6050+
}
6051+
6052+
PinBuffer_Locked(desc); /* releases spinlock */
6053+
6054+
/* If it was dirty, try to clean it once. */
6055+
if (buf_state & BM_DIRTY)
6056+
{
6057+
LWLockAcquire(BufferDescriptorGetContentLock(desc), LW_SHARED);
6058+
FlushBuffer(desc, NULL, IOOBJECT_RELATION, IOCONTEXT_NORMAL);
6059+
LWLockRelease(BufferDescriptorGetContentLock(desc));
6060+
}
6061+
6062+
/* This will return false if it becomes dirty or someone else pins it. */
6063+
result = InvalidateVictimBuffer(desc);
6064+
6065+
UnpinBuffer(desc);
6066+
6067+
return result;
6068+
}

‎src/include/storage/bufmgr.h‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -305,6 +305,8 @@ extern bool BgBufferSync(struct WritebackContext *wb_context);
305305
extern void LimitAdditionalPins(uint32 *additional_pins);
306306
extern void LimitAdditionalLocalPins(uint32 *additional_pins);
307307

308+
extern bool EvictUnpinnedBuffer(Buffer buf);
309+
308310
/* in buf_init.c */
309311
extern void InitBufferPool(void);
310312
extern Size BufferShmemSize(void);

0 commit comments

Comments
 (0)