GeezerVisonThe World Wide Web, restored to 800 pixels of glory. |
| Home|About|Gaming cabinet|Archives|How it works|Starter sites |
GeezerVison is showing docs.kernel.org — ID Allocation — The Linux Kernel documentation
English
ID Allocation¶
Overview¶A common problem to solve is allocating identifiers (IDs); generally small numbers which identify a thing. Examples include file descriptors, process IDs, packet identifiers in networking protocols, SCSI tags and device instance numbers. The IDR and the IDA provide a reasonable solution to the problem to avoid everybody inventing their own. The IDR provides the ability to map an ID to a pointer, while the IDA provides only ID allocation, and as a result is much more memory-efficient. The IDR interface is deprecated; please use the XArray instead. IDR usage¶Start by initialising an IDR, either with You can call If you need to change the pointer associated with an ID, you can call
Some users need to allocate IDs larger than If you need to allocate IDs sequentially, you can use
To perform an action on all pointers used by the IDR, you can
either use the callback-based When you have finished using an IDR, you can call You can use If you need to take a lock while allocating a new ID from the IDR,
you may need to pass a restrictive set of GFP flags, which can lead
to the IDR being unable to allocate memory. To work around this,
you can call idr synchronization (stolen from radix-tree.h)
It is still required that the caller manage the synchronization and
lifetimes of the items. So if RCU lock-free lookups are used, typically
this would mean that the items have their own locks, or are amenable to
lock-free access; and that the items are freed by RCU (or only freed after
having been deleted from the idr tree and a IDA usage¶The IDA is an ID allocator which does not provide the ability to
associate an ID with a pointer. As such, it only needs to store one
bit per ID, and so is more space efficient than an IDR. To use an IDA,
define it using
The IDA handles its own locking. It is safe to call any of the IDA functions without synchronisation in your code. IDs are currently limited to the range [0-INT_MAX]. If this is an awkward limitation, it should be quite straightforward to raise the maximum. Functions and structures¶
Parameters
Description A freshly-initialised IDR contains no IDs.
Parameters
Description An IDR defined using this macro is ready for use with no additional initialisation required. It contains no IDs.
Parameters
Description The value returned is the value that will be next returned from
Parameters
Description The next call to Parameters
Description This variation of Parameters
Description Initialise a dynamically allocated IDR. To initialise a
statically allocated IDR, use Parameters
Return
Parameters
Description Each
Parameters
Description entry and id do not need to be initialized before the loop, and after normal termination entry is left with the value NULL. This is convenient for a “not found” value.
Parameters
Description entry and id do not need to be initialized before the loop, and after normal termination entry is left with the value NULL. This is convenient for a “not found” value.
Parameters
Description Continue to iterate over entries, continuing after the current position.
Parameters
Description Continue to iterate over entries, continuing after the current position. After normal termination entry is left with the value NULL. This is convenient for a “not found” value. Parameters
Description Allocate an ID between 0 and Context Any context. It is safe to call this function without locking in your code. Return The allocated ID, or Parameters
Description Allocate an ID between min and Context Any context. It is safe to call this function without locking in your code. Return The allocated ID, or Parameters
Description Allocate an ID between 0 and max, inclusive. Context Any context. It is safe to call this function without locking in your code. Return The allocated ID, or
Parameters
Description Allocates an unused ID in the range specified by nextid and max.
Note that max is inclusive whereas the end parameter to The caller should provide their own locking to ensure that two concurrent modifications to the IDR are not possible. Read-only accesses to the IDR may be done under the RCU read lock or may exclude simultaneous writers. Return 0 if an ID was allocated, -ENOMEM if memory allocation failed, or -ENOSPC if no free IDs could be found. If an error occurred, nextid is unchanged. Parameters
Description Allocates an unused ID in the range specified by start and end. If
end is <= 0, it is treated as one larger than The caller should provide their own locking to ensure that two concurrent modifications to the IDR are not possible. Read-only accesses to the IDR may be done under the RCU read lock or may exclude simultaneous writers. Return The newly allocated ID, -ENOMEM if memory allocation failed, or -ENOSPC if no free IDs could be found.
Parameters
Description Allocates an unused ID in the range specified by start and end. If
end is <= 0, it is treated as one larger than The caller should provide their own locking to ensure that two concurrent modifications to the IDR are not possible. Read-only accesses to the IDR may be done under the RCU read lock or may exclude simultaneous writers. Return The newly allocated ID, -ENOMEM if memory allocation failed, or -ENOSPC if no free IDs could be found. Parameters
Description Removes this ID from the IDR. If the ID was not previously in the IDR,
this function returns Since this function modifies the IDR, the caller should provide their own locking to ensure that concurrent modification of the same IDR is not possible. Return The pointer formerly associated with this ID. Parameters
Description Looks up the pointer associated with this ID. A This function can be called under Return The pointer associated with this ID.
Parameters
Description The callback function will be called for each entry in idr, passing the ID, the entry and data. If fn returns anything other than
Parameters
Description Returns the next populated entry in the tree with an ID greater than or equal to the value pointed to by nextid. On exit, nextid is updated to the ID of the found value. To use in a loop, the value pointed to by nextid must be incremented by the user. Parameters
Description Returns the next populated entry in the tree with an ID greater than or equal to the value pointed to by nextid. On exit, nextid is updated to the ID of the found value. To use in a loop, the value pointed to by nextid must be incremented by the user. Parameters
Description Replace the pointer registered with an ID and return the old value.
This function can be called under the RCU read lock concurrently with
Return the old value on success.
Parameters
Description Allocate an ID between min and max, inclusive. The allocated ID will
not exceed Context Any context. It is safe to call this function without locking in your code. Return The allocated ID, or
Parameters
Description Get the lowest used ID between min and max, inclusive. The returned
ID will not exceed Context Any context. Takes and releases the xa_lock. Return The lowest used ID, or errno if no used ID is found. Parameters
Context Any context. It is safe to call this function without locking in your code. Parameters
Description Calling this function frees all IDs and releases all resources used by an IDA. When this call returns, the IDA is empty and can be reused or freed. If the IDA is already empty, there is no need to call this function. Context Any context. It is safe to call this function without locking in your code. |
| You are visitor 01402503 — GeezerVison does not store the pages you look up. Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required. |