| Message ID | 20241009193602.41797-2-tamird@gmail.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | XArray: minor documentation improvements | expand |
On Wed, Oct 09, 2024 at 03:36:03PM -0400, Tamir Duberstein wrote: > - Replace "they" with "you" where "you" is used in the preceding > sentence fragment. > - Use "erasing" rather than "storing `NULL`" when describing multi-index > entries. Split this into a separate sentence. > - Add "call" parentheses on "xa_store" for consistency and > linkification. > > Signed-off-by: Tamir Duberstein <tamird@gmail.com> > --- > Documentation/core-api/xarray.rst | 10 +++++----- > 1 file changed, 5 insertions(+), 5 deletions(-) > > diff --git a/Documentation/core-api/xarray.rst b/Documentation/core-api/xarray.rst > index 77e0ece2b1d6..d79d4e4ceff6 100644 > --- a/Documentation/core-api/xarray.rst > +++ b/Documentation/core-api/xarray.rst > @@ -42,8 +42,8 @@ call xa_tag_pointer() to create an entry with a tag, xa_untag_pointer() > to turn a tagged entry back into an untagged pointer and xa_pointer_tag() > to retrieve the tag of an entry. Tagged pointers use the same bits that > are used to distinguish value entries from normal pointers, so you must > -decide whether they want to store value entries or tagged pointers in > -any particular XArray. > +decide whether use want to store value entries or tagged pointers in any "...so you must decide if *you* want to store value entries or..." > +particular XArray. > > The XArray does not support storing IS_ERR() pointers as some > conflict with value entries or internal entries. > @@ -52,8 +52,8 @@ An unusual feature of the XArray is the ability to create entries which > occupy a range of indices. Once stored to, looking up any index in > the range will return the same entry as looking up any other index in > the range. Storing to any index will store to all of them. Multi-index > -entries can be explicitly split into smaller entries, or storing ``NULL`` > -into any entry will cause the XArray to forget about the range. > +entries can be explicitly split into smaller entries. Erasing any entry > +will cause the XArray to forget about the range. n00b question: is xa_store(..., NULL) the same as xa_erase? If it is, then should the documentation mention that xa_store(NULL) is the same as xa_erase, and that both of these operations will cause the xarray to forget about that range? --D > Normal API > ========== > @@ -64,7 +64,7 @@ allocated ones. A freshly-initialised XArray contains a ``NULL`` > pointer at every index. > > You can then set entries using xa_store() and get entries > -using xa_load(). xa_store will overwrite any entry with the > +using xa_load(). xa_store() will overwrite any entry with the > new entry and return the previous entry stored at that index. You can > use xa_erase() instead of calling xa_store() with a > ``NULL`` entry. There is no difference between an entry that has never > -- > 2.47.0 > >
On Wed, Oct 9, 2024 at 4:44 PM Darrick J. Wong <djwong@kernel.org> wrote: > > n00b question: is xa_store(..., NULL) the same as xa_erase? > > If it is, then should the documentation mention that xa_store(NULL) is > the same as xa_erase, and that both of these operations will cause the > xarray to forget about that range? They're not quite the same in the presence of `XA_FLAGS_ALLOC`. Per the docs: > Unlike a normal XArray, storing NULL will mark the entry as being in use [...] See https://docs.kernel.org/core-api/xarray.html#allocating-xarrays.
diff --git a/Documentation/core-api/xarray.rst b/Documentation/core-api/xarray.rst index 77e0ece2b1d6..d79d4e4ceff6 100644 --- a/Documentation/core-api/xarray.rst +++ b/Documentation/core-api/xarray.rst @@ -42,8 +42,8 @@ call xa_tag_pointer() to create an entry with a tag, xa_untag_pointer() to turn a tagged entry back into an untagged pointer and xa_pointer_tag() to retrieve the tag of an entry. Tagged pointers use the same bits that are used to distinguish value entries from normal pointers, so you must -decide whether they want to store value entries or tagged pointers in -any particular XArray. +decide whether use want to store value entries or tagged pointers in any +particular XArray. The XArray does not support storing IS_ERR() pointers as some conflict with value entries or internal entries. @@ -52,8 +52,8 @@ An unusual feature of the XArray is the ability to create entries which occupy a range of indices. Once stored to, looking up any index in the range will return the same entry as looking up any other index in the range. Storing to any index will store to all of them. Multi-index -entries can be explicitly split into smaller entries, or storing ``NULL`` -into any entry will cause the XArray to forget about the range. +entries can be explicitly split into smaller entries. Erasing any entry +will cause the XArray to forget about the range. Normal API ========== @@ -64,7 +64,7 @@ allocated ones. A freshly-initialised XArray contains a ``NULL`` pointer at every index. You can then set entries using xa_store() and get entries -using xa_load(). xa_store will overwrite any entry with the +using xa_load(). xa_store() will overwrite any entry with the new entry and return the previous entry stored at that index. You can use xa_erase() instead of calling xa_store() with a ``NULL`` entry. There is no difference between an entry that has never
- Replace "they" with "you" where "you" is used in the preceding sentence fragment. - Use "erasing" rather than "storing `NULL`" when describing multi-index entries. Split this into a separate sentence. - Add "call" parentheses on "xa_store" for consistency and linkification. Signed-off-by: Tamir Duberstein <tamird@gmail.com> --- Documentation/core-api/xarray.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-)