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@xxxxxxxxxx> --- 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
