1.\"- 2.\" Copyright (c) 2001 Dag-Erling Coïdan Smørgrav 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd March 21, 2013 29.Dt ZONE 9 30.Os 31.Sh NAME 32.Nm uma_zcreate , 33.Nm uma_zalloc , 34.Nm uma_zalloc_arg , 35.Nm uma_zfree , 36.Nm uma_zfree_arg , 37.Nm uma_find_refcnt , 38.Nm uma_zdestroy , 39.Nm uma_zone_set_max, 40.Nm uma_zone_get_max, 41.Nm uma_zone_get_cur, 42.Nm uma_zone_set_warning 43.Nd zone allocator 44.Sh SYNOPSIS 45.In sys/param.h 46.In sys/queue.h 47.In vm/uma.h 48.Ft uma_zone_t 49.Fo uma_zcreate 50.Fa "char *name" "int size" 51.Fa "uma_ctor ctor" "uma_dtor dtor" "uma_init uminit" "uma_fini fini" 52.Fa "int align" "uint16_t flags" 53.Fc 54.Ft "void *" 55.Fn uma_zalloc "uma_zone_t zone" "int flags" 56.Ft "void *" 57.Fn uma_zalloc_arg "uma_zone_t zone" "void *arg" "int flags" 58.Ft void 59.Fn uma_zfree "uma_zone_t zone" "void *item" 60.Ft void 61.Fn uma_zfree_arg "uma_zone_t zone" "void *item" "void *arg" 62.Ft "uint32_t *" 63.Fn uma_find_refcnt "uma_zone_t zone" "void *item" 64.Ft void 65.Fn uma_zdestroy "uma_zone_t zone" 66.Ft int 67.Fn uma_zone_set_max "uma_zone_t zone" "int nitems" 68.Ft int 69.Fn uma_zone_get_max "uma_zone_t zone" 70.Ft int 71.Fn uma_zone_get_cur "uma_zone_t zone" 72.Ft void 73.Fn uma_zone_set_warning "uma_zone_t zone" "const char *warning" 74.Sh DESCRIPTION 75The zone allocator provides an efficient interface for managing 76dynamically-sized collections of items of similar size. 77The zone allocator can work with preallocated zones as well as with 78runtime-allocated ones, and is therefore available much earlier in the 79boot process than other memory management routines. 80.Pp 81A zone is an extensible collection of items of identical size. 82The zone allocator keeps track of which items are in use and which 83are not, and provides functions for allocating items from the zone and 84for releasing them back (which makes them available for later use). 85.Pp 86After the first allocation of an item, 87it will have been cleared to zeroes, however subsequent allocations 88will retain the contents as of the last free. 89.Pp 90The 91.Fn uma_zcreate 92function creates a new zone from which items may then be allocated from. 93The 94.Fa name 95argument is a text name of the zone for debugging and stats; this memory 96should not be freed until the zone has been deallocated. 97.Pp 98The 99.Fa ctor 100and 101.Fa dtor 102arguments are callback functions that are called by 103the uma subsystem at the time of the call to 104.Fn uma_zalloc 105and 106.Fn uma_zfree 107respectively. 108Their purpose is to provide hooks for initializing or 109destroying things that need to be done at the time of the allocation 110or release of a resource. 111A good usage for the 112.Fa ctor 113and 114.Fa dtor 115callbacks 116might be to adjust a global count of the number of objects allocated. 117.Pp 118The 119.Fa uminit 120and 121.Fa fini 122arguments are used to optimize the allocation of 123objects from the zone. 124They are called by the uma subsystem whenever 125it needs to allocate or free several items to satisfy requests or memory 126pressure. 127A good use for the 128.Fa uminit 129and 130.Fa fini 131callbacks might be to 132initialize and destroy mutexes contained within the object. 133This would 134allow one to re-use already initialized mutexes when an object is returned 135from the uma subsystem's object cache. 136They are not called on each call to 137.Fn uma_zalloc 138and 139.Fn uma_zfree 140but rather in a batch mode on several objects. 141.Pp 142The 143.Fa flags 144argument of the 145.Fn uma_zcreate 146is a subset of the following flags: 147.Bl -tag -width "foo" 148.It Dv UMA_ZONE_NOFREE 149Slabs of the zone are never returned back to VM. 150.It Dv UMA_ZONE_REFCNT 151Each item in the zone would have internal reference counter associated with it. 152See 153.Fn uma_find_refcnt . 154.It Dv UMA_ZONE_NODUMP 155Pages belonging to the zone will not be included into mini-dumps. 156.It Dv UMA_ZONE_OFFPAGE 157By default book-keeping of items within a slab is done in the slab page itself. 158This flag explicitly tells subsystem that book-keeping structure should be 159allocated separately from special internal zone. 160This flag requires either 161.Dv UMA_ZONE_VTOSLAB 162or 163.Dv UMA_ZONE_HASH , 164since subsystem requires a mechanism to find a book-keeping structure 165to an item beeing freed. 166The subsystem may choose to prefer offpage book-keeping for certain zones 167implicitly. 168.It Dv UMA_ZONE_ZINIT 169The zone will have its 170.Ft uma_init 171method set to internal method that initializes a new allocated slab 172to all zeros. 173Don't mistake 174.Ft uma_init 175method with 176.Ft uma_ctor . 177A zone with 178.Dv UMA_ZONE_ZINIT 179flag would not return zeroed memory on every 180.Fn uma_zalloc . 181.It Dv UMA_ZONE_HASH 182The zone should use an internal hash table to find slab book-keeping 183structure where an allocation being freed belongs to. 184.It Dv UMA_ZONE_VTOSLAB 185The zone should use special field of 186.Vt vm_page_t 187to find slab book-keeping structure where an allocation being freed belongs to. 188.It Dv UMA_ZONE_MALLOC 189The zone is for the 190.Xr malloc 9 191subsystem. 192.It Dv UMA_ZONE_VM 193The zone is for the VM subsystem. 194.El 195.Pp 196To allocate an item from a zone, simply call 197.Fn uma_zalloc 198with a pointer to that zone 199and set the 200.Fa flags 201argument to selected flags as documented in 202.Xr malloc 9 . 203It will return a pointer to an item if successful, 204or 205.Dv NULL 206in the rare case where all items in the zone are in use and the 207allocator is unable to grow the zone 208and 209.Dv M_NOWAIT 210is specified. 211.Pp 212Items are released back to the zone from which they were allocated by 213calling 214.Fn uma_zfree 215with a pointer to the zone and a pointer to the item. 216If 217.Fa item 218is 219.Dv NULL , 220then 221.Fn uma_zfree 222does nothing. 223.Pp 224The variations 225.Fn uma_zalloc_arg 226and 227.Fn uma_zfree_arg 228allow to 229specify an argument for the 230.Dv ctor 231and 232.Dv dtor 233functions, respectively. 234.Pp 235If zone was created with 236.Dv UMA_ZONE_REFCNT 237flag, then pointer to reference counter for an item can be retrieved with 238help of the 239.Fn uma_find_refcnt 240function. 241.Pp 242Created zones, 243which are empty, 244can be destroyed using 245.Fn uma_zdestroy , 246freeing all memory that was allocated for the zone. 247All items allocated from the zone with 248.Fn uma_zalloc 249must have been freed with 250.Fn uma_zfree 251before. 252.Pp 253The 254.Fn uma_zone_set_max 255function limits the number of items 256.Pq and therefore memory 257that can be allocated to 258.Fa zone . 259The 260.Fa nitems 261argument specifies the requested upper limit number of items. 262The effective limit is returned to the caller, as it may end up being higher 263than requested due to the implementation rounding up to ensure all memory pages 264allocated to the zone are utilised to capacity. 265The limit applies to the total number of items in the zone, which includes 266allocated items, free items and free items in the per-cpu caches. 267On systems with more than one CPU it may not be possible to allocate 268the specified number of items even when there is no shortage of memory, 269because all of the remaining free items may be in the caches of the 270other CPUs when the limit is hit. 271.Pp 272The 273.Fn uma_zone_get_max 274function returns the effective upper limit number of items for a zone. 275.Pp 276The 277.Fn uma_zone_get_cur 278function returns the approximate current occupancy of the zone. 279The returned value is approximate because appropriate synchronisation to 280determine an exact value is not performed by the implementation. 281This ensures low overhead at the expense of potentially stale data being used 282in the calculation. 283.Pp 284The 285.Fn uma_zone_set_warning 286function sets a warning that will be printed on the system console when the 287given zone becomes full and fails to allocate an item. 288The warning will be printed not often than every five minutes. 289Warnings can be turned off globally by setting the 290.Va vm.zone_warnings 291sysctl tunable to 292.Va 0 . 293.Sh RETURN VALUES 294The 295.Fn uma_zalloc 296function returns a pointer to an item, or 297.Dv NULL 298if the zone ran out of unused items 299and 300.Dv M_NOWAIT 301was specified. 302.Sh SEE ALSO 303.Xr malloc 9 304.Sh HISTORY 305The zone allocator first appeared in 306.Fx 3.0 . 307It was radically changed in 308.Fx 5.0 309to function as a slab allocator. 310.Sh AUTHORS 311.An -nosplit 312The zone allocator was written by 313.An John S. Dyson . 314The zone allocator was rewritten in large parts by 315.An Jeff Roberson Aq jeff@FreeBSD.org 316to function as a slab allocator. 317.Pp 318This manual page was written by 319.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org . 320Changes for UMA by 321.An Jeroen Ruigrok van der Werven Aq asmodai@FreeBSD.org . 322