.\" Copyright (c) 2012 Vishesh Yadav
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\"
.Dd October 23, 2012
.Dt IDR 9
.Os
.Sh NAME
.Nm idr ,
.Nm idr_destroy ,
.Nm idr_find ,
.Nm idr_for_each ,
.Nm idr_get_new ,
.Nm idr_get_new_above ,
.Nm idr_init ,
.Nm idr_init1 ,
.Nm idr_pre_get ,
.Nm idr_remove ,
.Nm idr_remove_all ,
.Nm idr_replace
.Nd integer ID management library
.Sh SYNOPSIS
.In sys/idr.h
.Ft void
.Fn idr_destroy "struct idr *idp"
.Ft void *
.Fn idr_find "struct idr *idp" "int id"
.Ft int
.Fn idr_for_each "struct idr *idp" "int (*fn)(int id, void *p, void *data)" "void *data"
.Ft int
.Fn idr_get_new "struct idr *idp" "void *ptr" "int *id"
.Ft int
.Fn idr_get_new_above "struct idr *idp" "void *ptr" "int sid" "int *id"
.Ft void
.Fn idr_init "struct idr *idp"
.Ft void
.Fn idr_init1 "struct idr *idp" "int size"
.Ft int
.Fn idr_pre_get "struct idr *idp"
.Ft void
.Fn idr_remove "struct idr *idp" "int id"
.Ft void
.Fn idr_remove_all "struct idr *idp"
.Ft void *
.Fn idr_replace "struct idr *idp" "void *ptr" "int id"
.Sh DESCRIPTION
The
.Fn idr_destroy
function frees all resources taken by the specified
.Nm
handle
.Fa idp .
.Pp
The
.Fn idr_find
function returns the data pointer that is mapped with the specified
.Fa id .
.Pp
The
.Fn idr_for_each
function iterates through all pointers registered with the specified
.Nm
handle
.Fa idp
and calls the callback function
.Fn fn
for each pointer.
It is not safe to modify the
.Nm
tree through the callback function.
If the callback function returns a non-zero integer, it stops and returns the
value.
.Pp
The
.Fn idr_get_new
and
.Fn idr_get_new_above
functions allocate a new integer mapped with the specified pointer
.Fa ptr .
The new ID will be stored in
.Fa id .
If the tree becomes full, the functions function will return
.Er EAGAIN .
In this case,
.Fn idr_pre_get
should be called to grow the tree.
.Pp
The
.Fn idr_init
and
.Fn idr_init1
functions initialize an
.Nm
handle that will be used by other functions of the API.
.Fn idr_init
initializes a tree with a hard coded default initial capacity (32).
.Fn idr_init1
takes additional parameter
.Fa size
to set the initial capacity manually.
The
.Fn idr_pre_get
function should be called prior to calling the
.Fn idr_get_new*
functions.
It preallocates enough memory for subsequent calls to
.Fn idr_get_new*
functions.
This function should be called without any locks held.
It returns 0 if enough memory couldn't be allocated, otherwise 1.
This function lacks the
.Sq Vt gfp_t Va gfp_mask
parameter that is found in Linux version of this API.
.Pp
The
.Fn idr_remove
function removes the specified
.Fa id
from the tree.
.Pp
The
.Fn idr_remove_all
function removes all entries in the
.Nm
tree
.Fa idp .
.Pp
The
.Fn idr_replace
function replaces the pointer for the specified
.Fa id
with the new pointer
.Fa ptr .
It returns
.Dv NULL
if the pointer is not found.
This behavior is different from the Linux API.