xref: /freebsd/share/man/man9/zone.9 (revision 20ed0cb0c66d78b85d47e5c3d1d937979634f7cc)
10aa028ffSDag-Erling Smørgrav.\"-
20aa028ffSDag-Erling Smørgrav.\" Copyright (c) 2001 Dag-Erling Co�dan Sm�rgrav
30aa028ffSDag-Erling Smørgrav.\" All rights reserved.
40aa028ffSDag-Erling Smørgrav.\"
50aa028ffSDag-Erling Smørgrav.\" Redistribution and use in source and binary forms, with or without
60aa028ffSDag-Erling Smørgrav.\" modification, are permitted provided that the following conditions
70aa028ffSDag-Erling Smørgrav.\" are met:
80aa028ffSDag-Erling Smørgrav.\" 1. Redistributions of source code must retain the above copyright
90aa028ffSDag-Erling Smørgrav.\"    notice, this list of conditions and the following disclaimer.
100aa028ffSDag-Erling Smørgrav.\" 2. Redistributions in binary form must reproduce the above copyright
110aa028ffSDag-Erling Smørgrav.\"    notice, this list of conditions and the following disclaimer in the
120aa028ffSDag-Erling Smørgrav.\"    documentation and/or other materials provided with the distribution.
130aa028ffSDag-Erling Smørgrav.\"
140aa028ffSDag-Erling Smørgrav.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
150aa028ffSDag-Erling Smørgrav.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
160aa028ffSDag-Erling Smørgrav.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
170aa028ffSDag-Erling Smørgrav.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
180aa028ffSDag-Erling Smørgrav.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
190aa028ffSDag-Erling Smørgrav.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
200aa028ffSDag-Erling Smørgrav.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
210aa028ffSDag-Erling Smørgrav.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
220aa028ffSDag-Erling Smørgrav.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
230aa028ffSDag-Erling Smørgrav.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
240aa028ffSDag-Erling Smørgrav.\" SUCH DAMAGE.
250aa028ffSDag-Erling Smørgrav.\"
260aa028ffSDag-Erling Smørgrav.\" $FreeBSD$
270aa028ffSDag-Erling Smørgrav.\"
28c4ae7908SLawrence Stewart.Dd October 9, 2010
290aa028ffSDag-Erling Smørgrav.Dt ZONE 9
300aa028ffSDag-Erling Smørgrav.Os
310aa028ffSDag-Erling Smørgrav.Sh NAME
32382682b2SJeroen Ruigrok van der Werven.Nm uma_zcreate ,
337c32182eSJeroen Ruigrok van der Werven.Nm uma_zalloc ,
346a4c41d1SRemko Lodder.Nm uma_zalloc_arg ,
357c32182eSJeroen Ruigrok van der Werven.Nm uma_zfree ,
366a4c41d1SRemko Lodder.Nm uma_zfree_arg ,
37d7bbb21aSHartmut Brandt.Nm uma_zdestroy ,
38c4ae7908SLawrence Stewart.Nm uma_zone_set_max,
39c4ae7908SLawrence Stewart.Nm uma_zone_get_max,
40c4ae7908SLawrence Stewart.Nm uma_zone_get_cur
41f5fccbbcSDag-Erling Smørgrav.Nd zone allocator
420aa028ffSDag-Erling Smørgrav.Sh SYNOPSIS
4332eef9aeSRuslan Ermilov.In sys/param.h
44f16b3c0dSChad David.In sys/queue.h
453a347a6eSJeroen Ruigrok van der Werven.In vm/uma.h
46382682b2SJeroen Ruigrok van der Werven.Ft uma_zone_t
479be1948fSRuslan Ermilov.Fo uma_zcreate
489be1948fSRuslan Ermilov.Fa "char *name" "int size"
499be1948fSRuslan Ermilov.Fa "uma_ctor ctor" "uma_dtor dtor" "uma_init uminit" "uma_fini fini"
509be1948fSRuslan Ermilov.Fa "int align" "u_int16_t flags"
519be1948fSRuslan Ermilov.Fc
529be1948fSRuslan Ermilov.Ft "void *"
539be1948fSRuslan Ermilov.Fn uma_zalloc "uma_zone_t zone" "int flags"
546a4c41d1SRemko Lodder.Ft "void *"
556a4c41d1SRemko Lodder.Fn uma_zalloc_arg "uma_zone_t zone" "void *arg" "int flags"
560aa028ffSDag-Erling Smørgrav.Ft void
57f1de92e6SJeroen Ruigrok van der Werven.Fn uma_zfree "uma_zone_t zone" "void *item"
585ca0c84eSThomas Moestl.Ft void
596a4c41d1SRemko Lodder.Fn uma_zfree_arg "uma_zone_t zone" "void *item" "void *arg"
606a4c41d1SRemko Lodder.Ft void
61f1de92e6SJeroen Ruigrok van der Werven.Fn uma_zdestroy "uma_zone_t zone"
621c6cae97SLawrence Stewart.Ft int
63d7bbb21aSHartmut Brandt.Fn uma_zone_set_max "uma_zone_t zone" "int nitems"
64c4ae7908SLawrence Stewart.Ft int
65c4ae7908SLawrence Stewart.Fn uma_zone_get_max "uma_zone_t zone"
66c4ae7908SLawrence Stewart.Ft int
67c4ae7908SLawrence Stewart.Fn uma_zone_get_cur "uma_zone_t zone"
680aa028ffSDag-Erling Smørgrav.Sh DESCRIPTION
690aa028ffSDag-Erling SmørgravThe zone allocator provides an efficient interface for managing
700aa028ffSDag-Erling Smørgravdynamically-sized collections of items of similar size.
710aa028ffSDag-Erling SmørgravThe zone allocator can work with preallocated zones as well as with
720aa028ffSDag-Erling Smørgravruntime-allocated ones, and is therefore available much earlier in the
730aa028ffSDag-Erling Smørgravboot process than other memory management routines.
740aa028ffSDag-Erling Smørgrav.Pp
750aa028ffSDag-Erling SmørgravA zone is an extensible collection of items of identical size.
760aa028ffSDag-Erling SmørgravThe zone allocator keeps track of which items are in use and which
77008080bdSJeroen Ruigrok van der Wervenare not, and provides functions for allocating items from the zone and
780aa028ffSDag-Erling Smørgravfor releasing them back (which makes them available for later use).
790aa028ffSDag-Erling Smørgrav.Pp
80ced699e3SRuslan ErmilovAfter the first allocation of an item,
8190d83886SJulian Elischerit will have been cleared to zeroes, however subsequent allocations
827251f557SKonstantin Belousovwill retain the contents as of the last free.
8390d83886SJulian Elischer.Pp
84382682b2SJeroen Ruigrok van der WervenThe
85382682b2SJeroen Ruigrok van der Werven.Fn uma_zcreate
86382682b2SJeroen Ruigrok van der Wervenfunction creates a new zone from which items may then be allocated from.
87382682b2SJeroen Ruigrok van der WervenThe
88382682b2SJeroen Ruigrok van der Werven.Fa name
89382682b2SJeroen Ruigrok van der Wervenargument is a text name of the zone for debugging and stats; this memory
90382682b2SJeroen Ruigrok van der Wervenshould not be freed until the zone has been deallocated.
91382682b2SJeroen Ruigrok van der Werven.Pp
924919e8cbSAlfred PerlsteinThe
934919e8cbSAlfred Perlstein.Fa ctor
944919e8cbSAlfred Perlsteinand
954919e8cbSAlfred Perlstein.Fa dtor
964919e8cbSAlfred Perlsteinarguments are callback functions that are called by
974919e8cbSAlfred Perlsteinthe uma subsystem at the time of the call to
984919e8cbSAlfred Perlstein.Fn uma_zalloc
994919e8cbSAlfred Perlsteinand
1004919e8cbSAlfred Perlstein.Fn uma_zfree
101d962d52aSRuslan Ermilovrespectively.
102d962d52aSRuslan ErmilovTheir purpose is to provide hooks for initializing or
1034919e8cbSAlfred Perlsteindestroying things that need to be done at the time of the allocation
104d962d52aSRuslan Ermilovor release of a resource.
105e07f1d5fSHiten PandyaA good usage for the
1064919e8cbSAlfred Perlstein.Fa ctor
1074919e8cbSAlfred Perlsteinand
1084919e8cbSAlfred Perlstein.Fa dtor
1094919e8cbSAlfred Perlsteincallbacks
1104919e8cbSAlfred Perlsteinmight be to adjust a global count of the number of objects allocated.
1114919e8cbSAlfred Perlstein.Pp
1124919e8cbSAlfred PerlsteinThe
1134919e8cbSAlfred Perlstein.Fa uminit
1144919e8cbSAlfred Perlsteinand
1154919e8cbSAlfred Perlstein.Fa fini
1164919e8cbSAlfred Perlsteinarguments are used to optimize the allocation of
117d962d52aSRuslan Ermilovobjects from the zone.
118d962d52aSRuslan ErmilovThey are called by the uma subsystem whenever
1194919e8cbSAlfred Perlsteinit needs to allocate or free several items to satisfy requests or memory
120d962d52aSRuslan Ermilovpressure.
121d962d52aSRuslan ErmilovA good use for the
122d962d52aSRuslan Ermilov.Fa uminit
123d962d52aSRuslan Ermilovand
124d962d52aSRuslan Ermilov.Fa fini
125d962d52aSRuslan Ermilovcallbacks might be to
126d962d52aSRuslan Ermilovinitialize and destroy mutexes contained within the object.
127d962d52aSRuslan ErmilovThis would
1284919e8cbSAlfred Perlsteinallow one to re-use already initialized mutexes when an object is returned
129d962d52aSRuslan Ermilovfrom the uma subsystem's object cache.
130d962d52aSRuslan ErmilovThey are not called on each call to
1314919e8cbSAlfred Perlstein.Fn uma_zalloc
1324919e8cbSAlfred Perlsteinand
1334919e8cbSAlfred Perlstein.Fn uma_zfree
1344919e8cbSAlfred Perlsteinbut rather in a batch mode on several objects.
1354919e8cbSAlfred Perlstein.Pp
1360aa028ffSDag-Erling SmørgravTo allocate an item from a zone, simply call
1377c32182eSJeroen Ruigrok van der Werven.Fn uma_zalloc
1381437c79aSJeroen Ruigrok van der Wervenwith a pointer to that zone
1391437c79aSJeroen Ruigrok van der Wervenand set the
140acff84fbSJeroen Ruigrok van der Werven.Fa flags
141acff84fbSJeroen Ruigrok van der Wervenargument to selected flags as documented in
142acff84fbSJeroen Ruigrok van der Werven.Xr malloc 9 .
1431437c79aSJeroen Ruigrok van der WervenIt will return a pointer to an item if successful,
1441437c79aSJeroen Ruigrok van der Wervenor
1450aa028ffSDag-Erling Smørgrav.Dv NULL
1460aa028ffSDag-Erling Smørgravin the rare case where all items in the zone are in use and the
1471437c79aSJeroen Ruigrok van der Wervenallocator is unable to grow the zone
1481437c79aSJeroen Ruigrok van der Wervenor when
1491437c79aSJeroen Ruigrok van der Werven.Dv M_NOWAIT
1501437c79aSJeroen Ruigrok van der Wervenis specified.
1510aa028ffSDag-Erling Smørgrav.Pp
1520aa028ffSDag-Erling SmørgravItems are released back to the zone from which they were allocated by
1530aa028ffSDag-Erling Smørgravcalling
1547c32182eSJeroen Ruigrok van der Werven.Fn uma_zfree
1550aa028ffSDag-Erling Smørgravwith a pointer to the zone and a pointer to the item.
156*20ed0cb0SMatthew D FlemingIf
157*20ed0cb0SMatthew D Fleming.Fa item
158*20ed0cb0SMatthew D Flemingis
159*20ed0cb0SMatthew D Fleming.Dv NULL ,
160*20ed0cb0SMatthew D Flemingthen
161*20ed0cb0SMatthew D Fleming.Fn uma_zfree
162*20ed0cb0SMatthew D Flemingdoes nothing.
1635ca0c84eSThomas Moestl.Pp
1646a4c41d1SRemko LodderThe variations
1656a4c41d1SRemko Lodder.Fn uma_zalloc_arg
1666a4c41d1SRemko Lodderand
1676a4c41d1SRemko Lodder.Fn uma_zfree_arg
1686a4c41d1SRemko Lodderallow to
1696a4c41d1SRemko Lodderspecify an argument for the
1706a4c41d1SRemko Lodder.Dv ctor
1716a4c41d1SRemko Lodderand
1726a4c41d1SRemko Lodder.Dv dtor
1736a4c41d1SRemko Lodderfunctions, respectively.
1746a4c41d1SRemko Lodder.Pp
17555407559SJeroen Ruigrok van der WervenCreated zones,
17655407559SJeroen Ruigrok van der Wervenwhich are empty,
1775ca0c84eSThomas Moestlcan be destroyed using
1787c32182eSJeroen Ruigrok van der Werven.Fn uma_zdestroy ,
1795ca0c84eSThomas Moestlfreeing all memory that was allocated for the zone.
1805ca0c84eSThomas MoestlAll items allocated from the zone with
1817c32182eSJeroen Ruigrok van der Werven.Fn uma_zalloc
1825ca0c84eSThomas Moestlmust have been freed with
1837c32182eSJeroen Ruigrok van der Werven.Fn uma_zfree
1845ca0c84eSThomas Moestlbefore.
185d7bbb21aSHartmut Brandt.Pp
186c4ae7908SLawrence StewartThe
187d7bbb21aSHartmut Brandt.Fn uma_zone_set_max
188c4ae7908SLawrence Stewartfunction limits the number of items
189c4ae7908SLawrence Stewart.Pq and therefore memory
190c4ae7908SLawrence Stewartthat can be allocated to
191c4ae7908SLawrence Stewart.Fa zone .
192d7bbb21aSHartmut BrandtThe
193d7bbb21aSHartmut Brandt.Fa nitems
194c4ae7908SLawrence Stewartargument specifies the requested upper limit number of items.
1951c6cae97SLawrence StewartThe effective limit is returned to the caller, as it may end up being higher
1961c6cae97SLawrence Stewartthan requested due to the implementation rounding up to ensure all memory pages
1971c6cae97SLawrence Stewartallocated to the zone are utilised to capacity.
198c4ae7908SLawrence StewartThe limit applies to the total number of items in the zone, which includes
199d7bbb21aSHartmut Brandtallocated items, free items and free items in the per-cpu caches.
200d7bbb21aSHartmut BrandtOn systems with more than one CPU it may not be possible to allocate
201d7bbb21aSHartmut Brandtthe specified number of items even when there is no shortage of memory,
202d7bbb21aSHartmut Brandtbecause all of the remaining free items may be in the caches of the
203d7bbb21aSHartmut Brandtother CPUs when the limit is hit.
204c4ae7908SLawrence Stewart.Pp
205c4ae7908SLawrence StewartThe
206c4ae7908SLawrence Stewart.Fn uma_zone_get_max
207c4ae7908SLawrence Stewartfunction returns the effective upper limit number of items for a zone.
208c4ae7908SLawrence Stewart.Pp
209c4ae7908SLawrence StewartThe
210c4ae7908SLawrence Stewart.Fn uma_zone_get_cur
211c4ae7908SLawrence Stewartfunction returns the approximate current occupancy of the zone.
212c4ae7908SLawrence StewartThe returned value is approximate because appropriate synchronisation to
213c4ae7908SLawrence Stewartdetermine an exact value is not performend by the implementation.
214c4ae7908SLawrence StewartThis ensures low overhead at the expense of potentially stale data being used
215c4ae7908SLawrence Stewartin the calculation.
2160aa028ffSDag-Erling Smørgrav.Sh RETURN VALUES
2170aa028ffSDag-Erling SmørgravThe
2187c32182eSJeroen Ruigrok van der Werven.Fn uma_zalloc
2190aa028ffSDag-Erling Smørgravfunction returns a pointer to an item, or
2200aa028ffSDag-Erling Smørgrav.Dv NULL
2210aa028ffSDag-Erling Smørgravif the zone ran out of unused items and the allocator was unable to
2220aa028ffSDag-Erling Smørgravenlarge it.
2230aa028ffSDag-Erling Smørgrav.Sh SEE ALSO
2240aa028ffSDag-Erling Smørgrav.Xr malloc 9
2250aa028ffSDag-Erling Smørgrav.Sh HISTORY
2260aa028ffSDag-Erling SmørgravThe zone allocator first appeared in
2270aa028ffSDag-Erling Smørgrav.Fx 3.0 .
2289a795583SJeroen Ruigrok van der WervenIt was radically changed in
2299a795583SJeroen Ruigrok van der Werven.Fx 5.0
2309a795583SJeroen Ruigrok van der Wervento function as a slab allocator.
2310aa028ffSDag-Erling Smørgrav.Sh AUTHORS
2320aa028ffSDag-Erling Smørgrav.An -nosplit
2330aa028ffSDag-Erling SmørgravThe zone allocator was written by
2340aa028ffSDag-Erling Smørgrav.An John S. Dyson .
2359a795583SJeroen Ruigrok van der WervenThe zone allocator was rewritten in large parts by
2369a795583SJeroen Ruigrok van der Werven.An Jeff Roberson Aq jeff@FreeBSD.org
2379a795583SJeroen Ruigrok van der Wervento function as a slab allocator.
2380aa028ffSDag-Erling Smørgrav.Pp
2390aa028ffSDag-Erling SmørgravThis manual page was written by
24009e06539SDag-Erling Smørgrav.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .
2419a795583SJeroen Ruigrok van der WervenChanges for UMA by
2429a795583SJeroen Ruigrok van der Werven.An Jeroen Ruigrok van der Werven Aq asmodai@FreeBSD.org .
243