2 .\" Copyright (c) 2010, The DragonFly Project.
4 .\" This software is derived from software contributed to the DragonFly Project
5 .\" by Venkatesh Srinivas <me@endeavour.zapto.org>.
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.
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.
25 .Nm mpipe_alloc_nowait ,
26 .Nm mpipe_alloc_waitok ,
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 *)" \
38 .Fn mpipe_done "malloc_pipe_t mpipe"
40 .Fn mpipe_alloc_nowait "malloc_pipe_t mpipe"
42 .Fn mpipe_alloc_waitok "malloc_pipe_t mpipe"
44 .Fn mpipe_free "malloc_pipe_t mpipe" "void *buf"
46 A malloc pipeline is a linear pool of buffers of a single type.
48 pipeline guarantees a number of outstanding allocations and provides both
49 blocking and non-blocking behavior above the guaranteed allocation amounts.
50 A malloc pipeline can have an upper limit, beyond which allocations sleep
52 Malloc pipelines are intended for situations where
53 a minimum number of buffers are required to make progress.
57 function initializes a malloc pipeline
59 The pipeline allocates buffers of size
63 The pipeline is prefilled with
65 buffers and has a limit of
70 argument is a callback, invoked when a buffer is allocated from the system.
73 argument is a callback, invoked when the malloc pipeline is destroyed or a
74 buffer is freed to the system.
79 are invoked with the buffer address as their first parameter and with
81 as their second parameter.
84 argument controls allocation parameters:
85 .Bl -tag -width ".Dv MPF_NOZERO" -offset indent
87 Do not zero allocated buffers.
89 By default, MPIPE buffers are zeroed on free; this flag disables that behavior.
91 Allocations may use the interrupt memory reserve.
94 This function may block.
98 function destroys a malloc pipeline.
99 The pipeline's destructor is invoked on
100 each buffer and then they are returned to the system.
101 It is an error to invoke
102 this function on a pipeline with outstanding allocations.
103 This function may block.
106 .Fn mpipe_alloc_nowait
107 function allocates a buffer from the malloc pipeline.
108 It will first allocate from the pipeline itself; if that is exhausted,
111 up to the pipeline maximum.
112 This function may not block.
115 .Fn mpipe_alloc_waitok
116 function allocates a buffer from the malloc pipeline.
117 It will first allocate from the pipeline; if that is exhausted,
120 up to the pipeline maximum.
121 It will sleep if it reaches the maximum, potentially releasing any tokens.
125 function frees a buffer to the malloc pipeline.
126 If the pipeline is full, it will free directly to the kernel allocator,
127 calling the destructor as it does.
128 This function may block.
130 The MPIPE implementation is in
131 .Pa /sys/kern/kern_mpipe.c .
135 MPIPE first appeared in