mm.pod

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

=item int B<MM_unlock>(void);

This unlocks the global shared memory pool for the current process after the
critical operations were performed inside the global shared memory pool.

=item void *B<MM_malloc>(size_t I<size>);

Identical to the POSIX.1 malloc(3) function but instead of allocating
memory from the I<heap> it allocates it from the global shared memory pool.

=item void B<MM_free>(void *I<ptr>);

Identical to the POSIX.1 free(3) function but instead of deallocating
memory in the I<heap> it deallocates it in the global shared memory pool.

=item void *B<MM_realloc>(void *I<ptr>, size_t I<size>);

Identical to the POSIX.1 realloc(3) function but instead of reallocating
memory in the I<heap> it reallocates it inside the global shared memory pool.

=item void *B<MM_calloc>(size_t I<number>, size_t I<size>);

Identical to the POSIX.1 calloc(3) function but instead of allocating and
initializing memory from the I<heap> it allocates and initializes it from the
global shared memory pool.

=item char *B<MM_strdup>(const char *I<str>);

Identical to the POSIX.1 strdup(3) function but instead of creating the
string copy in the I<heap> it creates it in the global shared memory pool.

=item size_t B<MM_sizeof>(const void *I<ptr>);

This function returns the size in bytes of the chunk starting at I<ptr> when
I<ptr> was previously allocated with MM_malloc(3). The result is undefined
if I<ptr> was not previously allocated with MM_malloc(3).

=item size_t B<MM_maxsize>(void);

This function returns the maximum size which is allowed
as the first argument to the MM_create(3) function.

=item size_t B<MM_available>(void);

Returns the amount in bytes of still available (free) memory in the global
shared memory pool.

=item char *B<MM_error>(void);

Returns the last error message which occurred inside the B<MM> library.

=back

=head2 Standard Malloc-Style API

=over 4

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

This creates a shared memory pool which has space for approximately a total of
I<size> bytes with the help of I<file>. Here I<file> is a filesystem path to a
file which need not to exist (and perhaps is never created because this
depends on the platform and chosen shared memory and mutex implementation).
The return value is a pointer to a C<MM> structure which should be treated as
opaque by the application. It describes the internals of the created shared
memory pool. In case of an error C<NULL> is returned.  A I<size> of 0 means to
allocate the maximum allowed size which is platform dependent and is between a
few KB and the soft limit of 64MB.

