mm.pod

Apache V2.0.15 Alpha For Linuxhttpd-2_0_15-alpha.tar.Z

## ====================================================================
## Copyright (c) 1999-2000 Ralf S. Engelschall. All rights reserved.
##
## Redistribution and use in source and binary forms, with or without
## modification, are permitted provided that the following conditions
## are met:
##
## 1. Redistributions of source code must retain the above copyright
##    notice, this list of conditions and the following disclaimer. 
##
## 2. Redistributions in binary form must reproduce the above copyright
##    notice, this list of conditions and the following disclaimer in
##    the documentation and/or other materials provided with the
##    distribution.
##
## 3. All advertising materials mentioning features or use of this
##    software must display the following acknowledgment:
##    "This product includes software developed by
##     Ralf S. Engelschall <[e-mail]>."
##
## 4. Redistributions of any form whatsoever must retain the following
##    acknowledgment:
##    "This product includes software developed by
##     Ralf S. Engelschall <[e-mail]>."
##
## THIS SOFTWARE IS PROVIDED BY RALF S. ENGELSCHALL ``AS IS'' AND ANY
## EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
## IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
## PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL RALF S. ENGELSCHALL OR
## ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
## NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
## LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
## HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
## STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
## ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
## OF THE POSSIBILITY OF SUCH DAMAGE.
## ====================================================================

##
## mm.pod -- Manpage
##

=pod

=head1 NAME

B<MM - Shared Memory Library>

=head1 VERSION

MM MM_VERSION_STR

=head1 SYNOPSIS

 #include "mm.h"

B< Global Malloc-Replacement API>

 int     MM_create(size_t size, const char *file);
 int     MM_permission(mode_t mode, uid_t owner, gid_t group);
 void    MM_destroy(void);
 int     MM_lock(mm_lock_mode mode);
 int     MM_unlock(void);
 void   *MM_malloc(size_t size);
 void   *MM_realloc(void *ptr, size_t size);
 void    MM_free(void *ptr);
 void   *MM_calloc(size_t number, size_t size);
 char   *MM_strdup(const char *str);
 size_t  MM_sizeof(void *ptr);
 size_t  MM_maxsize(void);
 size_t  MM_available(void);
 char   *MM_error(void);

B< Standard Malloc-Style API>

 MM     *mm_create(size_t size, char *file);
 int     mm_permission(MM *mm, mode_t mode, uid_t owner, gid_t group);
 void    mm_destroy(MM *mm);
 int     mm_lock(MM *mm, mm_lock_mode mode);
 int     mm_unlock(MM *mm);
 void   *mm_malloc(MM *mm, size_t size);
 void   *mm_realloc(MM *mm, void *ptr, size_t size);
 void    mm_free(MM *mm, void *ptr);
 void   *mm_calloc(MM *mm, size_t number, size_t size);
 char   *mm_strdup(MM *mm, const char *str);
 size_t  mm_sizeof(void *ptr);
 size_t  mm_maxsize(void);
 size_t  mm_available(MM *mm);
 char   *mm_error(void);
 void    mm_display_info(MM *mm);

B< Low-level Shared Memory API>

 void   *mm_core_create(size_t size, char *file);
 int     mm_core_permission(void *core, mode_t mode, uid_t owner, gid_t group);
 void    mm_core_delete(void *core);
 int     mm_core_lock(void *core, mm_lock_mode mode);
 int     mm_core_unlock(void *core);
 size_t  mm_core_size(void *core);
 size_t  mm_core_maxsegsize(void);
 size_t  mm_core_align2page(size_t size);
 size_t  mm_core_align2click(size_t size);

B< Internal Library API>

 void    mm_lib_error_set(unsigned int, const char *str);
 char   *mm_lib_error_get(void);
 int     mm_lib_version(void);

=head1 DESCRIPTION

The B<MM> library is a 2-layer abstraction library which simplifies the usage
of shared memory between forked (and this way strongly related) processes
under Unix platforms. On the first (lower) layer it hides all platform
dependent implementation details (allocation and locking) when dealing with
shared memory segments and on the second (higher) layer it provides a
high-level malloc(3)-style API for a convenient and well known way to work
with data-structures inside those shared memory segments. 

The abbreviation B<MM> is historically and originally comes from the phrase
``I<memory mapped>'' as used by the POSIX.1 mmap(2) function. Because this
facility is internally used by this library on most platforms to establish the
shared memory segments. 

=head2 LIBRARY STRUCTURE

This library is structured into three main APIs which are internally based on
each other:

=over 4

=item B<Global Malloc-Replacement API>

