Lines Matching full:you
14 resizable array. Unlike a hash, it allows you to sensibly go to the
25 ``ULONG_MAX`` then the XArray is not the data type for you. The most
31 nor for function pointers. You can store pointers to statically allocated
34 You can also store integers between 0 and ``LONG_MAX`` in the XArray.
35 You must first convert it into an entry using xa_mk_value().
36 When you retrieve an entry from the XArray, you can check whether it is
40 Some users want to tag the pointers they store in the XArray. You can
44 are used to distinguish value entries from normal pointers, so you must
45 decide whether you want to store value entries or tagged pointers in any
67 You can then set entries using xa_store() and get entries using
69 return the previous entry stored at that index. You can unset entries
76 You can conditionally replace an entry at an index by using
82 If you want to only store a new entry to an index if the current entry
83 at that index is ``NULL``, you can use xa_insert() which
86 You can copy entries out of the XArray into a plain array by calling
87 xa_extract(). Or you can iterate over the present entries in the XArray
89 You may prefer to use xa_find() or xa_find_after() to move to the next
93 of indices. If you do this, some of the other operations will behave
99 Sometimes you need to ensure that a subsequent call to xa_store()
102 normal API will see this entry as containing ``NULL``. If you do
103 not need to use the reserved entry, you can call xa_release()
105 in the meantime, xa_release() will do nothing; if instead you
106 want the entry to become ``NULL``, you should use xa_erase().
112 Finally, you can remove all entries from an XArray by calling
113 xa_destroy(). If the XArray entries are pointers, you may wish
114 to free the entries first. You can do this by iterating over all present
121 Each mark may be set or cleared independently of the others. You can
124 You can enquire whether a mark is set on an entry by using
125 xa_get_mark(). If the entry is not ``NULL``, you can set a mark on it
127 xa_clear_mark(). You can ask whether any entry in the XArray has a
145 If you use DEFINE_XARRAY_ALLOC() to define the XArray, or
149 You can call xa_alloc() to store the entry at an unused index
150 in the XArray. If you need to modify the array from interrupt context,
151 you can use xa_alloc_bh() or xa_alloc_irq() to disable
158 you only want to free the entry if it's ``NULL``).
160 By default, the lowest free entry is allocated starting from 0. If you
162 DEFINE_XARRAY_ALLOC1() or ``XA_FLAGS_ALLOC1``. If you want to
164 ID, you can use xa_alloc_cyclic().
166 You cannot use ``XA_MARK_0`` with an allocating XArray as this mark
179 It is possible for no memory to be allocatable, particularly if you pass
182 If you don't need to know exactly which error occurred, using
188 When using the Normal API, you do not have to worry about locking.
238 If you want to take advantage of the lock to protect the data structures
239 that you are storing in the XArray, you can call xa_lock()
241 object you have found before calling xa_unlock(). This will
243 up the object and incrementing the refcount. You can also use RCU to
251 If, for example, you want to store entries in the XArray in process
252 context and then erase them in softirq context, you can do that this way::
280 If you are going to modify the XArray from interrupt or softirq context,
281 you need to initialise the array using xa_init_flags(), passing
296 Sometimes you need to protect access to the XArray with a mutex because
298 not entitle you to use functions like __xa_erase() without taking
303 available for situations where you look up an entry and want to atomically
305 in this case, as it will save you from walking the tree twice.
312 No locking is done for you by the advanced API, and you are required
313 to use the xa_lock while modifying the array. You can choose whether
315 the array. You can mix advanced and normal operations on the same array;
320 structure which you declare on the stack using the XA_STATE() macro.
323 and let you compose various operations together without having to restart
325 the rcu_read_lock() or the xas_lock(). If you need to drop whichever of
326 those locks is protecting your state and tree, you must call xas_pause()
330 The xa_state is also used to store errors. You can call
333 for you to check for an error after each call; you can make multiple
336 ``EINVAL``, but it supports arbitrary errors in case you want to call
341 cache it in the xa_state for the next attempt. The idea is that you take
344 likely to fail. Once you have dropped the lock, xas_nomem()
379 of this RCU period. You should restart the lookup from the head
399 You can use xas_init_marks() to reset the marks on an entry
403 xas_store() will not reset the marks on that entry; if you want
404 the marks reset, you should do that explicitly.
407 as it can. If you know the xa_state has already been walked to the
408 entry and need to check that the entry hasn't changed, you can use
411 If you need to move to a different index in the XArray, call
414 spot in the tree. If you want to move to the next or previous index,
419 You can search for the next present entry using xas_find(). This
437 After you have done the necessary work and wish to resume, the xa_state
439 you last processed. If you have interrupts disabled while iterating,
445 XArray; they will do nothing if you have called xas_pause() or xas_set()
448 You can call xas_set_update() to have a callback function
466 You can create a multi-index entry by using XA_STATE_ORDER()