Documentation/core-api/xarray.rst

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
49 conflict with value entries or internal entries.
51 An unusual feature of the XArray is the ability to create entries which
55 entries can be explicitly split into smaller entries, or storing ``NULL``
66 You can then set entries using xa_store() and get entries
84 You can copy entries out of the XArray into a plain array by calling
85 xa_extract().  Or you can iterate over the present entries in the XArray
107 If all entries in the array are ``NULL``, the xa_empty() function
110 Finally, you can remove all entries from an XArray by calling
111 xa_destroy().  If the XArray entries are pointers, you may wish
112 to free the entries first.  You can do this by iterating over all present
113 entries in the XArray using the xa_for_each() iterator.
120 iterate over marked entries by using the xa_for_each_marked() iterator.
133 There is no way to iterate over entries which are not marked; the data
136 iterate over all entries which have both ``XA_MARK_1`` and ``XA_MARK_2``
137 set, or iterate over all entries which have ``XA_MARK_0`` or ``XA_MARK_2``
145 the XArray changes to track whether entries are in use or not.
159 want to allocate entries starting at 1, it is more efficient to use
249 If, for example, you want to store entries in the XArray in process
345 Internal Entries
348 The XArray reserves some entries for its own purposes.  These are never
378      - Zero entries appear as ``NULL`` through the Normal API, but occupy
380        future use.  This is used by allocating XArrays for allocated entries
383 Other internal entries may be added in the future.  As far as possible, they
435 every ``XA_CHECK_SCHED`` entries.
445 shadow entries.
447 Multi-Index Entries
457 save substantial quantities of memory; for example tying 512 entries
467 entries in the range.  The xas_for_each_conflict() iterator will
480 reveal sibling entries; these should be skipped over by the caller.
484 entry can be split into entries occupying smaller ranges by calling