This is the most high-level API which directly can be used as replacement API
for the POSIX.1 memory allocation API (malloc(2) and friends). This is
useful when converting I<heap> based data structures to I<shared memory>
based data structures without the need to change the code dramatically.  All
which is needed is to prefix the POSIX.1 memory allocation functions with
`C<MM_>', i.e. `C<malloc>' becomes `C<MM_malloc>', `C<strdup>' becomes
`C<MM_strdup>', etc. This API internally uses just a global `C<MM *>' pool for
calling the corresponding functions (those with prefix `C<mm_>') of the
I<Standard Malloc-Style API>.

=item B<Standard Malloc-Style API>

This is the standard high-level memory allocation API. Its interface is
similar to the I<Global Malloc-Replacement API> but it uses an explicit `C<MM *>'
pool to operate on. That is why every function of this API has an argument of
type `C<MM *>' as its first argument. This API provides a comfortable way to
work with small dynamically allocated shared memory chunks inside large
statically allocated shared memory segments. It is internally based on the
I<Low-Level Shared Memory API> for creating the underlaying shared memory
segment.

=item B<Low-Level Shared Memory API>

This is the basis of the whole B<MM> library. It provides low-level functions
for creating shared memory segments with mutual exclusion (in short I<mutex>)
capabilities in a portable way. Internally the shared memory and mutex
facility is implemented in various platform-dependent ways. A list of
implementation variants follows under the next topic.

=back

=head2 SHARED MEMORY IMPLEMENTATION

Internally the shared memory facility is implemented in various
platform-dependent ways. Each way has its own advantages and disadvantages
(in addition to the fact that some variants aren't available at all on some
platforms). The B<MM> library's configuration procedure tries hard to make a
good decision. The implemented variants are now given for overview and
background reasons with their advantages and disadvantages and in an ascending
order, i.e. the B<MM> configuration mechanism chooses the last available one
in the list as the preferred variant.

=over 4

=item Classical mmap(2) on temporary file (MMFILE)

I<Advantage:> maximum portable.
I<Disadvantage:> needs a temporary file on the filesystem.

=item mmap(2) via POSIX.1 shm_open(3) on temporary file (MMPOSX)

I<Advantage:> standardized by POSIX.1 and theoretically portable.
I<Disadvantage:> needs a temporary file on the filesystem and is
is usually not available on existing Unix platform.

=item SVR4-style mmap(2) on C</dev/zero> device (MMZERO)

I<Advantage:> widely available and mostly portable on SVR4 platforms.
I<Disadvantage:> needs the C</dev/zero/> device and a mmap(2)
which supports memory mapping through this device.

=item 4.4BSD-style mmap(2) via C<MAP_ANON> facility (MMANON)

I<Advantage:> does not need a temporary file or external device.
I<Disadvantage:> usually only available on BSD platforms and derivatives.

=item SysV IPC shmget(2) (IPCSHM)

I<Advantage:> does not need a temporary file or external device.
I<Disadvantage:> although available on mostly all modern Unix platforms, it has
strong restrictions like the maximum size of a single shared memory segment (can
be as small as 100KB, but depends on the platform).

=back

=head2 LOCKING IMPLEMENTATION

As for the shared memory facility, internally the locking facility is
implemented in various platform-dependent ways. A short overview of
implemented variants is given:

=over 4

=item 4.2BSD-style flock(2) on temporary file (FLOCK)

I<Advantage:> exists on a lot of platforms, especially on older Unix
derivates.  I<Disadvantage:> needs a temporary file on the filesystem and has
to re-open file-descriptors to it in each(!) fork(2)'ed child process.

=item SysV IPC semget(2) (IPCSEM)

I<Advantage:> exists on a lot of platforms and does not need a temporary file.
I<Disadvantage:> an unmeant termination of the application leads to a
semaphore leak because the facility does not allow a ``remove in advance''
trick (as the IPC shared memory facility does) for safe cleanups.

=item SVR4-style fcntl(2) on temporary file (FCNTL)

I<Advantage:> exists on a lot of platforms and is also the most powerful
variant (although not always the fastest one). I<Disadvantage:> needs a
temporary file.

=back

=head2 MEMORY ALLOCATION STRATEGY

The memory allocation strategy the I<Standard Malloc-Style API> functions use
internally is the following:

=over 4

=item B<Allocation>

If a chunk of memory has to be allocated, the internal list of free chunks
is searched for a minimal-size chunk which is larger or equal than the size of
the to be allocated chunk (a I<best fit> strategy>). 

If a chunk is found which matches this best-fit criteria, but is still a lot
larger than the requested size, it is split into two chunks: One with exactly
the requested size (which is the resulting chunk given back) and one with the
remaining size (which is immediately re-inserted into the list of free
chunks). 

If no fitting chunk is found at all in the list of free chunks, a new one is
created from the spare area of the shared memory segment until the segment is
full (in which case an I<out of memory> error occurs).

=item B<Deallocation>

If a chunk of memory has to be deallocated, it is inserted in sorted manner
into the internal list of free chunks. The insertion operation automatically
merges the chunk with a previous and/or a next free chunk if possible, i.e.
if the free chunks stay physically seamless (one after another) in memory, to
automatically form larger free chunks out of smaller ones. 

This way the shared memory segment is automatically defragmented when memory
is deallocated.

=back

This strategy reduces memory waste and fragmentation caused by small and
frequent allocations and deallocations to a minimum. 

The internal implementation of the list of free chunks is not specially
optimized (for instance by using binary search trees or even I<splay> trees,
etc), because it is assumed that the total amount of entries in the list of
free chunks is always small (caused both by the fact that shared memory
segments are usually a lot smaller than heaps and the fact that we always
defragment by merging the free chunks if possible).

=head1 API FUNCTIONS

In the following all API functions are described in detail.
The order directly follows the one in the B<SYNOPSIS>.

=head2 Global Malloc-Replacement API

=over 4

=item int B<MM_create>(size_t I<size>, const char *I<file>);

This initializes the global shared memory pool with I<size> and I<file> and
has to be called I<before> any fork(2) operations are performed by the
application.

=item int B<MM_permission>(mode_t I<mode>, uid_t I<owner>, gid_t I<group>);

This sets the filesystem I<mode>, I<owner> and I<group> for the global shared
memory pool (has effects only if the underlaying shared memory segment
implementation is actually based on external auxiliary files).  The arguments
are directly passed through to chmod(2) and chown(2).

=item void B<MM_destroy>(void);

This destroys the global shared memory pool and should be called I<after> all
child processes were killed.

=item int B<MM_lock>(mm_lock_mode I<mode>);

This locks the global shared memory pool for the current process in order to
perform either shared/read-only (I<mode> is C<MM_LOCK_RD>) or
exclusive/read-write (I<mode> is C<MM_LOCK_RW>) critical operations inside the
global shared memory pool.