iv/linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

filemap: Update the folio_lock documentation

Browse Source 
Add kernel-doc for several functions relating to take the folio lock.

Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
This commit is contained in:
Matthew Wilcox (Oracle) 2022-04-04 13:24:36 -04:00
parent 65aa6b5a18
commit cd125eeab2
1 changed files with 57 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
include/linux/pagemap.h
View File

@ -888,6 +888,18 @@ bool __folio_lock_or_retry(struct folio *folio, struct mm_struct *mm,
void unlock_page(struct page *page);
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.
*
* Context: Any context.
* Return: Whether the lock was successfully acquired.
*/
static inline bool folio_trylock(struct folio *folio)
{
return likely(!test_and_set_bit_lock(PG_locked, folio_flags(folio, 0)));
@ -901,6 +913,28 @@ static inline int trylock_page(struct page *page)
return folio_trylock(page_folio(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 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.
*
* 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)
{
might_sleep();
@ -908,6 +942,17 @@ static inline void folio_lock(struct folio *folio)
__folio_lock(folio);
}
/**
* lock_page() - Lock the folio containing this page.
* @page: The page to lock.
*
* See folio_lock() for a description of what the lock protects.
* 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.
*/
static inline void lock_page(struct page *page)
{
struct folio *folio;
@ -918,6 +963,16 @@ static inline void lock_page(struct page *page)
__folio_lock(folio);
}
/**
* 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.
*
* Context: May sleep; see folio_lock().
* Return: 0 if the lock was acquired; -EINTR if a fatal signal was received.
*/
static inline int folio_lock_killable(struct folio *folio)
{
might_sleep();
@ -964,8 +1019,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 "page->count" so that the folio won't
* go away during the wait..
* ie 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)
{