1 /* SPDX-License-Identifier: GPL-2.0 */
2 /*
3  * include/linux/pagevec.h
4  *
5  * In many places it is efficient to batch an operation up against multiple
6  * folios.  A folio_batch is a container which is used for that.
7  */
8 
9 #ifndef _LINUX_PAGEVEC_H
10 #define _LINUX_PAGEVEC_H
11 
12 #include <linux/types.h>
13 
14 /* 31 pointers + header align the folio_batch structure to a power of two */
15 #define PAGEVEC_SIZE	31
16 
17 struct folio;
18 
19 /**
20  * struct folio_batch - A collection of folios.
21  *
22  * The folio_batch is used to amortise the cost of retrieving and
23  * operating on a set of folios.  The order of folios in the batch may be
24  * significant (eg delete_from_page_cache_batch()).  Some users of the
25  * folio_batch store "exceptional" entries in it which can be removed
26  * by calling folio_batch_remove_exceptionals().
27  */
28 struct folio_batch {
29 	unsigned char nr;
30 	unsigned char i;
31 	bool percpu_pvec_drained;
32 	struct folio *folios[PAGEVEC_SIZE];
33 };
34 
35 /**
36  * folio_batch_init() - Initialise a batch of folios
37  * @fbatch: The folio batch.
38  *
39  * A freshly initialised folio_batch contains zero folios.
40  */
folio_batch_init(struct folio_batch * fbatch)41 static inline void folio_batch_init(struct folio_batch *fbatch)
42 {
43 	fbatch->nr = 0;
44 	fbatch->i = 0;
45 	fbatch->percpu_pvec_drained = false;
46 }
47 
folio_batch_reinit(struct folio_batch * fbatch)48 static inline void folio_batch_reinit(struct folio_batch *fbatch)
49 {
50 	fbatch->nr = 0;
51 	fbatch->i = 0;
52 }
53 
folio_batch_count(struct folio_batch * fbatch)54 static inline unsigned int folio_batch_count(struct folio_batch *fbatch)
55 {
56 	return fbatch->nr;
57 }
58 
folio_batch_space(struct folio_batch * fbatch)59 static inline unsigned int folio_batch_space(struct folio_batch *fbatch)
60 {
61 	return PAGEVEC_SIZE - fbatch->nr;
62 }
63 
64 /**
65  * folio_batch_add() - Add a folio to a batch.
66  * @fbatch: The folio batch.
67  * @folio: The folio to add.
68  *
69  * The folio is added to the end of the batch.
70  * The batch must have previously been initialised using folio_batch_init().
71  *
72  * Return: The number of slots still available.
73  */
folio_batch_add(struct folio_batch * fbatch,struct folio * folio)74 static inline unsigned folio_batch_add(struct folio_batch *fbatch,
75 		struct folio *folio)
76 {
77 	fbatch->folios[fbatch->nr++] = folio;
78 	return folio_batch_space(fbatch);
79 }
80 
81 /**
82  * folio_batch_next - Return the next folio to process.
83  * @fbatch: The folio batch being processed.
84  *
85  * Use this function to implement a queue of folios.
86  *
87  * Return: The next folio in the queue, or NULL if the queue is empty.
88  */
folio_batch_next(struct folio_batch * fbatch)89 static inline struct folio *folio_batch_next(struct folio_batch *fbatch)
90 {
91 	if (fbatch->i == fbatch->nr)
92 		return NULL;
93 	return fbatch->folios[fbatch->i++];
94 }
95 
96 void __folio_batch_release(struct folio_batch *pvec);
97 
folio_batch_release(struct folio_batch * fbatch)98 static inline void folio_batch_release(struct folio_batch *fbatch)
99 {
100 	if (folio_batch_count(fbatch))
101 		__folio_batch_release(fbatch);
102 }
103 
104 void folio_batch_remove_exceptionals(struct folio_batch *fbatch);
105 #endif /* _LINUX_PAGEVEC_H */
106