git: ca18e0441029 - main - vm_page: update some iterator-related comments

The branch main has been updated by dougm:

URL: https://cgit.FreeBSD.org/src/commit/?id=ca18e0441029fc94076eb8441581ae07561cace0

commit ca18e0441029fc94076eb8441581ae07561cace0
Author:     Doug Moore <dougm@FreeBSD.org>
AuthorDate: 2025-05-16 07:42:34 +0000
Commit:     Doug Moore <dougm@FreeBSD.org>
CommitDate: 2025-05-16 07:42:34 +0000

    vm_page: update some iterator-related comments
    
    Update a stale comment about vm_page_alloc_iter(), and add a comment
    about one of its use cases.
    
    Reviewed by:    kib, markj, alc
    Differential Revision:  https://reviews.freebsd.org/D50263
---
 sys/vm/vm_page.c | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/sys/vm/vm_page.c b/sys/vm/vm_page.c
index 681846f8c71a..0fdda1d5fc48 100644
--- a/sys/vm/vm_page.c
+++ b/sys/vm/vm_page.c
@@ -1996,10 +1996,8 @@ vm_page_alloc(vm_object_t object, vm_pindex_t pindex, int req)
 }
 
 /*
- * Allocate a page in the specified object with the given page index.  To
- * optimize insertion of the page into the object, the caller must also specify
- * the resident page in the object with largest index smaller than the given
- * page index, or NULL if no such page exists.
+ * Allocate a page in the specified object with the given page index.  If the
+ * object lock is dropped and regained, the pages iter is reset.
  */
 vm_page_t
 vm_page_alloc_iter(vm_object_t object, vm_pindex_t pindex, int req,
@@ -5189,6 +5187,7 @@ retrylookup:
 				break;
 			m = vm_page_alloc_iter(object, pindex + i,
 			    pflags | VM_ALLOC_COUNT(count - i), &pages);
+			/* pages was reset if alloc_iter lost the lock. */
 			if (m == NULL) {
 				if ((allocflags & (VM_ALLOC_NOWAIT |
 				    VM_ALLOC_WAITFAIL)) != 0)