share/man/man9/mpipe.9

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