Documentation/core-api/idr.rst

   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: