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