Commit fad9c80e authored by Thomas Gleixner's avatar Thomas Gleixner Committed by Andrew Morton
Browse files

maple_tree: fix a few documentation issues 

The documentation of mt_next() claims that it starts the search at the
provided index.  That's incorrect as it starts the search after the
provided index.

The documentation of mt_find() is slightly confusing.  "Handles locking"
is not really helpful as it does not explain how the "locking" works. 
Also the documentation of index talks about a range, while in reality the
index is updated on a succesful search to the index of the found entry
plus one.

Fix similar issues for mt_find_after() and mt_prev().

Reword the confusing "Note: Will not return the zero entry." comment on
mt_for_each() and document @__index correctly.

Link: https://lkml.kernel.org/r/87ttw2n556.ffs@tglx


Signed-off-by: default avatarThomas Gleixner <tglx@linutronix.de>
Reviewed-by: default avatarLiam R. Howlett <Liam.Howlett@oracle.com>
Cc: Matthew Wilcox <willy@infradead.org>
Cc: Shanker Donthineni <sdonthineni@nvidia.com>
Signed-off-by: default avatarAndrew Morton <akpm@linux-foundation.org>
parent 20c897ea

include/linux/maple_tree.h

+3 −2
Original line number Diff line number Diff line
@@ -662,10 +662,11 @@ void *mt_next(struct maple_tree *mt, unsigned long index, unsigned long max); 
 * mt_for_each - Iterate over each entry starting at index until max.

 * @__tree: The Maple Tree

 * @__entry: The current entry

 * @__index: The index to update to track the location in the tree

 * @__index: The index to start the search from. Subsequently used as iterator.

 * @__max: The maximum limit for @index

 *

 * Note: Will not return the zero entry.

 * This iterator skips all entries, which resolve to a NULL pointer,

 * e.g. entries which has been reserved with XA_ZERO_ENTRY.

 */

#define mt_for_each(__tree, __entry, __index, __max) \

	for (__entry = mt_find(__tree, &(__index), __max); \

lib/maple_tree.c

+21 −5
Original line number Diff line number Diff line
@@ -5750,7 +5750,11 @@ EXPORT_SYMBOL_GPL(mas_next_range); 
 * @index: The start index

 * @max: The maximum index to check

 *

 * Return: The entry at @index or higher, or %NULL if nothing is found.

 * Takes RCU read lock internally to protect the search, which does not

 * protect the returned pointer after dropping RCU read lock.

 * See also: Documentation/core-api/maple_tree.rst

 *

 * Return: The entry higher than @index or %NULL if nothing is found.

 */

void *mt_next(struct maple_tree *mt, unsigned long index, unsigned long max)

{
@@ -5856,7 +5860,11 @@ EXPORT_SYMBOL_GPL(mas_prev_range); 
 * @index: The start index

 * @min: The minimum index to check

 *

 * Return: The entry at @index or lower, or %NULL if nothing is found.

 * Takes RCU read lock internally to protect the search, which does not

 * protect the returned pointer after dropping RCU read lock.

 * See also: Documentation/core-api/maple_tree.rst

 *

 * Return: The entry before @index or %NULL if nothing is found.

 */

void *mt_prev(struct maple_tree *mt, unsigned long index, unsigned long min)

{
@@ -6468,9 +6476,15 @@ EXPORT_SYMBOL(mtree_destroy); 
 * mt_find() - Search from the start up until an entry is found.

 * @mt: The maple tree

 * @index: Pointer which contains the start location of the search

 * @max: The maximum value to check

 * @max: The maximum value of the search range

 *

 * Takes RCU read lock internally to protect the search, which does not

 * protect the returned pointer after dropping RCU read lock.

 * See also: Documentation/core-api/maple_tree.rst

 *

 * Handles locking.  @index will be incremented to one beyond the range.

 * In case that an entry is found @index is updated to point to the next

 * possible entry independent whether the found entry is occupying a

 * single index or a range if indices.

 *

 * Return: The entry at or after the @index or %NULL

 */
@@ -6528,7 +6542,9 @@ EXPORT_SYMBOL(mt_find); 
 * @index: Pointer which contains the start location of the search

 * @max: The maximum value to check

 *

 * Handles locking, detects wrapping on index == 0

 * Same as mt_find() except that it checks @index for 0 before

 * searching. If @index == 0, the search is aborted. This covers a wrap

 * around of @index to 0 in an iterator loop.

 *

 * Return: The entry at or after the @index or %NULL

 */