History

filemap: Update the folio_lock documentation

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

Matthew Wilcox (Oracle) committed 4 years ago

Commit cd125ee1 parent 65aa6b51 file · +57 −2Browse files

Showing the changes to include (1 of 1 file). Show all

Unified · Split

include/linux/pagemap.h+57−2
@@ -888,6 +888,18 @@ bool __folio_lock_or_retry(struct folio *folio, struct mm_struct *mm, · 887 unmodified lines
888888 void unlock_page(struct page *page);
889889 void folio_unlock(struct folio *folio);
890890
891+/**
892+ * folio_trylock() - Attempt to lock a folio.
893+ * @folio: The folio to attempt to lock.
894+ *
895+ * Sometimes it is undesirable to wait for a folio to be unlocked (eg
896+ * when the locks are being taken in the wrong order, or if making
897+ * progress through a batch of folios is more important than processing
898+ * them in order). Usually folio_lock() is the correct function to call.
899+ *
900+ * Context: Any context.
901+ * Return: Whether the lock was successfully acquired.
902+ */
891903 static inline bool folio_trylock(struct folio *folio)
892904 {
893905 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) · 7 unmodified lines
901913 return folio_trylock(page_folio(page));
902914 }
903915
916+/**
917+ * folio_lock() - Lock this folio.
918+ * @folio: The folio to lock.
919+ *
920+ * The folio lock protects against many things, probably more than it
921+ * should. It is primarily held while a folio is being brought uptodate,
922+ * either from its backing file or from swap. It is also held while a
923+ * folio is being truncated from its address_space, so holding the lock
924+ * is sufficient to keep folio->mapping stable.
925+ *
926+ * The folio lock is also held while write() is modifying the page to
927+ * provide POSIX atomicity guarantees (as long as the write does not
928+ * cross a page boundary). Other modifications to the data in the folio
929+ * do not hold the folio lock and can race with writes, eg DMA and stores
930+ * to mapped pages.
931+ *
932+ * Context: May sleep. If you need to acquire the locks of two or
933+ * more folios, they must be in order of ascending index, if they are
934+ * in the same address_space. If they are in different address_spaces,
935+ * acquire the lock of the folio which belongs to the address_space which
936+ * has the lowest address in memory first.
937+ */
904938 static inline void folio_lock(struct folio *folio)
905939 {
906940 might_sleep();
@@ -908,6 +942,17 @@ static inline void folio_lock(struct folio *folio) · 1 unmodified line
908942 __folio_lock(folio);
909943 }
910944
945+/**
946+ * lock_page() - Lock the folio containing this page.
947+ * @page: The page to lock.
948+ *
949+ * See folio_lock() for a description of what the lock protects.
950+ * This is a legacy function and new code should probably use folio_lock()
951+ * instead.
952+ *
953+ * Context: May sleep. Pages in the same folio share a lock, so do not
954+ * attempt to lock two pages which share a folio.
955+ */
911956 static inline void lock_page(struct page *page)
912957 {
913958 struct folio *folio;
@@ -918,6 +963,16 @@ static inline void lock_page(struct page *page) · 4 unmodified lines
918963 __folio_lock(folio);
919964 }
920965
966+/**
967+ * folio_lock_killable() - Lock this folio, interruptible by a fatal signal.
968+ * @folio: The folio to lock.
969+ *
970+ * Attempts to lock the folio, like folio_lock(), except that the sleep
971+ * to acquire the lock is interruptible by a fatal signal.
972+ *
973+ * Context: May sleep; see folio_lock().
974+ * Return: 0 if the lock was acquired; -EINTR if a fatal signal was received.
975+ */
921976 static inline int folio_lock_killable(struct folio *folio)
922977 {
923978 might_sleep();
@@ -964,8 +1019,8 @@ int folio_wait_bit_killable(struct folio *folio, int bit_nr); · 40 unmodified lines
9641019 * Wait for a folio to be unlocked.
9651020 *
9661021 * This must be called with the caller "holding" the folio,
967− * ie with increased "page->count" so that the folio won't
968− * go away during the wait..
1022+ * ie with increased folio reference count so that the folio won't
1023+ * go away during the wait.
9691024 */
9701025 static inline void folio_wait_locked(struct folio *folio)
9711026 {

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t