From dcf7e1697ba75ce7883ad7c6bc26ba24422eb892 Mon Sep 17 00:00:00 2001 From: Andres Freund Date: Tue, 8 Apr 2025 02:16:51 -0400 Subject: Add pg_buffercache_evict_{relation,all} functions In addition to the added functions, the pg_buffercache_evict() function now shows whether the buffer was flushed. pg_buffercache_evict_relation(): Evicts all shared buffers in a relation at once. pg_buffercache_evict_all(): Evicts all shared buffers at once. Both functions provide mechanism to evict multiple shared buffers at once. They are designed to address the inefficiency of repeatedly calling pg_buffercache_evict() for each individual buffer, which can be time-consuming when dealing with large shared buffer pools. (e.g., ~477ms vs. ~2576ms for 16GB of fully populated shared buffers). These functions are intended for developer testing and debugging purposes and are available to superusers only. Minimal tests for the new functions are included. Also, there was no test for pg_buffercache_evict(), test for this added too. No new extension version is needed, as it was already increased this release by ba2a3c2302f. Author: Nazir Bilal Yavuz Reviewed-by: Andres Freund Reviewed-by: Aidar Imamov Reviewed-by: Joseph Koshakow Discussion: https://postgr.es/m/CAN55FZ0h_YoSqqutxV6DES1RW8ig6wcA8CR9rJk358YRMxZFmw%40mail.gmail.com --- doc/src/sgml/pgbuffercache.sgml | 75 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 68 insertions(+), 7 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/pgbuffercache.sgml b/doc/src/sgml/pgbuffercache.sgml index b5050cd7343..ef5732942f7 100644 --- a/doc/src/sgml/pgbuffercache.sgml +++ b/doc/src/sgml/pgbuffercache.sgml @@ -27,14 +27,24 @@ pg_buffercache_evict + + pg_buffercache_evict_relation + + + + pg_buffercache_evict_all + + This module provides the pg_buffercache_pages() function (wrapped in the pg_buffercache view), pg_buffercache_numa_pages() function (wrapped in the pg_buffercache_numa view), the pg_buffercache_summary() function, the - pg_buffercache_usage_counts() function and - the pg_buffercache_evict() function. + pg_buffercache_usage_counts() function, the + pg_buffercache_evict(), the + pg_buffercache_evict_relation() function and the + pg_buffercache_evict_all() function. @@ -76,6 +86,19 @@ function is restricted to superusers only. + + The pg_buffercache_evict_relation() function allows all + unpinned shared buffers in the relation to be evicted from the buffer pool + given a relation identifier. Use of this function is restricted to + superusers only. + + + + The pg_buffercache_evict_all() function allows all + unpinned shared buffers to be evicted in the buffer pool. Use of this + function is restricted to superusers only. + + The <structname>pg_buffercache</structname> View @@ -452,11 +475,49 @@ The pg_buffercache_evict() function takes a buffer identifier, as shown in the bufferid column of - the pg_buffercache view. It returns true on success, - and false if the buffer wasn't valid, if it couldn't be evicted because it - was pinned, or if it became dirty again after an attempt to write it out. - The result is immediately out of date upon return, as the buffer might - become valid again at any time due to concurrent activity. The function is + the pg_buffercache view. It returns information + about whether the buffer was evicted and flushed. The buffer_evicted + column is true on success, and false if the buffer wasn't valid, if it + couldn't be evicted because it was pinned, or if it became dirty again + after an attempt to write it out. The buffer_flushed column is true if the + buffer was flushed. This does not necessarily mean that buffer was flushed + by us, it might be flushed by someone else. The result is immediately out + of date upon return, as the buffer might become valid again at any time due + to concurrent activity. The function is intended for developer testing + only. + + + + + The <structname>pg_buffercache_evict_relation</structname> Function + + The pg_buffercache_evict_relation() function is very + similar to the pg_buffercache_evict() function. The + difference is that the pg_buffercache_evict_relation() + takes a relation identifier instead of buffer identifier. It tries to + evict all buffers for all forks in that relation. + + It returns the number of evicted buffers, flushed buffers and the number of + buffers that could not be evicted. Flushed buffers haven't necessarily + been flushed by us, they might have been flushed by someone else. The + result is immediately out of date upon return, as buffers might immediately + be read back in due to concurrent activity. The function is intended for + developer testing only. + + + + + The <structname>pg_buffercache_evict_all</structname> Function + + The pg_buffercache_evict_all() function is very + similar to the pg_buffercache_evict() function. The + difference is, the pg_buffercache_evict_all() function + does not take an argument; instead it tries to evict all buffers in the + buffer pool. It returns the number of evicted buffers, flushed buffers and + the number of buffers that could not be evicted. Flushed buffers haven't + necessarily been flushed by us, they might have been flushed by someone + else. The result is immediately out of date upon return, as buffers might + immediately be read back in due to concurrent activity. The function is intended for developer testing only. -- cgit v1.2.3