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 August 16, 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 (*destructor)(struct malloc_pipe *, void *)" 35.Ft void 36.Fn mpipe_done "malloc_pipe_t mpipe" 37.Ft void * 38.Fn mpipe_alloc_nowait "malloc_pipe_t mpipe" 39.Ft void * 40.Fn mpipe_alloc_waitok "malloc_pipe_t mpipe" 41.Ft void 42.Fn mpipe_free "malloc_pipe_t mpipe" "void *buf" 43.Sh DESCRIPTION 44.Pp 45A malloc pipeline is a linear pool of buffers of a single type. 46A malloc 47pipeline guarantees a number of outstanding allocations and provides both 48blocking and non-blocking behavior above the guaranteed allocation amounts. 49A malloc pipeline can have an upper limit, beyond which allocations sleep 50or fail respectively. 51Malloc pipelines are intended for situations where 52a minimum number of buffers are required to make progress. 53.Pp 54The 55.Fn mpipe_init 56function initializes a malloc pipeline 57.Fa mpipe . 58The pipeline allocates buffers of size 59.Fa bytes 60from the malloc zone 61.Fa type . 62The pipeline is prefilled with 63.Fa nnom 64buffers and has a limit of 65.Fa nmax 66buffers. 67The 68.Fa destructor 69argument is a callback, invoked when the malloc pipeline is destroyed. 70The 71.Fa flags 72argument controls allocation parameters: 73.Bl -tag -width ".Dv MPF_NOZERO" -offset indent 74.It Dv MPF_NOZERO 75Do not zero allocated buffers. 76.It Dv MPF_INT 77Allocations may use the interrupt memory reserve. 78.El 79.Pp 80This function may block. 81.Pp 82The 83.Fn mpipe_done 84function destroys a malloc pipeline. 85The pipeline's destructor is invoked on 86each buffer and then they are returned to the system. 87It is an error to invoke 88this function on a pipeline with outstanding allocations. 89This function may block. 90.Pp 91The 92.Fn mpipe_alloc_nowait 93function allocates a buffer from the malloc pipeline. 94It will first allocate from the pipeline itself; if that is exhausted, 95it will fall back on 96.Xr kmalloc 9 , 97up to the pipeline maximum. 98This function may not block. 99.Pp 100The 101.Fn mpipe_alloc_waitok 102function allocates a buffer from the malloc pipeline. 103It will first allocate from the pipeline; if that is exhausted, 104it will fall back on 105.Xr kmalloc 9 , 106up to the pipeline maximum. 107It will sleep if it reaches the maximum, potentially releasing any tokens. 108.Pp 109The 110.Fn mpipe_free 111function frees a buffer to the malloc pipeline. 112If the pipeline is full, it will free directly to the kernel allocator, 113calling the destructor as it does. 114This function may block. 115.Pp 116The mpipe functions do not synchronize access to a pipeline. 117It is up to higher-level code to use appropriate locks to ensure that 118multiple CPUs are not simultaneously accessing a pipeline. 119The pipeline functions do 120guard against preemption by entering critical sections. 121.Sh FILES 122The MPIPE implementation is in 123.Pa /sys/kern/kern_mpipe.c . 124.Sh SEE ALSO 125.Xr kmalloc 9 126.Sh HISTORY 127MPIPE first appeared in 128.Dx 1.0 . 129