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 December 7, 2012 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_zdestroy , 38.Nm uma_zone_set_max, 39.Nm uma_zone_get_max, 40.Nm uma_zone_get_cur, 41.Nm uma_zone_set_warning 42.Nd zone allocator 43.Sh SYNOPSIS 44.In sys/param.h 45.In sys/queue.h 46.In vm/uma.h 47.Ft uma_zone_t 48.Fo uma_zcreate 49.Fa "char *name" "int size" 50.Fa "uma_ctor ctor" "uma_dtor dtor" "uma_init uminit" "uma_fini fini" 51.Fa "int align" "uint16_t flags" 52.Fc 53.Ft "void *" 54.Fn uma_zalloc "uma_zone_t zone" "int flags" 55.Ft "void *" 56.Fn uma_zalloc_arg "uma_zone_t zone" "void *arg" "int flags" 57.Ft void 58.Fn uma_zfree "uma_zone_t zone" "void *item" 59.Ft void 60.Fn uma_zfree_arg "uma_zone_t zone" "void *item" "void *arg" 61.Ft void 62.Fn uma_zdestroy "uma_zone_t zone" 63.Ft int 64.Fn uma_zone_set_max "uma_zone_t zone" "int nitems" 65.Ft int 66.Fn uma_zone_get_max "uma_zone_t zone" 67.Ft int 68.Fn uma_zone_get_cur "uma_zone_t zone" 69.Ft void 70.Fn uma_zone_set_warning "uma_zone_t zone" "const char *warning" 71.Sh DESCRIPTION 72The zone allocator provides an efficient interface for managing 73dynamically-sized collections of items of similar size. 74The zone allocator can work with preallocated zones as well as with 75runtime-allocated ones, and is therefore available much earlier in the 76boot process than other memory management routines. 77.Pp 78A zone is an extensible collection of items of identical size. 79The zone allocator keeps track of which items are in use and which 80are not, and provides functions for allocating items from the zone and 81for releasing them back (which makes them available for later use). 82.Pp 83After the first allocation of an item, 84it will have been cleared to zeroes, however subsequent allocations 85will retain the contents as of the last free. 86.Pp 87The 88.Fn uma_zcreate 89function creates a new zone from which items may then be allocated from. 90The 91.Fa name 92argument is a text name of the zone for debugging and stats; this memory 93should not be freed until the zone has been deallocated. 94.Pp 95The 96.Fa ctor 97and 98.Fa dtor 99arguments are callback functions that are called by 100the uma subsystem at the time of the call to 101.Fn uma_zalloc 102and 103.Fn uma_zfree 104respectively. 105Their purpose is to provide hooks for initializing or 106destroying things that need to be done at the time of the allocation 107or release of a resource. 108A good usage for the 109.Fa ctor 110and 111.Fa dtor 112callbacks 113might be to adjust a global count of the number of objects allocated. 114.Pp 115The 116.Fa uminit 117and 118.Fa fini 119arguments are used to optimize the allocation of 120objects from the zone. 121They are called by the uma subsystem whenever 122it needs to allocate or free several items to satisfy requests or memory 123pressure. 124A good use for the 125.Fa uminit 126and 127.Fa fini 128callbacks might be to 129initialize and destroy mutexes contained within the object. 130This would 131allow one to re-use already initialized mutexes when an object is returned 132from the uma subsystem's object cache. 133They are not called on each call to 134.Fn uma_zalloc 135and 136.Fn uma_zfree 137but rather in a batch mode on several objects. 138.Pp 139To allocate an item from a zone, simply call 140.Fn uma_zalloc 141with a pointer to that zone 142and set the 143.Fa flags 144argument to selected flags as documented in 145.Xr malloc 9 . 146It will return a pointer to an item if successful, 147or 148.Dv NULL 149in the rare case where all items in the zone are in use and the 150allocator is unable to grow the zone 151and 152.Dv M_NOWAIT 153is specified. 154.Pp 155Items are released back to the zone from which they were allocated by 156calling 157.Fn uma_zfree 158with a pointer to the zone and a pointer to the item. 159If 160.Fa item 161is 162.Dv NULL , 163then 164.Fn uma_zfree 165does nothing. 166.Pp 167The variations 168.Fn uma_zalloc_arg 169and 170.Fn uma_zfree_arg 171allow to 172specify an argument for the 173.Dv ctor 174and 175.Dv dtor 176functions, respectively. 177.Pp 178Created zones, 179which are empty, 180can be destroyed using 181.Fn uma_zdestroy , 182freeing all memory that was allocated for the zone. 183All items allocated from the zone with 184.Fn uma_zalloc 185must have been freed with 186.Fn uma_zfree 187before. 188.Pp 189The 190.Fn uma_zone_set_max 191function limits the number of items 192.Pq and therefore memory 193that can be allocated to 194.Fa zone . 195The 196.Fa nitems 197argument specifies the requested upper limit number of items. 198The effective limit is returned to the caller, as it may end up being higher 199than requested due to the implementation rounding up to ensure all memory pages 200allocated to the zone are utilised to capacity. 201The limit applies to the total number of items in the zone, which includes 202allocated items, free items and free items in the per-cpu caches. 203On systems with more than one CPU it may not be possible to allocate 204the specified number of items even when there is no shortage of memory, 205because all of the remaining free items may be in the caches of the 206other CPUs when the limit is hit. 207.Pp 208The 209.Fn uma_zone_get_max 210function returns the effective upper limit number of items for a zone. 211.Pp 212The 213.Fn uma_zone_get_cur 214function returns the approximate current occupancy of the zone. 215The returned value is approximate because appropriate synchronisation to 216determine an exact value is not performed by the implementation. 217This ensures low overhead at the expense of potentially stale data being used 218in the calculation. 219.Pp 220The 221.Fn uma_zone_set_warning 222function sets a warning that will be printed on the system console when the 223given zone becomes full and fails to allocate an item. 224The warning will be printed not often than every five minutes. 225Warnings can be turned off globally by setting the 226.Va vm.zone_warnings 227sysctl tunable to 228.Va 0 . 229.Sh RETURN VALUES 230The 231.Fn uma_zalloc 232function returns a pointer to an item, or 233.Dv NULL 234if the zone ran out of unused items 235and 236.Dv M_NOWAIT 237was specified. 238.Sh SEE ALSO 239.Xr malloc 9 240.Sh HISTORY 241The zone allocator first appeared in 242.Fx 3.0 . 243It was radically changed in 244.Fx 5.0 245to function as a slab allocator. 246.Sh AUTHORS 247.An -nosplit 248The zone allocator was written by 249.An John S. Dyson . 250The zone allocator was rewritten in large parts by 251.An Jeff Roberson Aq jeff@FreeBSD.org 252to function as a slab allocator. 253.Pp 254This manual page was written by 255.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org . 256Changes for UMA by 257.An Jeroen Ruigrok van der Werven Aq asmodai@FreeBSD.org . 258