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