.. | .. |
---|
20 | 20 | IDR usage |
---|
21 | 21 | ========= |
---|
22 | 22 | |
---|
23 | | -Start by initialising an IDR, either with :c:func:`DEFINE_IDR` |
---|
24 | | -for statically allocated IDRs or :c:func:`idr_init` for dynamically |
---|
| 23 | +Start by initialising an IDR, either with DEFINE_IDR() |
---|
| 24 | +for statically allocated IDRs or idr_init() for dynamically |
---|
25 | 25 | allocated IDRs. |
---|
26 | 26 | |
---|
27 | | -You can call :c:func:`idr_alloc` to allocate an unused ID. Look up |
---|
28 | | -the pointer you associated with the ID by calling :c:func:`idr_find` |
---|
29 | | -and free the ID by calling :c:func:`idr_remove`. |
---|
| 27 | +You can call idr_alloc() to allocate an unused ID. Look up |
---|
| 28 | +the pointer you associated with the ID by calling idr_find() |
---|
| 29 | +and free the ID by calling idr_remove(). |
---|
30 | 30 | |
---|
31 | 31 | If you need to change the pointer associated with an ID, you can call |
---|
32 | | -:c:func:`idr_replace`. One common reason to do this is to reserve an |
---|
| 32 | +idr_replace(). One common reason to do this is to reserve an |
---|
33 | 33 | ID by passing a ``NULL`` pointer to the allocation function; initialise the |
---|
34 | 34 | object with the reserved ID and finally insert the initialised object |
---|
35 | 35 | into the IDR. |
---|
36 | 36 | |
---|
37 | 37 | Some users need to allocate IDs larger than ``INT_MAX``. So far all of |
---|
38 | 38 | these users have been content with a ``UINT_MAX`` limit, and they use |
---|
39 | | -:c:func:`idr_alloc_u32`. If you need IDs that will not fit in a u32, |
---|
| 39 | +idr_alloc_u32(). If you need IDs that will not fit in a u32, |
---|
40 | 40 | we will work with you to address your needs. |
---|
41 | 41 | |
---|
42 | 42 | If you need to allocate IDs sequentially, you can use |
---|
43 | | -:c:func:`idr_alloc_cyclic`. The IDR becomes less efficient when dealing |
---|
| 43 | +idr_alloc_cyclic(). The IDR becomes less efficient when dealing |
---|
44 | 44 | with larger IDs, so using this function comes at a slight cost. |
---|
45 | 45 | |
---|
46 | 46 | To perform an action on all pointers used by the IDR, you can |
---|
47 | | -either use the callback-based :c:func:`idr_for_each` or the |
---|
48 | | -iterator-style :c:func:`idr_for_each_entry`. You may need to use |
---|
49 | | -:c:func:`idr_for_each_entry_continue` to continue an iteration. You can |
---|
50 | | -also use :c:func:`idr_get_next` if the iterator doesn't fit your needs. |
---|
| 47 | +either use the callback-based idr_for_each() or the |
---|
| 48 | +iterator-style idr_for_each_entry(). You may need to use |
---|
| 49 | +idr_for_each_entry_continue() to continue an iteration. You can |
---|
| 50 | +also use idr_get_next() if the iterator doesn't fit your needs. |
---|
51 | 51 | |
---|
52 | | -When you have finished using an IDR, you can call :c:func:`idr_destroy` |
---|
| 52 | +When you have finished using an IDR, you can call idr_destroy() |
---|
53 | 53 | to release the memory used by the IDR. This will not free the objects |
---|
54 | 54 | pointed to from the IDR; if you want to do that, use one of the iterators |
---|
55 | 55 | to do it. |
---|
56 | 56 | |
---|
57 | | -You can use :c:func:`idr_is_empty` to find out whether there are any |
---|
| 57 | +You can use idr_is_empty() to find out whether there are any |
---|
58 | 58 | IDs currently allocated. |
---|
59 | 59 | |
---|
60 | 60 | If you need to take a lock while allocating a new ID from the IDR, |
---|
61 | 61 | you may need to pass a restrictive set of GFP flags, which can lead |
---|
62 | 62 | to the IDR being unable to allocate memory. To work around this, |
---|
63 | | -you can call :c:func:`idr_preload` before taking the lock, and then |
---|
64 | | -:c:func:`idr_preload_end` after the allocation. |
---|
| 63 | +you can call idr_preload() before taking the lock, and then |
---|
| 64 | +idr_preload_end() after the allocation. |
---|
65 | 65 | |
---|
66 | 66 | .. kernel-doc:: include/linux/idr.h |
---|
67 | 67 | :doc: idr sync |
---|