From: "Tobin C. Harding" <tobin@kernel.org>
To: Matthew Wilcox <willy@infradead.org>
Cc: "Tobin C. Harding" <tobin@kernel.org>,
linux-fsdevel@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: [PATCH v3] xarray: Document erasing entries during iteration
Date: Thu, 14 Feb 2019 15:01:33 +1100 [thread overview]
Message-ID: <20190214040133.23467-1-tobin@kernel.org> (raw)
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
reply other threads:[~2019-02-14 4:02 UTC|newest]
Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20190214040133.23467-1-tobin@kernel.org \
--to=tobin@kernel.org \
--cc=linux-fsdevel@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=willy@infradead.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).