1 .. SPDX-License-Identifier: GPL-2.0+ 2 3 ============= 4 ID Allocation 5 ============= 6 7 :Author: Matthew Wilcox 8 9 Overview 10 ======== 11 12 A common problem to solve is allocating identifiers (IDs); generally 13 small numbers which identify a thing. Examples include file descriptors, 14 process IDs, packet identifiers in networking protocols, SCSI tags 15 and device instance numbers. The IDR and the IDA provide a reasonable 16 solution to the problem to avoid everybody inventing their own. The IDR 17 provides the ability to map an ID to a pointer, while the IDA provides 18 only ID allocation, and as a result is much more memory-efficient. 19 20 The IDR interface is deprecated; please use the :doc:`XArray <xarray>` 21 instead. 22 23 IDR usage 24 ========= 25 26 Start by initialising an IDR, either with DEFINE_IDR() 27 for statically allocated IDRs or idr_init() for dynamically 28 allocated IDRs. 29 30 You can call idr_alloc() to allocate an unused ID. Look up 31 the pointer you associated with the ID by calling idr_find() 32 and free the ID by calling idr_remove(). 33 34 If you need to change the pointer associated with an ID, you can call 35 idr_replace(). One common reason to do this is to reserve an 36 ID by passing a ``NULL`` pointer to the allocation function; initialise the 37 object with the reserved ID and finally insert the initialised object 38 into the IDR. 39 40 Some users need to allocate IDs larger than ``INT_MAX``. So far all of 41 these users have been content with a ``UINT_MAX`` limit, and they use 42 idr_alloc_u32(). If you need IDs that will not fit in a u32, 43 we will work with you to address your needs. 44 45 If you need to allocate IDs sequentially, you can use 46 idr_alloc_cyclic(). The IDR becomes less efficient when dealing 47 with larger IDs, so using this function comes at a slight cost. 48 49 To perform an action on all pointers used by the IDR, you can 50 either use the callback-based idr_for_each() or the 51 iterator-style idr_for_each_entry(). You may need to use 52 idr_for_each_entry_continue() to continue an iteration. You can 53 also use idr_get_next() if the iterator doesn't fit your needs. 54 55 When you have finished using an IDR, you can call idr_destroy() 56 to release the memory used by the IDR. This will not free the objects 57 pointed to from the IDR; if you want to do that, use one of the iterators 58 to do it. 59 60 You can use idr_is_empty() to find out whether there are any 61 IDs currently allocated. 62 63 If you need to take a lock while allocating a new ID from the IDR, 64 you may need to pass a restrictive set of GFP flags, which can lead 65 to the IDR being unable to allocate memory. To work around this, 66 you can call idr_preload() before taking the lock, and then 67 idr_preload_end() after the allocation. 68 69 .. kernel-doc:: include/linux/idr.h 70 :doc: idr sync 71 72 IDA usage 73 ========= 74 75 .. kernel-doc:: lib/idr.c 76 :doc: IDA description 77 78 Functions and structures 79 ======================== 80 81 .. kernel-doc:: include/linux/idr.h 82 :functions: 83 .. kernel-doc:: lib/idr.c 84 :functions:
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.