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

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
888void unlock_page(struct page *page);888void unlock_page(struct page *page);
889void folio_unlock(struct folio *folio);889void folio_unlock(struct folio *folio);
890 890
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 */
891static inline bool folio_trylock(struct folio *folio)903static inline bool folio_trylock(struct folio *folio)
892{904{
893 return likely(!test_and_set_bit_lock(PG_locked, folio_flags(folio, 0)));905 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
901 return folio_trylock(page_folio(page));913 return folio_trylock(page_folio(page));
902}914}
903 915
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 */
904static inline void folio_lock(struct folio *folio)938static inline void folio_lock(struct folio *folio)
905{939{
906 might_sleep();940 might_sleep();
@@ -908,6 +942,17 @@ static inline void folio_lock(struct folio *folio) · 1 unmodified line
908 __folio_lock(folio);942 __folio_lock(folio);
909}943}
910 944
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 */
911static inline void lock_page(struct page *page)956static inline void lock_page(struct page *page)
912{957{
913 struct folio *folio;958 struct folio *folio;
@@ -918,6 +963,16 @@ static inline void lock_page(struct page *page) · 4 unmodified lines
918 __folio_lock(folio);963 __folio_lock(folio);
919}964}
920 965
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 */
921static inline int folio_lock_killable(struct folio *folio)976static inline int folio_lock_killable(struct folio *folio)
922{977{
923 might_sleep();978 might_sleep();
@@ -964,8 +1019,8 @@ int folio_wait_bit_killable(struct folio *folio, int bit_nr); · 40 unmodified lines
964 * Wait for a folio to be unlocked.1019 * Wait for a folio to be unlocked.
965 *1020 *
966 * This must be called with the caller "holding" the folio,1021 * This must be called with the caller "holding" the folio,
967 * ie with increased "page->count" so that the folio won't1022 * ie with increased folio reference count so that the folio won't
968 * go away during the wait..1023 * go away during the wait.
969 */1024 */
970static inline void folio_wait_locked(struct folio *folio)1025static inline void folio_wait_locked(struct folio *folio)
971{1026{

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