=item int B<mm_permission>(MM *I<mm>, 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 shared memory
pool I<mm> (has effects only when 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>(MM *I<mm>);

This destroys the complete shared memory pool I<mm> and with it all chunks
which were allocated in this pool. Additionally any created files on the
filesystem corresponding the to shared memory pool are unlinked.

=item int B<mm_lock>(MM *I<mm>, mm_lock_mode I<mode>);

This locks the shared memory pool I<mm> 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.

=item int B<mm_unlock>(MM *I<mm>);

This unlocks the shared memory pool I<mm> for the current process after
critical operations were performed inside the global shared memory pool.

=item void *B<mm_malloc>(MM *I<mm>, size_t I<size>);

This function allocates I<size> bytes from the shared memory pool I<mm> and
returns either a (virtual memory word aligned) pointer to it or C<NULL> in
case of an error (out of memory). It behaves like the POSIX.1 malloc(3)
function but instead of allocating memory from the I<heap> it allocates it
from the shared memory segment underlaying I<mm>.

=item void B<mm_free>(MM *I<mm>, void *I<ptr>);

This deallocates the chunk starting at I<ptr> in the shared memory pool I<mm>.
It behaves like the POSIX.1 free(3) function but instead of deallocating
memory from the I<heap> it deallocates it from the shared memory segment
underlaying I<mm>.

=item void *B<mm_realloc>(MM *I<mm>, void *I<ptr>, size_t I<size>);

This function reallocates the chunk starting at I<ptr> inside the shared
memory pool I<mm> with the new size of I<size> bytes.  It behaves like the
POSIX.1 realloc(3) function but instead of reallocating memory in the
I<heap> it reallocates it in the shared memory segment underlaying I<mm>.

=item void *B<mm_calloc>(MM *I<mm>, size_t I<number>, size_t I<size>);

This is similar to mm_malloc(3), but additionally clears the chunk. It behaves
like the POSIX.1 calloc(3) function.  It allocates space for I<number>
objects, each I<size> bytes in length from the shared memory pool I<mm>.  The
result is identical to calling mm_malloc(3) with an argument of ``I<number> *
I<size>'', with the exception that the allocated memory is initialized to nul
bytes.

=item char *B<mm_strdup>(MM *I<mm>, const char *I<str>);

This function behaves like the POSIX.1 strdup(3) function.  It allocates
sufficient memory inside the shared memory pool I<mm> for a copy of the string
I<str>, does the copy, and returns a pointer to it.  The pointer may
subsequently be used as an argument to the function mm_free(3). If
insufficient shared memory is available, C<NULL> is returned.

=item size_t B<mm_sizeof>(const void *I<ptr>);

This function returns the size in bytes of the chunk starting at I<ptr> when
I<ptr> was previously allocated with mm_malloc(3). The result is undefined
when I<ptr> was not previously allocated with mm_malloc(3).

=item size_t B<mm_maxsize>(void);

This function returns the maximum size which is allowed as the first argument
to the mm_create(3) function.

=item size_t B<mm_available>(MM *I<mm>);

Returns the amount in bytes of still available (free) memory in the 
shared memory pool I<mm>.

=item char *B<mm_error>(void);

Returns the last error message which occurred inside the B<MM> library.

=item void B<mm_display_info>(MM *I<mm>);

This is debugging function which displays a summary page for the shared memory
pool I<mm> describing various internal sizes and counters.

=back

=head2 Low-Level Shared Memory API

=over 4

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

This creates a shared memory area which is at least I<size> bytes in size with
the help of I<file>. The value I<size> has to be greater than 0 and less or
equal the value returned by mm_core_maxsegsize(3). Here I<file> is a
filesystem path to a file which need not to exist (and perhaps is never
created because this depends on the platform and chosen shared memory and
mutex implementation).  The return value is either a (virtual memory word
aligned) pointer to the shared memory segment or C<NULL> in case of an error.
The application is guaranteed to be able to access the shared memory segment
from byte 0 to byte I<size>-1 starting at the returned address.

=item int B<mm_core_permission>(void *I<core>, 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 shared memory
segment I<code> (has effects only when 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_core_delete>(void *I<core>);

This deletes a shared memory segment I<core> (as previously returned by a
mm_core_create(3) call). After this operation, accessing the segment starting
at I<core> is no longer allowed and will usually lead to a segmentation fault.

=item int B<mm_core_lock>(const void *I<core>, mm_lock_mode I<mode>);

This function acquires an advisory lock for the current process on the shared
memory segment I<core> for either shared/read-only (I<mode> is C<MM_LOCK_RD>)
or exclusive/read-write (I<mode> is C<MM_LOCK_RW>) critical operations between
fork(2)'ed child processes.

=item int B<mm_core_unlock>(const void *I<core>);

This function releases a previously acquired advisory lock for the current
process on the shared memory segment I<core>.

=item size_t B<mm_core_size>(const void *I<core>);

This returns the size in bytes of I<core>. This size is exactly the size which
was used for creating the shared memory area via mm_core_create(3). The
function is provided just for convenience reasons to not require the
application to remember the memory size behind I<core> itself. 

=item size_t B<mm_core_maxsegsize>(void);

This returns the number of bytes of a maximum-size shared memory segment which
is allowed to allocate via the MM library. It is between a few KB and the soft
limit of 64MB.

=item size_t B<mm_core_align2page>(size_t I<size>);

This is just a utility function which can be used to align the number I<size>
to the next virtual memory I<page> boundary used by the underlaying platform.
The memory page boundary under Unix platforms is usually somewhere between
2048 and 16384 bytes. You do not have to align the I<size> arguments of other
B<MM> library functions yourself, because this is already done internally.
This function is exported by the B<MM> library just for convenience reasons in
case an application wants to perform similar calculations for other purposes.

=item size_t B<mm_core_align2word>(size_t I<size>);

This is another utility function which can be used to align the number I<size>
to the next virtual memory I<word> boundary used by the underlaying platform.
The memory word boundary under Unix platforms is usually somewhere between 4
and 16 bytes.  You do not have to align the I<size> arguments of other B<MM>
library functions yourself, because this is already done internally.  This
function is exported by the B<MM> library just for convenience reasons in case
an application wants to perform simular calculations for other purposes.

=back

=head2 Low-Level Shared Memory API

=over 4

=item void B<mm_lib_error_set>(unsigned int, const char *str);

This is a function which is used internally by the various MM function to set
an error string. It's usually not called directly from applications.

=item char *B<mm_lib_error_get>(void);

This is a function which is used internally by MM_error(3) and mm_error(3)
functions to get the current error string. It is usually not called directly
from applications.

=item int B<mm_lib_version>(void);

This function returns a hex-value ``0xI<V>I<RR>I<T>I<LL>'' which describes the
current B<MM> library version. I<V> is the version, I<RR> the revisions, I<LL>
the level and I<T> the type of the level (alphalevel=0, betalevel=1,
patchlevel=2, etc). For instance B<MM> version 1.0.4 is encoded as 0x100204.
The reason for this unusual mapping is that this way the version number is
steadily I<increasing>.

=back

=head1 RESTRICTIONS

The maximum size of a continuous shared memory segment one can allocate
depends on the underlaying platform. This cannot be changed, of course.  But
currently the high-level malloc(3)-style API just uses a single shared memory
segment as the underlaying data structure for an C<MM> object which means that
the maximum amount of memory an C<MM> object represents also depends on the
platform. 

This should be changed in later versions by allowing at least the high-level
malloc(3)-style API to internally use multiple shared memory segments to form
the C<MM> object. This way C<MM> objects could have arbitrary sizes, although
the maximum size of an allocatable chunk still is bounded by the maximum size
of a shared memory segment.

=head1 SEE ALSO

mm-config(1).

malloc(3), calloc(3), realloc(3), strdup(3), free(3), mmap(2), shmget(2),
shmctl(2), flock(2), fcntl(2), semget(2), semctl(2), semop(2).

=head1 HOME

=for html 
<a href="http://www.engelschall.com/sw/mm/">http://www.engelschall.com/sw/mm/</a>

=for text 
http://www.engelschall.com/sw/mm/

=for man 
http://www.engelschall.com/sw/mm/

=head1 HISTORY

This library was originally written in January 1999 by I<Ralf S.
Engelschall> <[e-mail]> for use in the B<Extended API> (EAPI)
of the B<Apache> HTTP server project (see www.apache.org), which was
originally invented for B<mod_ssl> (see http://www.modssl.org/).

Its base idea (a malloc-style API for handling shared memory) was originally
derived from the non-publically available I<mm_malloc> library written in
October 1997 by I<Charles Randall> <[e-mail]> for MatchLogic,
Inc.

=head1 AUTHOR

 Ralf S. Engelschall
 [e-mail]
 www.engelschall.com

=cut