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
66 You can then set entries using xa_store() and get entries
68 new entry and return the previous entry stored at that index. You can
74 You can conditionally replace an entry at an index by using
80 If you want to only store a new entry to an index if the current entry
81 at that index is ``NULL``, you can use xa_insert() which
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
87 You may prefer to use xa_find() or xa_find_after() to move to the next
91 of indices. If you do this, some of the other operations will behave
97 Sometimes you need to ensure that a subsequent call to xa_store()
100 normal API will see this entry as containing ``NULL``. If you do
101 not need to use the reserved entry, you can call xa_release()
103 in the meantime, xa_release() will do nothing; if instead you
104 want the entry to become ``NULL``, you should use xa_erase().
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
119 Each mark may be set or cleared independently of the others. You can
122 You can enquire whether a mark is set on an entry by using
123 xa_get_mark(). If the entry is not ``NULL``, you can set a mark on it
125 xa_clear_mark(). You can ask whether any entry in the XArray has a
143 If you use DEFINE_XARRAY_ALLOC() to define the XArray, or
147 You can call xa_alloc() to store the entry at an unused index
148 in the XArray. If you need to modify the array from interrupt context,
149 you can use xa_alloc_bh() or xa_alloc_irq() to disable
156 you only want to free the entry if it's ``NULL``).
158 By default, the lowest free entry is allocated starting from 0. If you
160 DEFINE_XARRAY_ALLOC1() or ``XA_FLAGS_ALLOC1``. If you want to
162 ID, you can use xa_alloc_cyclic().
164 You cannot use ``XA_MARK_0`` with an allocating XArray as this mark
177 It is possible for no memory to be allocatable, particularly if you pass
180 If you don't need to know exactly which error occurred, using
186 When using the Normal API, you do not have to worry about locking.
236 If you want to take advantage of the lock to protect the data structures
237 that you are storing in the XArray, you can call xa_lock()
239 object you have found before calling xa_unlock(). This will
241 up the object and incrementing the refcount. You can also use RCU to
249 If, for example, you want to store entries in the XArray in process
250 context and then erase them in softirq context, you can do that this way::
278 If you are going to modify the XArray from interrupt or softirq context,
279 you need to initialise the array using xa_init_flags(), passing
294 Sometimes you need to protect access to the XArray with a mutex because
296 not entitle you to use functions like __xa_erase() without taking
301 available for situations where you look up an entry and want to atomically
303 in this case, as it will save you from walking the tree twice.
310 No locking is done for you by the advanced API, and you are required
311 to use the xa_lock while modifying the array. You can choose whether
313 the array. You can mix advanced and normal operations on the same array;
318 structure which you declare on the stack using the XA_STATE() macro.
321 and let you compose various operations together without having to restart
323 the rcu_read_lock() or the xas_lock(). If you need to drop whichever of
324 those locks is protecting your state and tree, you must call xas_pause()
328 The xa_state is also used to store errors. You can call
331 for you to check for an error after each call; you can make multiple
334 ``EINVAL``, but it supports arbitrary errors in case you want to call
339 cache it in the xa_state for the next attempt. The idea is that you take
342 likely to fail. Once you have dropped the lock, xas_nomem()
377 of this RCU period. You should restart the lookup from the head
397 You can use xas_init_marks() to reset the marks on an entry
401 xas_store() will not reset the marks on that entry; if you want
402 the marks reset, you should do that explicitly.
405 as it can. If you know the xa_state has already been walked to the
406 entry and need to check that the entry hasn't changed, you can use
409 If you need to move to a different index in the XArray, call
412 spot in the tree. If you want to move to the next or previous index,
417 You can search for the next present entry using xas_find(). This
435 After you have done the necessary work and wish to resume, the xa_state
437 you last processed. If you have interrupts disabled while iterating,
443 XArray; they will do nothing if you have called xas_pause() or xas_set()
446 You can call xas_set_update() to have a callback function
464 You can create a multi-index entry by using XA_STATE_ORDER()