Bug 242062 - FAQs 10.21 and 10.22 still mention the cache queue
Summary: FAQs 10.21 and 10.22 still mention the cache queue
Status: Closed FIXED
Alias: None
Product: Documentation
Classification: Unclassified
Component: Documentation (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Only Me
Assignee: Mark Linimon
URL: https://reviews.freebsd.org/D24486
Keywords:
Depends on:
Blocks:
 
Reported: 2019-11-18 16:52 UTC by PauAmma
Modified: 2020-05-16 21:34 UTC (History)
1 user (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description PauAmma 2019-11-18 16:52:16 UTC
Yet, I'm told in IRC that the cache queue no longer exists.
Comment 1 PauAmma 2020-02-09 03:41:33 UTC
Draft language, derived from an IRC discussion with debdrup several weeks ago:

"There are a couple of kinds of "free memory". One kind is the amount of memory immediately available without paging anything else out. That is approximately the size of the free queue + the combined size of the inactive and laundry queues (with a derating factor, depending upon system tuning), all as shown in &man.top.1;. Another kind of "free memory" is the total amount of VM space. That can be complex, but is dependent upon the amount of swap space and memory. Other kinds of "free memory" descriptions are also possible, but it is relatively useless to define these, but rather it is important to make sure that the paging rate is kept low, and to avoid running out of swap space."

Can someone who understands those things check my language for accuracy?
Comment 2 Mark Johnston freebsd_committer 2020-04-14 18:16:57 UTC
(In reply to PauAmma from comment #1)
This isn't quite accurate: "free memory" by the VM system's definition is simply unused memory, i.e., the "Free" entry in top(1).  Memory in the inactive and laundry queues may need to be paged out before being reclaimed.

I don't really understand the comment about "VM space".

WRT the FAQ entry, I would suggest simply deleting the "Cache" entry, and adding one for "Laundry", perhaps, "Pages recently statistically unused that are known to be dirty, i.e., their contents must be paged out before they can be reused."
Comment 3 PauAmma 2020-04-14 19:07:36 UTC
(In reply to Mark Johnston from comment #2)
Thanks for pointing out to me that FAQ 10.21 needs to be updated as well and suggesting revised language for it.

I took the 2 "VM space" sentences in FAQ 10.22 to mean something like "Free space may also mean total virtual memory available to userland processes, which depends on the sum of physical memory and swap space" but (if they mean that) I agree they're not very clear. Would this reformulation be clearer and as or more accurate?
Comment 4 Mark Johnston freebsd_committer 2020-04-17 13:45:58 UTC
(In reply to PauAmma from comment #3)
Oh sorry, I thought the suggested update was for 10.21.  I was a bit confused.

For 10.21, let's do this:
- remove the "cache" entry
- remove the reference to "cache" in the "free" entry
- add a "laundry" entry: "Pages recently statistically unused that are known to be dirty, i.e., their contents must be paged out before they can be reused."

For 10.22, let's change the second and third sentences: "The most common definition is the amount of memory immediately available without reclaiming memory already in use.  That is the size of the free page queues, plus unallocated pages in partially populated superpage reservations.  This quantity is exported by the vm.stats.vm.v_free_count, shown, for example, by top(1)."

I don't really like the rest of the paragraph (what's the point of stating that there are multiple definitions if all but one are "too complex" or not worth defining?) but we can leave it alone for now.
Comment 5 PauAmma 2020-04-17 14:40:51 UTC
(In reply to Mark Johnston from comment #4)
Thanks for your detailed suggestion. I think I'm going to simplify a bit your suggested language in 10.22, if you don't mind, by removing the mentions of superpage reservation and partial allocation, which are nowhere defined in the FAQ and seem to me to have a level of detail too deep for what's meant as a document for end users, and instead saying something like "and some other pages not covered here".
Comment 6 Mark Johnston freebsd_committer 2020-04-17 14:45:03 UTC
(In reply to PauAmma from comment #5)
That is fine with me.  It'd be nice if this was covered somewhere in the handbook, since it's one of the more interesting features of the kernel, but I agree with your reasoning.
Comment 7 commit-hook freebsd_committer 2020-04-28 02:29:25 UTC
A commit references this bug:

Author: allanjude
Date: Tue Apr 28 02:28:48 UTC 2020
New revision: 54079
URL: https://svnweb.freebsd.org/changeset/doc/54079

Log:
  Update FAQ entries 10.21 and 10.22

  PR:		242062
  Submitted by:	pauamma@gundo.com
  Reviewed by:	markj, debdrup
  Differential Revision:	https://reviews.freebsd.org/D24486

Changes:
  head/en_US.ISO8859-1/books/faq/book.xml
Comment 8 PauAmma 2020-05-04 20:53:57 UTC
Should this be closed?