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 A malloc pipeline is a linear pool of buffers of a single type.
  47 A malloc
  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
  51 or fail respectively.
  52 Malloc pipelines are intended for situations where
  53 a minimum number of buffers are required to make progress.
  54 .Pp
  55 The
  56 .Fn mpipe_init
  57 function initializes a malloc pipeline
  58 .Fa mpipe .
  59 The pipeline allocates buffers of size
  60 .Fa bytes
  61 from the malloc zone
  62 .Fa type .
  63 The pipeline is prefilled with
  64 .Fa nnom
  65 buffers and has a limit of
  66 .Fa nmax
  67 buffers.
  68 The
  69 .Fa construct
  70 argument is a callback, invoked when a buffer is allocated from the system.
  71 The
  72 .Fa deconstruct
  73 argument is a callback, invoked when the malloc pipeline is destroyed or a
  74 buffer is freed to the system.
  75 Both
  76 .Fa construct
  77 and
  78 .Fa deconstruct
  79 are invoked with the buffer address as their first parameter and with
  80 .Fa priv
  81 as their second parameter.
  82 The
  83 .Fa flags
  84 argument controls allocation parameters:
  85 .Bl -tag -width ".Dv MPF_NOZERO" -offset indent
  86 .It Dv MPF_NOZERO
  87 Do not zero allocated buffers.
  88 .It Dv MPF_CACHEDATA
  89 By default, MPIPE buffers are zeroed on free; this flag disables that behavior.
  90 .It Dv MPF_INT
  91 Allocations may use the interrupt memory reserve.
  92 .El
  93 .Pp
  94 This function may block.
  95 .Pp
  96 The
  97 .Fn mpipe_done
  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.
 104 .Pp
 105 The
 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,
 109 it will fall back on
 110 .Xr kmalloc 9 ,
 111 up to the pipeline maximum.
 112 This function may not block.
 113 .Pp
 114 The
 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,
 118 it will fall back on
 119 .Xr kmalloc 9 ,
 120 up to the pipeline maximum.
 121 It will sleep if it reaches the maximum, potentially releasing any tokens.
 122 .Pp
 123 The
 124 .Fn mpipe_free
 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.
 129 .Sh FILES
 130 The MPIPE implementation is in
 131 .Pa /sys/kern/kern_mpipe.c .
 132 .Sh SEE ALSO
 133 .Xr memory 9
 134 .Sh HISTORY
 135 MPIPE first appeared in
 136 .Dx 1.0 .