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