From 91782eb56b587056fdf1746f23401c152ea9861c Mon Sep 17 00:00:00 2001 From: Venkatesh Srinivas Date: Sun, 15 Aug 2010 23:29:10 -0700 Subject: [PATCH] Add a draft mpipe(9) manpage explaining malloc pipelines. --- share/man/man9/Makefile | 6 +++ share/man/man9/mpipe.9 | 112 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 118 insertions(+) create mode 100644 share/man/man9/mpipe.9 diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 26ee0468df..71b65167fd 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -116,6 +116,7 @@ MAN= accept_filter.9 \ module.9 \ MODULE_DEPEND.9 \ MODULE_VERSION.9 \ + mpipe.9 \ mutex.9 \ nlookup.9 \ objcache.9 \ @@ -582,6 +583,11 @@ MLINKS+=microtime.9 getmicrotime.9 \ MLINKS+=microuptime.9 getmicrouptime.9 \ microuptime.9 getnanouptime.9 \ microuptime.9 nanouptime.9 +MLINKS+=mpipe.9 mpipe_init.9 \ + mpipe.9 mpipe_done.9 \ + mpipe.9 mpipe_alloc_nowait.9 \ + mpipe.9 mpipe_alloc_waitok.9 \ + mpipe.9 mpipe_free.9 MLINKS+=mutex.9 mtx_downgrade.9 \ mutex.9 mtx_drop.9 \ mutex.9 mtx_hold.9 \ diff --git a/share/man/man9/mpipe.9 b/share/man/man9/mpipe.9 new file mode 100644 index 0000000000..08b037a429 --- /dev/null +++ b/share/man/man9/mpipe.9 @@ -0,0 +1,112 @@ +.\" +.\" Copyright (c) 2010, The DragonFly Project. +.\" +.\" This software is derived from software contributed to the DragonFly Project +.\" by Venkatesh Srinivas . +.\" +.\" Permission to use, copy, modify, or distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR OTHER DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA, OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE, OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd August 16, 2010 +.Os +.Dt MPIPE 9 +.Sh NAME +.Nm mpipe_init , +.Nm mpipe_done , +.Nm mpipe_alloc_nowait , +.Nm mpipe_alloc_waitok , +.Nm mpipe_free +.Nd malloc pipelines +.Sh SYNOPSIS +.In sys/mpipe.h +.Ft void +.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*)" +.Ft void +.Fn mpipe_done "malloc_pipe_t mpipe" +.Ft void * +.Fn mpipe_alloc_nowait "malloc_pipe_t mpipe" +.Ft void * +.Fn mpipe_alloc_waitok "malloc_pipe_t mpipe" +.Ft void +.Fn mpipe_free "malloc_pipe_t mpipe" "void *buf" +.Sh DESCRIPTION +.Pp +A malloc pipeline is a linear pool of buffers of a single type. A malloc +pipeline guarantees a number of outstanding allocations and provides both +blocking and non-blocking behavior above the guaranteed allocation amounts. +A malloc pipeline can have an upper limit, beyond which allocations sleep +or fail respectively. Malloc pipelines are intended for situations where +a minimum number of buffers are required to make progress. +.Pp +The +.Fn mpipe_init +function initializes a malloc pipeline +.Fa mpipe . +The pipeline allocates buffers of size +.Fa bytes +from the +malloc zone +.Fa type . +The pipeline is prefilled with +.Fa nnom +buffers and has a limit of +.Fa nmax +buffers. The +.Fa destructor +argument is a callback, invoked when the malloc pipeline is destroyed. The +.Fa flags +argument controls allocation parameters: +.Ss MPF_NOZERO +Do not zero allocated buffers. +.Ss MPF_INT +Allocations may use the interrupt memory reserve. +.Pp +This function may block. +.Pp +The +.Fn mpipe_done +function destroys a malloc pipeline. The pipeline's destructor is invoked on +each buffer and then they are returned to the system. It is an error to invoke +this function on a pipeline with outstanding allocations. This function may +block. +.Pp +The +.Fn mpipe_alloc_nowait +function allocates a buffer from the malloc pipeline. It will first allocate +from the pipeline itself; if that is exhausted, it will fall back on kmalloc, +up to the pipeline maximum. This function may not block. +.Pp +The +.Fn mpipe_alloc_waitok +function allocates a buffer from the malloc pipeline. It will first allocate +from the pipeline; if that is exhausted, it will fall back on kmalloc, up to +the pipeline maximum. It will sleep if it reaches the maximum, potentially +releasing any tokens. +.Pp +The +.Fn mpipe_free +function frees a buffer to the malloc pipeline. If the pipeline is full, it +will free directly to the kernel allocator, calling the destructor as it does. +This function may block. +.Pp +The mpipe functions do not synchronize access to a pipeline. It is +up to higher-level code to use appropriate locks to ensure that multiple +CPUs are not simultaneously accessing a pipeline. The pipeline functions do +guard against preemption by entering critical sections. +.Sh FILES +The MPIPE implementation is in +.Pa /sys/kern/kern_mpipe.c . +.Sh SEE ALSO +.Xr malloc 9 +.Sh HISTORY +MPIPE first appeared in +.Dx 1.0 . -- 2.41.0