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 46A malloc pipeline is a linear pool of buffers of a single type. 47A malloc 48pipeline guarantees a number of outstanding allocations and provides both 49blocking and non-blocking behavior above the guaranteed allocation amounts. 50A malloc pipeline can have an upper limit, beyond which allocations sleep 51or fail respectively. 52Malloc pipelines are intended for situations where 53a minimum number of buffers are required to make progress. 54.Pp 55The 56.Fn mpipe_init 57function initializes a malloc pipeline 58.Fa mpipe . 59The pipeline allocates buffers of size 60.Fa bytes 61from the malloc zone 62.Fa type . 63The pipeline is prefilled with 64.Fa nnom 65buffers and has a limit of 66.Fa nmax 67buffers. 68The 69.Fa construct 70argument is a callback, invoked when a buffer is allocated from the system. 71The 72.Fa deconstruct 73argument is a callback, invoked when the malloc pipeline is destroyed or a 74buffer is freed to the system. 75Both 76.Fa construct 77and 78.Fa deconstruct 79are invoked with the buffer address as their first parameter and with 80.Fa priv 81as their second parameter. 82The 83.Fa flags 84argument controls allocation parameters: 85.Bl -tag -width ".Dv MPF_NOZERO" -offset indent 86.It Dv MPF_NOZERO 87Do not zero allocated buffers. 88.It Dv MPF_CACHEDATA 89By default, MPIPE buffers are zeroed on free; this flag disables that behavior. 90.It Dv MPF_INT 91Allocations may use the interrupt memory reserve. 92.El 93.Pp 94This function may block. 95.Pp 96The 97.Fn mpipe_done 98function destroys a malloc pipeline. 99The pipeline's destructor is invoked on 100each buffer and then they are returned to the system. 101It is an error to invoke 102this function on a pipeline with outstanding allocations. 103This function may block. 104.Pp 105The 106.Fn mpipe_alloc_nowait 107function allocates a buffer from the malloc pipeline. 108It will first allocate from the pipeline itself; if that is exhausted, 109it will fall back on 110.Xr kmalloc 9 , 111up to the pipeline maximum. 112This function may not block. 113.Pp 114The 115.Fn mpipe_alloc_waitok 116function allocates a buffer from the malloc pipeline. 117It will first allocate from the pipeline; if that is exhausted, 118it will fall back on 119.Xr kmalloc 9 , 120up to the pipeline maximum. 121It will sleep if it reaches the maximum, potentially releasing any tokens. 122.Pp 123The 124.Fn mpipe_free 125function frees a buffer to the malloc pipeline. 126If the pipeline is full, it will free directly to the kernel allocator, 127calling the destructor as it does. 128This function may block. 129.Sh FILES 130The MPIPE implementation is in 131.Pa /sys/kern/kern_mpipe.c . 132.Sh SEE ALSO 133.Xr memory 9 134.Sh HISTORY 135MPIPE first appeared in 136.Dx 1.0 . 137