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