[PATCH RFC 05/11] folio_wait: reformat comments and fix alignment
Tal Zussman <[email protected]>
| Newsgroups | org.kernel.vger.io-uring,org.kernel.vger.linux-fsdevel,org.kernel.vger.linux-kernel,org.kvack.linux-mm |
|---|---|
| Message-ID | <[email protected]> |
Reflow comments to fill 80 columns and fix indentation issues carried over from the original locations in pagemap.h and filemap.c. Signed-off-by: Tal Zussman <[email protected]> --- include/linux/folio_wait.h | 62 ++++++++------- mm/folio_wait.c | 185 ++++++++++++++++++++------------------------- 2 files changed, 113 insertions(+), 134 deletions(-) diff --git a/include/linux/folio_wait.h b/include/linux/folio_wait.h index 4a5cb2fcf046..57ccf9ffd243 100644 --- a/include/linux/folio_wait.h +++ b/include/linux/folio_wait.h @@ -19,10 +19,10 @@ struct wait_page_queue { }; static inline bool wake_page_match(struct wait_page_queue *wait_page, - struct wait_page_key *key) + struct wait_page_key *key) { if (wait_page->folio != key->folio) - return false; + return false; key->page_match = 1; if (wait_page->bit_nr != key->bit_nr) @@ -41,10 +41,10 @@ void folio_unlock(struct folio *folio); * folio_trylock() - Attempt to lock a folio. * @folio: The folio to attempt to lock. * - * Sometimes it is undesirable to wait for a folio to be unlocked (eg - * when the locks are being taken in the wrong order, or if making - * progress through a batch of folios is more important than processing - * them in order). Usually folio_lock() is the correct function to call. + * Sometimes it is undesirable to wait for a folio to be unlocked (e.g. when + * the locks are being taken in the wrong order, or if making progress through + * a batch of folios is more important than processing them in order). Usually + * folio_lock() is the correct function to call. * * Context: Any context. * Return: Whether the lock was successfully acquired. @@ -66,23 +66,22 @@ static inline bool trylock_page(struct page *page) * folio_lock() - Lock this folio. * @folio: The folio to lock. * - * The folio lock protects against many things, probably more than it - * should. It is primarily held while a folio is being brought uptodate, - * either from its backing file or from swap. It is also held while a - * folio is being truncated from its address_space, so holding the lock - * is sufficient to keep folio->mapping stable. + * The folio lock protects against many things, probably more than it should. + * It is primarily held while a folio is being brought uptodate, either from + * its backing file or from swap. It is also held while a folio is being + * truncated from its address_space, so holding the lock is sufficient to keep + * folio->mapping stable. * - * The folio lock is also held while write() is modifying the page to - * provide POSIX atomicity guarantees (as long as the write does not - * cross a page boundary). Other modifications to the data in the folio - * do not hold the folio lock and can race with writes, eg DMA and stores - * to mapped pages. + * The folio lock is also held while write() is modifying the folio to provide + * POSIX atomicity guarantees (as long as the write does not cross a page + * boundary). Other modifications to the data in the folio do not hold the + * folio lock and can race with writes, e.g. DMA and stores to mapped pages. * - * Context: May sleep. If you need to acquire the locks of two or - * more folios, they must be in order of ascending index, if they are - * in the same address_space. If they are in different address_spaces, - * acquire the lock of the folio which belongs to the address_space which - * has the lowest address in memory first. + * Context: May sleep. If you need to acquire the locks of two or more folios, + * they must be in order of ascending index, if they are in the same + * address_space. If they are in different address_spaces, acquire the lock of + * the folio which belongs to the address_space which has the lowest address in + * memory first. */ static inline void folio_lock(struct folio *folio) { @@ -99,8 +98,8 @@ static inline void folio_lock(struct folio *folio) * This is a legacy function and new code should probably use folio_lock() * instead. * - * Context: May sleep. Pages in the same folio share a lock, so do not - * attempt to lock two pages which share a folio. + * Context: May sleep. Pages in the same folio share a lock, so do not attempt + * to lock two pages which share a folio. */ static inline void lock_page(struct page *page) { @@ -116,8 +115,8 @@ static inline void lock_page(struct page *page) * folio_lock_killable() - Lock this folio, interruptible by a fatal signal. * @folio: The folio to lock. * - * Attempts to lock the folio, like folio_lock(), except that the sleep - * to acquire the lock is interruptible by a fatal signal. + * Attempts to lock the folio, like folio_lock(), except that the sleep to + * acquire the lock is interruptible by a fatal signal. * * Context: May sleep; see folio_lock(). * Return: 0 if the lock was acquired; -EINTR if a fatal signal was received. @@ -131,8 +130,8 @@ static inline int folio_lock_killable(struct folio *folio) } /* - * folio_lock_or_retry - Lock the folio, unless this would block and the - * caller indicated that it can handle a retry. + * folio_lock_or_retry - Lock the folio, unless this would block and the caller + * indicated that it can handle a retry. * * Return value and mmap_lock implications depend on flags; see * __folio_lock_or_retry(). @@ -147,8 +146,8 @@ static inline vm_fault_t folio_lock_or_retry(struct folio *folio, } /* - * This is exported only for folio_wait_locked/folio_wait_writeback, etc., - * and should not be used directly. + * This is exported only for folio_wait_locked/folio_wait_writeback, etc., and + * should not be used directly. */ void folio_wait_bit(struct folio *folio, int bit_nr); int folio_wait_bit_killable(struct folio *folio, int bit_nr); @@ -156,9 +155,8 @@ int folio_wait_bit_killable(struct folio *folio, int bit_nr); /* * Wait for a folio to be unlocked. * - * This must be called with the caller "holding" the folio, - * ie with increased folio reference count so that the folio won't - * go away during the wait. + * This must be called with the caller "holding" the folio, i.e. with increased + * folio reference count so that the folio won't go away during the wait. */ static inline void folio_wait_locked(struct folio *folio) { diff --git a/mm/folio_wait.c b/mm/folio_wait.c index 9d3328717bb3..8d8237cdd73b 100644 --- a/mm/folio_wait.c +++ b/mm/folio_wait.c @@ -20,14 +20,12 @@ #include "internal.h" /* - * In order to wait for pages to become available there must be - * waitqueues associated with pages. By using a hash table of - * waitqueues where the bucket discipline is to maintain all - * waiters on the same queue and wake all when any of the pages - * become available, and for the woken contexts to check to be - * sure the appropriate page became available, this saves space - * at a cost of "thundering herd" phenomena during rare hash - * collisions. + * In order to wait for pages to become available there must be waitqueues + * associated with pages. By using a hash table of waitqueues where the bucket + * discipline is to maintain all waiters on the same queue and wake all when any + * of the pages become available, and for the woken contexts to check to be + * sure the appropriate page became available, this saves space at a cost of + * "thundering herd" phenomena during rare hash collisions. */ #define PAGE_WAIT_TABLE_BITS 8 #define PAGE_WAIT_TABLE_SIZE (1 << PAGE_WAIT_TABLE_BITS) @@ -70,44 +68,42 @@ void __init folio_wait_init(void) * * (a) no special bits set: * - * We're just waiting for the bit to be released, and when a waker - * calls the wakeup function, we set WQ_FLAG_WOKEN and wake it up, - * and remove it from the wait queue. + * We're just waiting for the bit to be released, and when a waker calls + * the wakeup function, we set WQ_FLAG_WOKEN and wake it up, and remove + * it from the wait queue. * * Simple and straightforward. * * (b) WQ_FLAG_EXCLUSIVE: * - * The waiter is waiting to get the lock, and only one waiter should - * be woken up to avoid any thundering herd behavior. We'll set the + * The waiter is waiting to get the lock, and only one waiter should be + * woken up to avoid any thundering herd behavior. We'll set the * WQ_FLAG_WOKEN bit, wake it up, and remove it from the wait queue. * * This is the traditional exclusive wait. * * (c) WQ_FLAG_EXCLUSIVE | WQ_FLAG_CUSTOM: * - * The waiter is waiting to get the bit, and additionally wants the - * lock to be transferred to it for fair lock behavior. If the lock - * cannot be taken, we stop walking the wait queue without waking - * the waiter. + * The waiter is waiting to get the bit, and additionally wants the lock + * to be transferred to it for fair lock behavior. If the lock cannot be + * taken, we stop walking the wait queue without waking the waiter. * * This is the "fair lock handoff" case, and in addition to setting - * WQ_FLAG_WOKEN, we set WQ_FLAG_DONE to let the waiter easily see - * that it now has the lock. + * WQ_FLAG_WOKEN, we set WQ_FLAG_DONE to let the waiter easily see that + * it now has the lock. */ -static int wake_page_function(wait_queue_entry_t *wait, unsigned mode, int sync, void *arg) +static int wake_page_function(wait_queue_entry_t *wait, unsigned int mode, int sync, void *arg) { unsigned int flags; struct wait_page_key *key = arg; - struct wait_page_queue *wait_page - = container_of(wait, struct wait_page_queue, wait); + struct wait_page_queue *wait_page = container_of(wait, struct wait_page_queue, wait); if (!wake_page_match(wait_page, key)) return 0; /* - * If it's a lock handoff wait, we get the bit for it, and - * stop walking (and do not wake it up) if we can't. + * If it's a lock handoff wait, we get the bit for it, and stop walking + * (and do not wake it up) if we can't. */ flags = wait->flags; if (flags & WQ_FLAG_EXCLUSIVE) { @@ -121,26 +117,24 @@ static int wake_page_function(wait_queue_entry_t *wait, unsigned mode, int sync, } /* - * We are holding the wait-queue lock, but the waiter that - * is waiting for this will be checking the flags without - * any locking. + * We are holding the wait-queue lock, but the waiter that is waiting + * for this will be checking the flags without any locking. * - * So update the flags atomically, and wake up the waiter - * afterwards to avoid any races. This store-release pairs - * with the load-acquire in folio_wait_bit_common(). + * So update the flags atomically, and wake up the waiter afterwards to + * avoid any races. This store-release pairs with the load-acquire in + * folio_wait_bit_common(). */ smp_store_release(&wait->flags, flags | WQ_FLAG_WOKEN); wake_up_state(wait->private, mode); /* - * Ok, we have successfully done what we're waiting for, - * and we can unconditionally remove the wait entry. + * Ok, we have successfully done what we're waiting for, and we can + * unconditionally remove the wait entry. * - * Note that this pairs with the "finish_wait()" in the - * waiter, and has to be the absolute last thing we do. - * After this list_del_init(&wait->entry) the wait entry - * might be de-allocated and the process might even have - * exited. + * Note that this pairs with the "finish_wait()" in the waiter, and has + * to be the absolute last thing we do. After this + * list_del_init(&wait->entry) the wait entry might be de-allocated and + * the process might even have exited. */ list_del_init_careful(&wait->entry); return (flags & WQ_FLAG_EXCLUSIVE) != 0; @@ -198,11 +192,10 @@ enum behavior { }; /* - * Attempt to check (or get) the folio flag, and mark us done - * if successful. + * Attempt to check (or get) the folio flag, and mark as done if successful. */ static inline bool folio_trylock_flag(struct folio *folio, int bit_nr, - struct wait_queue_entry *wait) + struct wait_queue_entry *wait) { if (wait->flags & WQ_FLAG_EXCLUSIVE) { if (test_and_set_bit(bit_nr, &folio->flags.f)) @@ -246,18 +239,14 @@ static inline int folio_wait_bit_common(struct folio *folio, int bit_nr, } /* - * Do one last check whether we can get the - * page bit synchronously. + * Do one last check whether we can get the page bit synchronously. * - * Do the folio_set_waiters() marking before that - * to let any waker we _just_ missed know they - * need to wake us up (otherwise they'll never - * even go to the slow case that looks at the - * page queue), and add ourselves to the wait - * queue if we need to sleep. + * Do the folio_set_waiters() marking before that to let any waker we + * _just_ missed know they need to wake us up (otherwise they'll never + * even go to the slow case that looks at the wait queue), and add + * ourselves to the wait queue if we need to sleep. * - * This part needs to be done under the queue - * lock to avoid races. + * This part needs to be done under the queue lock to avoid races. */ spin_lock_irq(&q->lock); folio_set_waiters(folio); @@ -266,9 +255,8 @@ static inline int folio_wait_bit_common(struct folio *folio, int bit_nr, spin_unlock_irq(&q->lock); /* - * From now on, all the logic will be based on - * the WQ_FLAG_WOKEN and WQ_FLAG_DONE flag, to - * see whether the page bit testing has already + * From now on, all the logic will be based on the WQ_FLAG_WOKEN and + * WQ_FLAG_DONE flag, to see whether the page bit testing has already * been done by the wake function. * * We can drop our reference to the folio. @@ -277,10 +265,9 @@ static inline int folio_wait_bit_common(struct folio *folio, int bit_nr, folio_put(folio); /* - * Note that until the "finish_wait()", or until - * we see the WQ_FLAG_WOKEN flag, we need to - * be very careful with the 'wait->flags', because - * we may race with a waker that sets them. + * Note that until the "finish_wait()", or until we see the + * WQ_FLAG_WOKEN flag, we need to be very careful with the + * 'wait->flags', because we may race with a waker that sets them. */ for (;;) { unsigned int flags; @@ -306,8 +293,8 @@ static inline int folio_wait_bit_common(struct folio *folio, int bit_nr, break; /* - * Otherwise, if we're getting the lock, we need to - * try to get it ourselves. + * Otherwise, if we're getting the lock, we need to try to get + * it ourselves. * * And if that fails, we'll have to retry this all. */ @@ -333,13 +320,13 @@ static inline int folio_wait_bit_common(struct folio *folio, int bit_nr, /* * NOTE! The wait->flags weren't stable until we've done the - * 'finish_wait()', and we could have exited the loop above due - * to a signal, and had a wakeup event happen after the signal - * test but before the 'finish_wait()'. + * 'finish_wait()', and we could have exited the loop above due to a + * signal, and had a wakeup event happen after the signal test but + * before the 'finish_wait()'. * - * So only after the finish_wait() can we reliably determine - * if we got woken up or not, so we can now figure out the final - * return value based on that state without races. + * So only after the finish_wait() can we reliably determine if we got + * woken up or not, so we can now figure out the final return value + * based on that state without races. * * Also note that WQ_FLAG_WOKEN is sufficient for a non-exclusive * waiter, but an exclusive one requires WQ_FLAG_DONE. @@ -452,11 +439,10 @@ EXPORT_SYMBOL(folio_wait_bit_killable); * @folio: The folio to wait for. * @state: The sleep state (TASK_KILLABLE, TASK_UNINTERRUPTIBLE, etc). * - * The caller should hold a reference on @folio. They expect the page to - * become unlocked relatively soon, but do not wish to hold up migration - * (for example) by holding the reference while waiting for the folio to - * come unlocked. After this function returns, the caller should not - * dereference @folio. + * The caller should hold a reference on @folio. They expect the page to become + * unlocked relatively soon, but do not wish to hold up migration (for example) + * by holding the reference while waiting for the folio to come unlocked. After + * this function returns, the caller should not dereference @folio. * * Return: 0 if the folio was unlocked or -EINTR if interrupted by a signal. */ @@ -471,8 +457,8 @@ int folio_put_wait_locked(struct folio *folio, int state) * * Unlocks the folio and wakes up any thread sleeping on the page lock. * - * Context: May be called from interrupt or process context. May not be - * called from NMI context. + * Context: May be called from interrupt or process context. May not be called + * from NMI context. */ void folio_unlock(struct folio *folio) { @@ -490,14 +476,13 @@ EXPORT_SYMBOL(folio_unlock); * @folio: The folio. * @success: True if all reads completed successfully. * - * When all reads against a folio have completed, filesystems should - * call this function to let the pagecache know that no more reads - * are outstanding. This will unlock the folio and wake up any thread - * sleeping on the lock. The folio will also be marked uptodate if all - * reads succeeded. + * When all reads against a folio have completed, filesystems should call this + * function to let the pagecache know that no more reads are outstanding. This + * will unlock the folio and wake up any thread sleeping on the lock. The folio + * will also be marked uptodate if all reads succeeded. * - * Context: May be called from interrupt or process context. May not be - * called from NMI context. + * Context: May be called from interrupt or process context. May not be called + * from NMI context. */ void folio_end_read(struct folio *folio, bool success) { @@ -577,13 +562,12 @@ EXPORT_SYMBOL(folio_wait_private_2_killable); * folio_wait_writeback - Wait for a folio to finish writeback. * @folio: The folio to wait for. * - * If the folio is currently being written back to storage, wait for the - * I/O to complete. + * If the folio is currently being written back to storage, wait for the I/O to + * complete. * - * Context: Sleeps. Must be called in process context and with - * no spinlocks held. Caller should hold a reference on the folio. - * If the folio is not locked, writeback may start again after writeback - * has finished. + * Context: Sleeps. Must be called in process context and with no spinlocks + * held. Caller should hold a reference on the folio. If the folio is not + * locked, writeback may start again after writeback has finished. */ void folio_wait_writeback(struct folio *folio) { @@ -598,13 +582,12 @@ EXPORT_SYMBOL_GPL(folio_wait_writeback); * folio_wait_writeback_killable - Wait for a folio to finish writeback. * @folio: The folio to wait for. * - * If the folio is currently being written back to storage, wait for the - * I/O to complete or a fatal signal to arrive. + * If the folio is currently being written back to storage, wait for the I/O to + * complete or a fatal signal to arrive. * - * Context: Sleeps. Must be called in process context and with - * no spinlocks held. Caller should hold a reference on the folio. - * If the folio is not locked, writeback may start again after writeback - * has finished. + * Context: Sleeps. Must be called in process context and with no spinlocks + * held. Caller should hold a reference on the folio. If the folio is not + * locked, writeback may start again after writeback has finished. * Return: 0 on success, -EINTR if we get a fatal signal while waiting. */ int folio_wait_writeback_killable(struct folio *folio) @@ -623,14 +606,13 @@ EXPORT_SYMBOL_GPL(folio_wait_writeback_killable); * folio_wait_stable() - wait for writeback to finish, if necessary. * @folio: The folio to wait on. * - * This function determines if the given folio is related to a backing - * device that requires folio contents to be held stable during writeback. - * If so, then it will wait for any pending writeback to complete. + * This function determines if the given folio is related to a backing device + * that requires folio contents to be held stable during writeback. If so, then + * it will wait for any pending writeback to complete. * - * Context: Sleeps. Must be called in process context and with - * no spinlocks held. Caller should hold a reference on the folio. - * If the folio is not locked, writeback may start again after writeback - * has finished. + * Context: Sleeps. Must be called in process context and with no spinlocks + * held. Caller should hold a reference on the folio. If the folio is not + * locked, writeback may start again after writeback has finished. */ void folio_wait_stable(struct folio *folio) { @@ -670,10 +652,9 @@ int __folio_lock_async(struct folio *folio, struct wait_page_queue *wait) folio_set_waiters(folio); ret = !folio_trylock(folio); /* - * If we were successful now, we know we're still on the - * waitqueue as we're still under the lock. This means it's - * safe to remove and return success, we know the callback - * isn't going to trigger. + * If we were successful now, we know we're still on the waitqueue as + * we're still under the lock. This means it's safe to remove and + * return success, we know the callback isn't going to trigger. */ if (!ret) __remove_wait_queue(q, &wait->wait); -- 2.39.5