tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

XArray: minor documentation improvements

- Replace "they" with "you" where "you" is used in the preceding
sentence fragment.
- Mention `xa_erase` in discussion of multi-index entries. Split this
into a separate sentence.
- Add "call" parentheses on "xa_store" for consistency and
linkification.
- Add caveat that `xa_store` and `xa_erase` are not equivalent in the
presence of `XA_FLAGS_ALLOC`.

Link: https://lkml.kernel.org/r/20241105-xarray-documentation-v5-1-8e1702321b41@gmail.com
Signed-off-by: Tamir Duberstein <tamird@gmail.com>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Matthew Wilcox <willy@infradead.org>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>

authored by

Tamir Duberstein and committed by
Andrew Morton eb7a18eb 876a5b25

+13 -11
+13 -11
Documentation/core-api/xarray.rst
··· 42 42 to turn a tagged entry back into an untagged pointer and xa_pointer_tag() 43 43 to retrieve the tag of an entry. Tagged pointers use the same bits that 44 44 are used to distinguish value entries from normal pointers, so you must 45 - decide whether they want to store value entries or tagged pointers in 46 - any particular XArray. 45 + decide whether you want to store value entries or tagged pointers in any 46 + particular XArray. 47 47 48 48 The XArray does not support storing IS_ERR() pointers as some 49 49 conflict with value entries or internal entries. ··· 52 52 occupy a range of indices. Once stored to, looking up any index in 53 53 the range will return the same entry as looking up any other index in 54 54 the range. Storing to any index will store to all of them. Multi-index 55 - entries can be explicitly split into smaller entries, or storing ``NULL`` 56 - into any entry will cause the XArray to forget about the range. 55 + entries can be explicitly split into smaller entries. Unsetting (using 56 + xa_erase() or xa_store() with ``NULL``) any entry will cause the XArray 57 + to forget about the range. 57 58 58 59 Normal API 59 60 ========== ··· 64 63 allocated ones. A freshly-initialised XArray contains a ``NULL`` 65 64 pointer at every index. 66 65 67 - You can then set entries using xa_store() and get entries 68 - using xa_load(). xa_store will overwrite any entry with the 69 - new entry and return the previous entry stored at that index. You can 70 - use xa_erase() instead of calling xa_store() with a 71 - ``NULL`` entry. There is no difference between an entry that has never 72 - been stored to, one that has been erased and one that has most recently 73 - had ``NULL`` stored to it. 66 + You can then set entries using xa_store() and get entries using 67 + xa_load(). xa_store() will overwrite any entry with the new entry and 68 + return the previous entry stored at that index. You can unset entries 69 + using xa_erase() or by setting the entry to ``NULL`` using xa_store(). 70 + There is no difference between an entry that has never been stored to 71 + and one that has been erased with xa_erase(); an entry that has most 72 + recently had ``NULL`` stored to it is also equivalent except if the 73 + XArray was initialized with ``XA_FLAGS_ALLOC``. 74 74 75 75 You can conditionally replace an entry at an index by using 76 76 xa_cmpxchg(). Like cmpxchg(), it will only succeed if