Subject: bgwriter_lru_multiplier blurbs inconsistent

From: Alvaro Herrera <[email-masked]>
Date: Sun, 20 Jan 2008 16:55:19 -0300

Is the bgwriter_lru_multiplier parameter a limit on the number to scan
or to write?  GUC and docs seem to contradict one another.  GUC says

#: utils/misc/guc.c:1834
#, fuzzy
msgid "Background writer multiplier on average buffers to scan per round."

The docs say

         Unless limited by <varname>bgwriter_lru_maxpages</>, the number
         of dirty buffers written in each round is determined by reference
         to the number of new buffers that have been needed by server
         processes during recent rounds.  This number is multiplied by
         <varname>bgwriter_lru_multiplier</> to arrive at the estimate
         of the number of buffers that will be needed during the next round.

Which one is correct?  Do we need a correction of either?

-- 
Alvaro Herrera                                http://www.CommandPrompt.com/
The PostgreSQL Company - Command Prompt, Inc.

---

From: Tom Lane <[email-masked]>
Date: Sun, 20 Jan 2008 15:08:40 -0500

> Which one is correct?  Do we need a correction of either?

We multiply the average number of new buffers used per round by the
multiplier, and use that as the target for the number of clean buffers
to have in front of the sweep hand.  Any of these that are dirty will
be written (until we exceed maxpages written).  So it's the number to scan.

I don't find either the docs or the msgid to be wrong, exactly; but if
you have a proposal for better wording, I'm all ears.

			regards, tom lane

---

From: Greg Smith <[email-masked]>
Date: Sun, 20 Jan 2008 15:55:54 -0500 (EST)

On Sun, 20 Jan 2008, Alvaro Herrera wrote:

> or to write?  GUC and docs seem to contradict one another.

It adjusts the target for how many clean buffers it wants to either find 
or create.  This always increases the number of buffers scanned, and 
that's what the GUC description says.

Since a clean buffer can either be a) a reusable candidate found by 
scanning or b) a buffer that is written, on average it's adjusting up the 
number of writes as well.  But it's not guaranteed to--you could have a 
case where it just found all the buffers it needed and never wrote a 
single one.

>         of the number of buffers that will be needed during the next round.

There is nothing incorrect here, it's just not as clear as it could be. 
Here's a V2 that tries to clear that up:

Unless limited by <varname>bgwriter_lru_maxpages</>, the number of dirty 
buffers written in each round is based on the number of new buffers that 
have been needed by server processes during recent rounds.  The recent 
need is multiplied by <varname>bgwriter_lru_multiplier</> to arrive at the 
estimate of the number of buffers that will be needed during the next 
round.  Buffers are written to meet that need if there aren't enough 
reusable ones found while scanning.

--
* Greg Smith [email-masked] http://www.gregsmith.com Baltimore, MD

---

From: Tom Lane <[email-masked]>
Date: Sun, 20 Jan 2008 17:05:22 -0500

> reusable ones found while scanning.

I think the main problem is the qualifying clause up front in a place
of prominence.  Here's a V3 try:

The number of dirty buffers written in each round is based on the number
of new buffers that have been needed by server processes during recent
rounds.  The average recent need is multiplied by
<varname>bgwriter_lru_multiplier</> to arrive at the estimate of the
number of buffers that will be needed during the next round.  Dirty
buffers are written until there are that many clean, reusable buffers
available.  However, no more than <varname>bgwriter_lru_maxpages</>
buffers will be written per round.

			regards, tom lane

---

From: Greg Smith <[email-masked]>
Date: Sun, 20 Jan 2008 22:07:52 -0500 (EST)

On Sun, 20 Jan 2008, Tom Lane wrote:

> of prominence.  Here's a V3 try

That one looks good to me.  These are small details but better to get it 
right now.

---

From: Tom Lane <[email-masked]>
Date: Sun, 20 Jan 2008 22:29:48 -0500

> That one looks good to me.  These are small details but better to get it 

OK, committed.  Back to Alvaro's original concern: is the short
description in guc.c all right, or can we improve that?

			regards, tom lane

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 6 Mar 2008 11:32:03 -0500 (EST)

> description in guc.c all right, or can we improve that?

I have tried to improve the GUC description for
"bgwriter_lru_multiplier";  applied to CVS HEAD.

-- 
  Bruce Momjian  <[email-masked]>        http://momjian.us
  EnterpriseDB                             http://postgres.enterprisedb.com

  + If your life is a hard drive, Christ can be your backup. +
Index: src/backend/utils/misc/guc.c
===================================================================
RCS file: /cvsroot/pgsql/src/backend/utils/misc/guc.c,v
retrieving revision 1.432
diff -c -c -r1.432 guc.c
*** src/backend/utils/misc/guc.c	30 Jan 2008 18:35:55 -0000	1.432
--- src/backend/utils/misc/guc.c	6 Mar 2008 16:22:44 -0000
***************
*** 1841,1847 ****
  
  	{
  		{"bgwriter_lru_multiplier", PGC_SIGHUP, RESOURCES,
! 			gettext_noop("Background writer multiplier on average buffers to scan per round."),
  			NULL
  		},
  		&bgwriter_lru_multiplier,
--- 1841,1847 ----
  
  	{
  		{"bgwriter_lru_multiplier", PGC_SIGHUP, RESOURCES,
! 			gettext_noop("Multiple of the average buffer usage to free per round."),
  			NULL
  		},
  		&bgwriter_lru_multiplier,