[PATCH v3] xarray: Document erasing entries during iteration

[PATCH v3] xarray: Document erasing entries during iteration

[Tobin C. Harding]

The XArray is, in a way, a replacement data structure for linked lists,
as such, on first use developers may wonder if it is safe to remove
items while iterating over the array.  Calling xa_erase() while
looping with xa_for_each() is fine, let's document it.

Document explicitly in the docs and also for the macro definition.

Signed-off-by: Tobin C. Harding <tobin@kernel.org>
---

v2 -> v3:
 - Put document comment in a better place, tie together current
   discussion of xa_for_each(), xa_erase(), and xa_destroy().
 - Improve commit message.
 - Actually build the docs and verify the patched file renders in HTML.

v1 -> v2:
 - Use the correct function name

thanks,
Tobin.

 Documentation/core-api/xarray.rst | 4 +++-
 include/linux/xarray.h            | 2 ++
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/Documentation/core-api/xarray.rst b/Documentation/core-api/xarray.rst
index 5d54b27c6eba..77a93e3e0e4f 100644
--- a/Documentation/core-api/xarray.rst
+++ b/Documentation/core-api/xarray.rst
@@ -97,7 +97,9 @@ You can copy entries out of the XArray into a plain array by calling
 :c:func:`xa_extract`.  Or you can iterate over the present entries in
 the XArray by calling :c:func:`xa_for_each`.  You may prefer to use
 :c:func:`xa_find` or :c:func:`xa_find_after` to move to the next present
-entry in the XArray.
+entry in the XArray.  It is safe to call :c:func:`xa_erase` while iterating
+the array.  If you are clearing the whole array you may prefer to use
+:c:func:`xa_destroy` (documented below).
 
 Calling :c:func:`xa_store_range` stores the same entry in a range
 of indices.  If you do this, some of the other operations will behave
diff --git a/include/linux/xarray.h b/include/linux/xarray.h
index 5d9d318bcf7a..1f8974281a0a 100644
--- a/include/linux/xarray.h
+++ b/include/linux/xarray.h
@@ -407,6 +407,8 @@ static inline bool xa_marked(const struct xarray *xa, xa_mark_t mark)
  * you should use the xas_for_each() iterator instead.  The xas_for_each()
  * iterator will expand into more inline code than xa_for_each().
  *
+ * It is safe to erase entries from the XArray as you iterate over it.
+ *
  * Context: Any context.  Takes and releases the RCU lock.
  */
 #define xa_for_each(xa, index, entry) \
-- 
2.20.1