1.\" 2.\" Copyright (c) 2010, The DragonFly Project. 3.\" 4.\" This software is derived from software contributed to the DragonFly Project 5.\" by Venkatesh Srinivas <me@endeavour.zapto.org>. 6.\" 7.\" Permission to use, copy, modify, or distribute this software for any 8.\" purpose with or without fee is hereby granted, provided that the above 9.\" copyright notice and this permission notice appear in all copies. 10.\" 11.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 12.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 13.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 14.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR OTHER DAMAGES 15.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA, OR PROFITS, WHETHER IN AN 16.\" ACTION OF CONTRACT, NEGLIGENCE, OR OTHER TORTIOUS ACTION, ARISING OUT OF 17.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 18.\" 19.Dd December 21, 2010 20.Dt MPIPE 9 21.Os 22.Sh NAME 23.Nm mpipe_init , 24.Nm mpipe_done , 25.Nm mpipe_alloc_nowait , 26.Nm mpipe_alloc_waitok , 27.Nm mpipe_free 28.Nd malloc pipelines 29.Sh SYNOPSIS 30.In sys/mpipe.h 31.Ft void 32.Fn mpipe_init "malloc_pipe_t mpipe" "malloc_type_t type" "int bytes" \ 33"int nnom" "int nmax" "int mpflags" \ 34"void (*construct)(void *, void *)" \ 35"void (*deconstruct)(void *, void *)" \ 36"void *priv" 37.Ft void 38.Fn mpipe_done "malloc_pipe_t mpipe" 39.Ft void * 40.Fn mpipe_alloc_nowait "malloc_pipe_t mpipe" 41.Ft void * 42.Fn mpipe_alloc_waitok "malloc_pipe_t mpipe" 43.Ft void 44.Fn mpipe_free "malloc_pipe_t mpipe" "void *buf" 45.Sh DESCRIPTION 46.Pp 47A malloc pipeline is a linear pool of buffers of a single type. 48A malloc 49pipeline guarantees a number of outstanding allocations and provides both 50blocking and non-blocking behavior above the guaranteed allocation amounts. 51A malloc pipeline can have an upper limit, beyond which allocations sleep 52or fail respectively. 53Malloc pipelines are intended for situations where 54a minimum number of buffers are required to make progress. 55.Pp 56The 57.Fn mpipe_init 58function initializes a malloc pipeline 59.Fa mpipe . 60The pipeline allocates buffers of size 61.Fa bytes 62from the malloc zone 63.Fa type . 64The pipeline is prefilled with 65.Fa nnom 66buffers and has a limit of 67.Fa nmax 68buffers. 69The 70.Fa construct 71argument is a callback, invoked when a buffer is allocated from the system. 72The 73.Fa deconstruct 74argument is a callback, invoked when the malloc pipeline is destroyed or a 75buffer is freed to the system. 76Both 77.Fa construct 78and 79.Fa deconstruct 80are invoked with the buffer address as their first parameter and with 81.Fa priv 82as their second parameter. 83The 84.Fa flags 85argument controls allocation parameters: 86.Bl -tag -width ".Dv MPF_NOZERO" -offset indent 87.It Dv MPF_NOZERO 88Do not zero allocated buffers. 89.It Dv MPF_CACHEDATA 90By default, MPIPE buffers are zeroed on free; this flag disables that behavior. 91.It Dv MPF_INT 92Allocations may use the interrupt memory reserve. 93.El 94.Pp 95This function may block. 96.Pp 97The 98.Fn mpipe_done 99function destroys a malloc pipeline. 100The pipeline's destructor is invoked on 101each buffer and then they are returned to the system. 102It is an error to invoke 103this function on a pipeline with outstanding allocations. 104This function may block. 105.Pp 106The 107.Fn mpipe_alloc_nowait 108function allocates a buffer from the malloc pipeline. 109It will first allocate from the pipeline itself; if that is exhausted, 110it will fall back on 111.Xr kmalloc 9 , 112up to the pipeline maximum. 113This function may not block. 114.Pp 115The 116.Fn mpipe_alloc_waitok 117function allocates a buffer from the malloc pipeline. 118It will first allocate from the pipeline; if that is exhausted, 119it will fall back on 120.Xr kmalloc 9 , 121up to the pipeline maximum. 122It will sleep if it reaches the maximum, potentially releasing any tokens. 123.Pp 124The 125.Fn mpipe_free 126function frees a buffer to the malloc pipeline. 127If the pipeline is full, it will free directly to the kernel allocator, 128calling the destructor as it does. 129This function may block. 130.Sh FILES 131The MPIPE implementation is in 132.Pa /sys/kern/kern_mpipe.c . 133.Sh SEE ALSO 134.Xr kmalloc 9 135.Sh HISTORY 136MPIPE first appeared in 137.Dx 1.0 . 138