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 May 18, 2002 29.Dt ZONE 9 30.Os 31.Sh NAME 32.Nm uma_zcreate , 33.Nm uma_zalloc , 34.Nm uma_zfree , 35.Nm uma_zdestroy 36.Nd zone allocator 37.Sh SYNOPSIS 38.In sys/param.h 39.In sys/queue.h 40.In vm/uma.h 41.Ft uma_zone_t 42.Fo uma_zcreate 43.Fa "char *name" "int size" 44.Fa "uma_ctor ctor" "uma_dtor dtor" "uma_init uminit" "uma_fini fini" 45.Fa "int align" "u_int16_t flags" 46.Fc 47.Ft "void *" 48.Fn uma_zalloc "uma_zone_t zone" "int flags" 49.Ft void 50.Fn uma_zfree "uma_zone_t zone" "void *item" 51.Ft void 52.Fn uma_zdestroy "uma_zone_t zone" 53.Sh DESCRIPTION 54The zone allocator provides an efficient interface for managing 55dynamically-sized collections of items of similar size. 56The zone allocator can work with preallocated zones as well as with 57runtime-allocated ones, and is therefore available much earlier in the 58boot process than other memory management routines. 59.Pp 60A zone is an extensible collection of items of identical size. 61The zone allocator keeps track of which items are in use and which 62are not, and provides functions for allocating items from the zone and 63for releasing them back (which makes them available for later use). 64.Pp 65The zone allocator stores state information inside the items proper 66while they are not allocated, 67so structures that will be managed by the zone allocator 68and wish to use the type stable property of zones by leaving some fields 69pre-filled between allocations, must reserve 70two pointers at the very beginning for internal use by the zone 71allocator, as follows: 72.Bd -literal -offset indent 73struct my_item { 74 struct my_item *z_rsvd1; 75 struct my_item *z_rsvd2; 76 /* rest of structure */ 77}; 78.Ed 79.Pp 80Alternatively they should assume those entries corrupted 81after each allocation. 82After the first allocation of an item, 83it will have been cleared to zeroes, however subsequent allocations 84will retain the contents as of the last free, with the exception of the 85fields mentioned above. 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 95To allocate an item from a zone, simply call 96.Fn uma_zalloc 97with a pointer to that zone 98and set the 99.Fa flags 100argument to selected flags as documented in 101.Xr malloc 9 . 102It will return a pointer to an item if successful, 103or 104.Dv NULL 105in the rare case where all items in the zone are in use and the 106allocator is unable to grow the zone 107or when 108.Dv M_NOWAIT 109is specified. 110.Pp 111Items are released back to the zone from which they were allocated by 112calling 113.Fn uma_zfree 114with a pointer to the zone and a pointer to the item. 115.Pp 116Created zones, 117which are empty, 118can be destroyed using 119.Fn uma_zdestroy , 120freeing all memory that was allocated for the zone. 121All items allocated from the zone with 122.Fn uma_zalloc 123must have been freed with 124.Fn uma_zfree 125before. 126.Sh RETURN VALUES 127The 128.Fn uma_zalloc 129function returns a pointer to an item, or 130.Dv NULL 131if the zone ran out of unused items and the allocator was unable to 132enlarge it. 133.Sh SEE ALSO 134.Xr malloc 9 135.Sh HISTORY 136The zone allocator first appeared in 137.Fx 3.0 . 138It was radically changed in 139.Fx 5.0 140to function as a slab allocator. 141.Sh AUTHORS 142.An -nosplit 143The zone allocator was written by 144.An John S. Dyson . 145The zone allocator was rewritten in large parts by 146.An Jeff Roberson Aq jeff@FreeBSD.org 147to function as a slab allocator. 148.Pp 149This manual page was written by 150.An Dag-Erling Co\(:idan Sm\(/orgrav Aq des@FreeBSD.org . 151Changes for UMA by 152.An Jeroen Ruigrok van der Werven Aq asmodai@FreeBSD.org . 153