DragonFly On-Line Manual Pages

Search: Section:  

MPIPE(9)              DragonFly Kernel Developer's Manual             MPIPE(9)


NAME

     mpipe_init, mpipe_done, mpipe_alloc_nowait, mpipe_alloc_waitok,
     mpipe_free -- malloc pipelines


SYNOPSIS

     #include <sys/mpipe.h>

     void
     mpipe_init(malloc_pipe_t mpipe, malloc_type_t type, int bytes, int nnom,
         int nmax, int mpflags, void (*construct)(void *, void *),
         void (*deconstruct)(void *, void *), void *priv);

     void
     mpipe_done(malloc_pipe_t mpipe);

     void *
     mpipe_alloc_nowait(malloc_pipe_t mpipe);

     void *
     mpipe_alloc_waitok(malloc_pipe_t mpipe);

     void
     mpipe_free(malloc_pipe_t mpipe, void *buf);


DESCRIPTION

     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 alloca-
     tions sleep or fail respectively.  Malloc pipelines are intended for sit-
     uations where a minimum number of buffers are required to make progress.

     The mpipe_init() function initializes a malloc pipeline mpipe.  The pipe-
     line allocates buffers of size bytes from the malloc zone type.  The
     pipeline is prefilled with nnom buffers and has a limit of nmax buffers.
     The construct argument is a callback, invoked when a buffer is allocated
     from the system.  The deconstruct argument is a callback, invoked when
     the malloc pipeline is destroyed or a buffer is freed to the system.
     Both construct and deconstruct are invoked with the buffer address as
     their first parameter and with priv as their second parameter.  The flags
     argument controls allocation parameters:

           MPF_NOZERO  Do not zero allocated buffers.

           MPF_CACHEDATA
                       By default, MPIPE buffers are zeroed on free; this flag
                       disables that behavior.

           MPF_INT     Allocations may use the interrupt memory reserve.

     This function may block.

     The 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 out-
     standing allocations.  This function may block.

     The 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(9), up to the pipeline maximum.
     This function may not block.

     The 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(9), up to the pipeline maximum.
     It will sleep if it reaches the maximum, potentially releasing any
     tokens.

     The 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.


FILES

     The MPIPE implementation is in /sys/kern/kern_mpipe.c.


SEE ALSO

     memory(9)


HISTORY

     MPIPE first appeared in DragonFly 1.0.

DragonFly 3.5                  December 21, 2010                 DragonFly 3.5

Search: Section: