.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source.  A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright 2016 Joyent, Inc.
.\"
.Dd Aug 02, 2016
.Dt ID_SPACE 9F
.Os
.Sh NAME
.Nm id_space ,
.Nm id_space_create ,
.Nm id_space_destroy ,
.Nm id_space_extend ,
.Nm id_alloc ,
.Nm id_alloc_nosleep ,
.Nm id_allocff ,
.Nm id_allocff_nosleep ,
.Nm id_alloc_specific_nosleep ,
.Nm id_free
.Nd create, destroy, and use identifier spaces
.Sh SYNOPSIS
.In sys/id_space.h
.Ft "id_space_t *"
.Fo id_space_create
.Fa "const char *name"
.Fa "id_t low"
.Fa "id_t high"
.Fc
.Ft void
.Fo id_space_destroy
.Fa "id_space_t *idspace"
.Fc
.Ft void
.Fo id_space_extend
.Fa "id_t low"
.Fa "id_t high"
.Fc
.Ft id_t
.Fo id_alloc
.Fa "id_space_t *idspace"
.Fc
.Ft id_t
.Fo id_alloc_nosleep
.Fa "id_space_t *idspace"
.Fc
.Ft id_t
.Fo id_allocff
.Fa "id_space_t *idspace"
.Fc
.Ft id_t
.Fo id_allocff_nosleep
.Fa "id_space_t *idspace"
.Fc
.Ft id_t
.Fo id_allocff_specific_nosleep
.Fa "id_space_t *idspace"
.Fa "id_t id"
.Fc
.Ft void
.Fo id_free
.Fa "id_space_t *idspace"
.Fa "id_t id"
.Fc
.Sh INTERFACE STABILITY
illumos DDI specific
.Sh PARAMETERS
.Bl -tag -width Fa
.It Fa idspace
A pointer to an
.Sy id_space_t
structure allocated with the
.Fn id_space_create
function.
.It Fa id
An identifier, a signed 32-bit integer.
.It Fa name
An ASCII character string to call the identifier space.
.It Fa low
The lower end of an identifier space.
This value is included in the range.
.It Fa high
The upper end of an identifier space.
This value is excluded from the range.
.El
.Sh DESCRIPTION
The
.Sy id_space
suite of functions is used to create and manage identifier spaces.
An identifier space allows the system to manage a range of identifiers.
It tracks what values have been used and which values have not been used
and has different ways of allocating values from the identifier space.
.Pp
Identifier spaces are often used by device drivers to manage ranges of
numeric identifiers that may be disjoint.
A common use case for identifier spaces is to manage the set of allocated minor
numbers for a device driver.
.Ss Creating, Expanding and Destroying Identifier Spaces
To create an identifier space, the
.Fn id_space_create
function should be used.
A name for the id space must be passed in the
.Fa name
argument.
It should be unique.
For device drivers, often combining the name of the driver and the instance from
the
.Xr ddi_get_instance 9F
function results in a unique name.
.Pp
The values of
.Fa low
and
.Fa high
describe the range of the identifier space.
The range is inclusive on the low end and exclusive on the high end.
Mathematically, this would be represented as
.Pf [ Fa low ,
.Fa high Ns ).
.Pp
Once the
.Fn id_space_create
function has been successfully called, the returned identifier space can
be used to allocate and manage identifiers.
.Pp
Once an identifier space has been created, additional ranges of
identifiers can be added.
This process allows for disjoint ranges of values to be added to a single
identifier space.
The
.Fn id_space_extend
function is used to do this, and it adds the range
.Fa low
to
.Fa high
to the identifier space.
The range follows the same rules as with the
.Fn id_space_create
function.
It is inclusive of
.Fa low
and is exclusive of
.Fa high .
.Pp
Finally, when an identifier space is no longer being used and all of its
identifiers have been freed, the caller should call the
.Fn id_space_destroy
function to destroy the id space
.Fa idspace .
.Pp
All three of these functions,
.Fn id_space_create ,
.Fn id_space_extend ,
and
.Fn id_space_destroy
may block.
They should only be called from a context where it's safe for it to block.
This is equivalent to performing a blocking memory allocation.
.Ss Allocating Identifiers
Once an id space has been created with the
.Fn id_space_create
function, identifiers can be allocated from the space.
There are three different strategies for allocating an identifier:
.Bl -enum
.It
Allocating an identifier using the standard algorithm that attempts to
use the next identifier first.
.It
Allocating an identifier using a first fit algorithm.
These are functions with
.Em ff
in the name.
Using this will tend to keep the allocated id space more compressed.
.It
Allocating a specific id.
.El
.Pp
In addition, identifiers can be allocated in both a blocking and
non-blocking fashion.
When functions with the
.Sy _nosleep
prefix are used, they are non-blocking.
If no identifier is available, they will return an error.
.Pp
The
.Fn id_alloc
function will allocate the next identifier.
The
.Fn id_alloc_nosleep
function uses the same algorithm as
.Fn id_alloc ,
but will fail rather than block.
.Pp
The
.Fn id_allocff
function will allocate the first available identifier.
The
.Fn id_allocff_nosleep
function uses the same algorithm as
.Fn id_allocff ,
but will fail rather than block.
.Pp
The
.Fn id_alloc_specific_nosleep
function attempts to allocate the specific identifier
.Fa id
from the specified identifier space.
If
.Fa id
has already been allocated, then the function will fail.
.Ss Freeing Identifiers
Every allocated identifier must eventually be freed and returned to the
identifier space.
To free an identifier, use the
.Fn id_free
function, specifying the identifier in
.Fa id
and the identifier space it came from in
.Fa id_space .
It is a programmer error to call the
.Fn id_free
function on an identifier that has not been allocated.
.Sh CONTEXT
All of these functions may be called in
.Sy user
or
.Sy kernel
context.
The
.Fn id_alloc_nosleep ,
.Fn id_allocff_nosleep ,
and
.Fn id_alloc_specific_nosleep
functions may be called in
.Sy interrupt
context.
.Sh RETURN VALUES
Upon successful completion, the
.Fn id_space_create
function returns a pointer to an identifier space.
Otherwise,
.Dv NULL
is returned to indicate that the identifier space could not be created.
.Pp
The
.Fn id_alloc
and
.Fn id_allocff
functions always return an identifier that's in the range of the
specified identifier space.
.Pp
Upon successful completion, the
.Fn id_alloc_nosleep ,
.Fn id_allocff_nosleep ,
and
.Fn id_alloc_specific_nosleep
functions will return an identifier that's in the range of the specified
identifier space.
Otherwise,
.Sy -1
is returned to indicate that no identifier was available, or in the case
of the
.Fn id_alloc_specific_nosleep
function, that the specified identifier was not available.
.Sh SEE ALSO
.Xr kmem_alloc 9F ,
.Xr rmallocmap 9F