From: Randy Dunlap <rdunlap@infradead.org>
To: Matthew Wilcox <willy@infradead.org>
Cc: Matthew Wilcox <mawilcox@microsoft.com>,
Ross Zwisler <ross.zwisler@linux.intel.com>,
Jens Axboe <axboe@kernel.dk>, Rehas Sachdeva <aquannie@gmail.com>,
linux-mm@kvack.org, linux-fsdevel@vger.kernel.org,
linux-f2fs-devel@lists.sourceforge.net,
linux-nilfs@vger.kernel.org, linux-btrfs@vger.kernel.org,
linux-xfs@vger.kernel.org, linux-usb@vger.kernel.org,
linux-kernel@vger.kernel.org
Subject: Re: [PATCH v4 08/73] xarray: Add documentation
Date: Mon, 11 Dec 2017 15:10:22 -0800 [thread overview]
Message-ID: <66ad068b-1973-ca41-7bbf-8a0634cc488d@infradead.org> (raw)
In-Reply-To: <20171206004159.3755-9-willy@infradead.org>
On 12/05/2017 04:40 PM, Matthew Wilcox wrote:
> From: Matthew Wilcox <mawilcox@microsoft.com>
>
> This is documentation on how to use the XArray, not details about its
> internal implementation.
>
> Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com>
> ---
> Documentation/core-api/index.rst | 1 +
> Documentation/core-api/xarray.rst | 281 ++++++++++++++++++++++++++++++++++++++
> 2 files changed, 282 insertions(+)
> create mode 100644 Documentation/core-api/xarray.rst
>
> diff --git a/Documentation/core-api/xarray.rst b/Documentation/core-api/xarray.rst
> new file mode 100644
> index 000000000000..871161539242
> --- /dev/null
> +++ b/Documentation/core-api/xarray.rst
> @@ -0,0 +1,281 @@
> +======
> +XArray
> +======
> +
> +Overview
> +========
> +
> +The XArray is an abstract data type which behaves like a very large array
> +of pointers. It meets many of the same needs as a hash or a conventional
> +resizable array. Unlike a hash, it allows you to sensibly go to the
> +next or previous entry in a cache-efficient manner. In contrast to
> +a resizable array, there is no need for copying data or changing MMU
> +mappings in order to grow the array. It is more memory-efficient,
> +parallelisable and cache friendly than a doubly-linked list. It takes
> +advantage of RCU to perform lookups without locking.
> +
> +The XArray implementation is efficient when the indices used are
> +densely clustered; hashing the object and using the hash as the index
> +will not perform well. The XArray is optimised for small indices,
> +but still has good performance with large indices. If your index is
> +larger than ULONG_MAX then the XArray is not the data type for you.
> +The most important user of the XArray is the page cache.
> +
> +A freshly-initialised XArray contains a ``NULL`` pointer at every index.
> +Each non-``NULL`` entry in the array has three bits associated with
> +it called tags. Each tag may be flipped on or off independently of
> +the others. You can search for entries with a given tag set.
Only tags that are set, or search for entries with some tag(s) cleared?
Or is that like a mathematical set?
> +Normal pointers may be stored in the XArray directly. They must be 4-byte
> +aligned, which is true for any pointer returned from :c:func:`kmalloc` and
> +:c:func:`alloc_page`. It isn't true for arbitrary user-space pointers,
> +nor for function pointers. You can store pointers to statically allocated
> +objects, as long as those objects have an alignment of at least 4.
This (above) is due to the internal usage of low bits for flags?
> +The XArray does not support storing :c:func:`IS_ERR` pointers; some
> +conflict with data values and others conflict with entries the XArray
> +uses for its own purposes. If you need to store special values which
> +cannot be confused with real kernel pointers, the values 4, 8, ... 4092
> +are available.
or if I know that they values are errno-range values, I can just shift them
left by 2 to store them and then shift them right by 2 to use them?
oh, or use the following function?
> +You can also store integers between 0 and ``LONG_MAX`` in the XArray.
> +You must first convert it into an entry using :c:func:`xa_mk_value`.
> +When you retrieve an entry from the XArray, you can check whether it is
> +a data value by calling :c:func:`xa_is_value`, and convert it back to
> +an integer by calling :c:func:`xa_to_value`.
> +
> +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. Setting a tag on one index will set it on all of them.
> +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.
> +
> +Normal API
> +==========
> +
> +Start by initialising an XArray, either with :c:func:`DEFINE_XARRAY`
> +for statically allocated XArrays or :c:func:`xa_init` for dynamically
> +allocated ones.
> +
> +You can then set entries using :c:func:`xa_store` and get entries
> +using :c:func:`xa_load`. xa_store will overwrite any entry with the
> +new entry and return the previous entry stored at that index. If you
> +store %NULL, the XArray does not need to allocate memory. You can call
> +:c:func:`xa_erase` to avoid inventing a GFP flags value. There is no
> +difference between an entry that has never been stored to and one that
> +has most recently had %NULL stored to it.
> +
> +You can conditionally replace an entry at an index by using
> +:c:func:`xa_cmpxchg`. Like :c:func:`cmpxchg`, it will only succeed if
> +the entry at that index has the 'old' value. It also returns the entry
> +which was at that index; if it returns the same entry which was passed as
> +'old', then :c:func:`xa_cmpxchg` succeeded.
> +
> +You can enquire whether a tag is set on an entry by using
> +:c:func:`xa_get_tag`. If the entry is not ``NULL``, you can set a tag
> +on it by using :c:func:`xa_set_tag` and remove the tag from an entry by
> +calling :c:func:`xa_clear_tag`. You can ask whether any entry in the
an entry
> +XArray has a particular tag set by calling :c:func:`xa_tagged`.
or maybe I don't understand. Does xa_tagged() test one entry and return its
"tagged" result/status? or does it test (potentially) the entire array to search
for a particular tag value?
> +You can copy entries out of the XArray into a plain array by
> +calling :c:func:`xa_get_entries` and copy tagged entries by calling
> +:c:func:`xa_get_tagged`. Or you can iterate over the non-``NULL``
> +entries in place 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.
> +
> +Finally, you can remove all entries from an XArray by calling
> +:c:func:`xa_destroy`. If the XArray entries are pointers, you may
> +wish to free the entries first. You can do this by iterating over
> +all non-``NULL`` entries in the XArray using the :c:func:`xa_for_each`
> +iterator.
> +
> +When using the Normal API, you do not have to worry about locking.
> +The XArray uses RCU and an irq-safe spinlock to synchronise access to
> +the XArray:
[snip]
> +Advanced API
> +============
> +
> +The advanced API offers more flexibility and better performance at the
> +cost of an interface which can be harder to use and has fewer safeguards.
> +No locking is done for you by the advanced API, and you are required
> +to use the xa_lock while modifying the array. You can choose whether
> +to use the xa_lock or the RCU lock while doing read-only operations on
> +the array. You can mix advanced and normal operations on the same array;
> +indeed the normal API is implemented in terms of the advanced API. The
> +advanced API is only available to modules with a GPL-compatible license.
> +
> +The advanced API is based around the xa_state. This is an opaque data
> +structure which you declare on the stack using the :c:func:`XA_STATE`
> +macro. This macro initialises the xa_state ready to start walking
> +around the XArray. It is used as a cursor to maintain the position
> +in the XArray and let you compose various operations together without
> +having to restart from the top every time.
> +
> +The xa_state is also used to store errors. You can call
> +:c:func:`xas_error` to retrieve the error. All operations check whether
> +the xa_state is in an error state before proceeding, so there's no need
> +for you to check for an error after each call; you can make multiple
> +calls in succession and only check at a convenient point. The only error
> +currently generated by the xarray code itself is %ENOMEM, but it supports
> +arbitrary errors in case you want to call :c:func:`xas_set_err` yourself.
> +
> +If the xa_state is holding an %ENOMEM error, calling :c:func:`xas_nomem`
> +will attempt to allocate more memory using the specified gfp flags and
> +cache it in the xa_state for the next attempt. The idea is that you take
> +the xa_lock, attempt the operation and drop the lock. The operation
> +attempts to allocate memory while holding the lock, but it is more
> +likely to fail. Once you have dropped the lock, :c:func:`xas_nomem`
> +can try harder to allocate more memory. It will return ``true`` if it
> +is worth retrying the operation (ie that there was a memory error *and*
usually i.e.
> +more memory was allocated. If it has previously allocated memory, and
allocated).
> +that memory wasn't used, and there is no error (or some error that isn't
> +%ENOMEM), then it will free the memory previously allocated.
> +
> +Some users wish to hold the xa_lock for their own purpose while performing
> +one simple XArray operation, and then some other operation of their
> +own, protected by the same lock. While they could declare an xa_state
> +and use it to call one of the usual advanced API functions, it is a
> +little cumbersome. These interfaces are added on demand; at the moment,
> +:c:func:`__xa_erase`, :c:func:`__xa_set_tag` and :c:func:`__xa_clear_tag`
> +are available.
> +
> +Internal Entries
> +----------------
[snip]
> +Additional functionality
> +------------------------
> +
> +The :c:func:`xas_create` function ensures that there is somewhere in the
> +XArray to store an entry. It will store ENOMEM in the xa_state if it
> +cannot allocate memory. You do not normally need to call this function
> +yourself as it is called by :c:func:`xas_store`.
> +
> +You can use :c:func:`xas_init_tags` to reset the tags on an entry
> +to their default state. This is usually all tags clear, unless the
> +XArray is marked with ``XA_FLAGS_TRACK_FREE``, in which case tag 0 is set
> +and all other tags are clear. Replacing one entry with another using
> +:c:func:`xas_store` will not reset the tags on that entry; if you want
> +the tags reset, you should do that explicitly.
> +
> +The :c:func:`xas_load` will walk the xa_state as close to the entry
> +as it can. If you know the xa_state has already been walked to the
> +entry and need to check that the entry hasn't changed, you can use
> +:c:func:`xas_reload` to save a function call.
> +
> +If you need to move to a different index in the XArray, call
> +:c:func:`xas_set`. This reinitialises the cursor which will generally
I would put a comma .... here.......................^
but consult your $editor. :)
> +have the effect of making the next operation walk the cursor to the
> +desired spot in the tree. If you want to move to the next or previous
> +index, call :c:func:`xas_next` or :c:func:`xas_prev`. Setting the index
> +does not walk the cursor around the array so does not require a lock to
> +be held, while moving to the next or previous index does.
[snip]
Nicely done. Thanks.
--
~Randy
next prev parent reply other threads:[~2017-12-11 23:10 UTC|newest]
Thread overview: 127+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-12-06 0:40 [PATCH v4 00/73] XArray version 4 Matthew Wilcox
2017-12-06 0:40 ` [PATCH v4 01/73] xfs: Rename xa_ elements to ail_ Matthew Wilcox
2017-12-06 0:40 ` [PATCH v4 02/73] xarray: Add the xa_lock to the radix_tree_root Matthew Wilcox
2017-12-06 0:40 ` [PATCH v4 03/73] page cache: Use xa_lock Matthew Wilcox
2017-12-06 0:40 ` [PATCH v4 04/73] xarray: Replace exceptional entries Matthew Wilcox
2017-12-06 0:40 ` [PATCH v4 05/73] xarray: Change definition of sibling entries Matthew Wilcox
2017-12-06 0:40 ` [PATCH v4 06/73] xarray: Add definition of struct xarray Matthew Wilcox
2017-12-06 0:40 ` [PATCH v4 07/73] xarray: Define struct xa_node Matthew Wilcox
2017-12-06 0:40 ` [PATCH v4 08/73] xarray: Add documentation Matthew Wilcox
2017-12-11 23:10 ` Randy Dunlap [this message]
2017-12-15 4:22 ` Matthew Wilcox
2017-12-15 12:34 ` Naming of tag operations in the XArray Matthew Wilcox
2017-12-19 0:16 ` Randy Dunlap
2017-12-15 17:10 ` Storing errors " Matthew Wilcox
2017-12-19 0:27 ` Randy Dunlap
2017-12-06 0:40 ` [PATCH v4 09/73] xarray: Add xa_load Matthew Wilcox
2017-12-06 0:40 ` [PATCH v4 10/73] xarray: Add xa_get_tag, xa_set_tag and xa_clear_tag Matthew Wilcox
2017-12-06 0:40 ` [PATCH v4 11/73] xarray: Add xa_store Matthew Wilcox
2017-12-06 0:40 ` [PATCH v4 12/73] xarray: Add xa_cmpxchg Matthew Wilcox
2017-12-06 0:40 ` [PATCH v4 13/73] xarray: Add xa_for_each Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 14/73] xarray: Add xas_for_each_tag Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 15/73] xarray: Add xa_get_entries, xa_get_tagged and xa_get_maybe_tag Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 16/73] xarray: Add xa_destroy Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 17/73] xarray: Add xas_next and xas_prev Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 18/73] xarray: Add xas_create_range Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 19/73] xarray: Add MAINTAINERS entry Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 20/73] idr: Convert to XArray Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 21/73] ida: " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 22/73] page cache: Convert hole search " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 23/73] page cache: Add page_cache_range_empty function Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 24/73] page cache: Add and replace pages using the XArray Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 25/73] page cache: Convert page deletion to XArray Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 26/73] page cache: Convert page cache lookups " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 27/73] page cache: Convert delete_batch " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 28/73] page cache: Remove stray radix comment Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 29/73] mm: Convert page-writeback to XArray Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 30/73] mm: Convert workingset " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 31/73] mm: Convert truncate " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 32/73] mm: Convert add_to_swap_cache " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 33/73] mm: Convert delete_from_swap_cache " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 34/73] mm: Convert cgroup writeback " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 35/73] mm: Convert __do_page_cache_readahead " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 36/73] mm: Convert page migration " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 37/73] mm: Convert huge_memory " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 38/73] mm: Convert collapse_shmem " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 39/73] mm: Convert khugepaged_scan_shmem " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 40/73] pagevec: Use xa_tag_t Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 41/73] shmem: Convert replace to XArray Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 42/73] shmem: Convert shmem_confirm_swap " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 43/73] shmem: Convert find_swap_entry " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 44/73] shmem: Convert shmem_tag_pins " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 45/73] shmem: Convert shmem_wait_for_pins " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 46/73] shmem: Convert shmem_add_to_page_cache " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 47/73] shmem: Convert shmem_alloc_hugepage " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 48/73] shmem: Convert shmem_free_swap " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 49/73] shmem: Convert shmem_partial_swap_usage " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 50/73] shmem: Comment fixups Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 51/73] btrfs: Convert page cache to XArray Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 52/73] fs: Convert buffer " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 53/73] fs: Convert writeback " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 54/73] nilfs2: Convert " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 55/73] f2fs: " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 56/73] lustre: " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 57/73] dax: Convert dax_unlock_mapping_entry " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 58/73] dax: Convert lock_slot " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 59/73] dax: More XArray conversion Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 60/73] dax: Convert __dax_invalidate_mapping_entry to XArray Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 61/73] dax: Convert dax_writeback_one " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 62/73] dax: Convert dax_insert_pfn_mkwrite " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 63/73] dax: Convert dax_insert_mapping_entry " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 64/73] dax: Convert grab_mapping_entry " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 65/73] dax: Fix sparse warning Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 66/73] page cache: Finish XArray conversion Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 67/73] vmalloc: Convert to XArray Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 68/73] brd: " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 69/73] xfs: Convert m_perag_tree " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 70/73] xfs: Convert pag_ici_root " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 71/73] xfs: Convert xfs dquot " Matthew Wilcox
2017-12-06 0:41 ` [PATCH v4 72/73] xfs: Convert mru cache " Matthew Wilcox
2017-12-06 1:36 ` Dave Chinner
2017-12-06 2:02 ` Matthew Wilcox
2017-12-06 3:14 ` Dave Chinner
2017-12-06 4:45 ` Matthew Wilcox
2017-12-06 4:52 ` Matthew Wilcox
2017-12-06 8:44 ` Dave Chinner
2017-12-06 14:06 ` Matthew Wilcox
2017-12-07 0:38 ` Dave Chinner
2017-12-08 23:01 ` Matthew Wilcox
2017-12-10 23:57 ` Dave Chinner
2017-12-11 4:23 ` Matthew Wilcox
2017-12-11 21:55 ` Dave Chinner
2017-12-07 16:06 ` Theodore Ts'o
2017-12-07 22:22 ` Dave Chinner
2017-12-08 4:45 ` Byungchul Park
2017-12-08 7:25 ` Dave Chinner
2017-12-08 9:27 ` Byungchul Park
2017-12-08 17:35 ` Alan Stern
2017-12-08 22:36 ` Dave Chinner
2017-12-09 17:00 ` Joe Perches
2017-12-11 21:43 ` Dave Chinner
2017-12-11 22:12 ` Joe Perches
2017-12-11 22:43 ` Matthew Wilcox
2017-12-11 23:46 ` Joe Perches
2017-12-12 15:51 ` Alan Stern
2017-12-14 18:23 ` Joe Perches
2017-12-17 1:26 ` [RFC patch] checkpatch: Add a test for long function definitions (>200 lines) Joe Perches
2017-12-17 21:46 ` Linus Torvalds
2017-12-17 22:22 ` Joe Perches
2017-12-17 22:33 ` Luc Van Oostenryck
2017-12-11 23:38 ` [PATCH v4 72/73] xfs: Convert mru cache to XArray Dave Chinner
2017-12-21 12:05 ` Knut Omang
2017-12-07 22:38 ` Lockdep is less useful than it was Matthew Wilcox
2017-12-07 22:39 ` Matthew Wilcox
2017-12-08 0:14 ` Dave Chinner
2017-12-08 15:27 ` Theodore Ts'o
2017-12-08 18:14 ` Matthew Wilcox
2017-12-08 22:47 ` Dave Chinner
2017-12-06 0:41 ` [PATCH v4 73/73] usb: Convert xhci-mem to XArray Matthew Wilcox
2017-12-06 1:45 ` [PATCH v4 00/73] XArray version 4 Dave Chinner
2017-12-06 1:51 ` Dave Chinner
2017-12-06 1:53 ` Matthew Wilcox
2017-12-06 2:17 ` Dave Chinner
2017-12-06 2:27 ` Matthew Wilcox
2017-12-06 2:05 ` Matthew Wilcox
2017-12-06 2:38 ` Dave Chinner
2017-12-06 23:58 ` Ross Zwisler
2017-12-07 0:13 ` Matthew Wilcox
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=66ad068b-1973-ca41-7bbf-8a0634cc488d@infradead.org \
--to=rdunlap@infradead.org \
--cc=aquannie@gmail.com \
--cc=axboe@kernel.dk \
--cc=linux-btrfs@vger.kernel.org \
--cc=linux-f2fs-devel@lists.sourceforge.net \
--cc=linux-fsdevel@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-mm@kvack.org \
--cc=linux-nilfs@vger.kernel.org \
--cc=linux-usb@vger.kernel.org \
--cc=linux-xfs@vger.kernel.org \
--cc=mawilcox@microsoft.com \
--cc=ross.zwisler@linux.intel.com \
--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).