Commit c053672c authored by Ralf S. Engelschall's avatar Ralf S. Engelschall
Browse files

Although mod_mmap_static is an experimental module it works fine and already 

is distributed with Apache it was not prepared the same way as the other
modules. Hence let us give it a first cut for a documentation and an
(disabled, of course) entry in the Configuration.tmpl file.

Dean: Feel free to fix both my english and my initial content in the
      mod_mmap_static.html document. It's your baby, so you know
      best what is missing.


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@80796 13f79535-47bb-0310-9956-ffa450edef68
parent d17eff8c

docs/manual/mod/directives.html

+1 −0
Changes for docs/manual/mod/directives.html: 1 added line, 0 removed lines.
Original line number Diff line number Diff line
@@ -136,6 +136,7 @@ of the terms used in their descriptions available. 
<LI><A HREF="mod_cern_meta.html#metasuffix">MetaSuffix</A>

<LI><A HREF="mod_mime_magic.html#mimemagicfile">MimeMagicFile</A>

<LI><A HREF="core.html#minspareservers">MinSpareServers</A>

<LI><A HREF="mod_mmap_static.html#mmapfile">MMapFile</A>

<LI><A HREF="core.html#namevirtualhost">NameVirtualHost</A>

<LI><A HREF="mod_proxy.html#nocache">NoCache</A>

<LI><A HREF="core.html#options">Options</A>

docs/manual/mod/index.html

+2 −0
Changes for docs/manual/mod/index.html: 2 added lines, 0 removed lines.
Original line number Diff line number Diff line
@@ -91,6 +91,8 @@ mod_log_config module in Apache 1.2 and up 
<DD>Determining document types using file extensions.

<DT><A HREF="mod_mime_magic.html">mod_mime_magic</A>

<DD>Determining document types using "magic numbers".

<DT><A HREF="mod_mmap_static.html">mod_mmap_static</A>

<DD>Mapping files into memory for faster serving.

<DT><A HREF="mod_negotiation.html">mod_negotiation</A>

<DD>Content negotiation.

<DT><A HREF="mod_proxy.html">mod_proxy</A>

docs/manual/mod/mod_mmap_static.html

0 → 100644
+127 −0
Changes for docs/manual/mod/mod_mmap_static.html: 127 added lines, 0 removed lines.
Original line number Diff line number Diff line 
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<HTML>

 <HEAD>

  <TITLE>Apache module mod_mmap_static</TITLE>

 </HEAD>

<!-- Background white, links blue (unvisited), navy (visited), red (active) -->

 <BODY

  BGCOLOR="#FFFFFF"

  TEXT="#000000"

  LINK="#0000FF"

  VLINK="#000080"

  ALINK="#FF0000"

 >

<!--#include virtual="header.html" -->

  <H1 ALIGN="CENTER">Module mod_mmap_static</H1>



  <P>

  This module is contained in the <CODE>mod_mmap_static.c</CODE> file, with

  Apache 1.3 and later. It provides mmap()ing of a statically configured list

  of frequently requested but not changed files.  It is not compiled into the

  server by default. To use <CODE>mod_mmap_static</CODE> you have to enable

  the following line in the server build <CODE>Configuration</CODE> file:

  <PRE>

    AddModule  modules/experimental/mod_mmap_static.o

  </PRE>

  </P>



  <H2>Summary</H2>

  <P>

  This is an <STRONG>experimental</STRONG> module and should be used with

  care.  It maps a list of statically configured files (via

  <CODE>MMapFile</CODE> directives in the main server configuration) into

  memory through the system call <CODE>mmap()</CODE>. Although this system

  call is not available on every platform, most of the modern Unix derivates

  provide it. At least those ones conforming to the POSIX.4 definition. The

  size of the mapable files usually has to be less then 2GB.  But this is no

  real restriction for documents on a webserver.

  </P>

  <P>

  This mmap()ing is done once at server start or restart, only. So whenever

  one of the mapped files changes on the filesystem you <EM>have</EM> to

  restart the server by at least sending it a HUP or USR1 signal.  To

  reiterate that point:  if the files are modified <EM>in place</EM> without

  restarting the server you may end up serving requests that are completely

  bogus.  You should update files by unlinking the old copy and putting a new

  copy in place. Most tools such as <CODE>rdist</CODE> and <CODE>mv</CODE> do

  this. The reason why this modules doesn't take care of changes to the files

  is that this check would need an extra <CODE>stat()</CODE> every time which

  is a waste and against the intend of I/O reduction.

  </P>



  <H2>Directives</H2>

  <UL>

   <LI><A HREF="#mmapfile">MMapFile</A>

   </LI>

  </UL>



  <HR>



  <H2><A NAME="mmapfile">MMapFile</A></H2>

  <P>

  <A

   HREF="directive-dict.html#Syntax"

   REL="Help"

  ><STRONG>Syntax:</STRONG></A> MMapFile <EM>filename ...</EM>

  <BR>

  <A

   HREF="directive-dict.html#Default"

   REL="Help"

  ><STRONG>Default:</STRONG></A> <EM>None</EM>

  <BR>

  <A

   HREF="directive-dict.html#Context"

   REL="Help"

  ><STRONG>Context:</STRONG></A> server-config

  <BR>

  <A

   HREF="directive-dict.html#Override"

   REL="Help"

  ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM>

  <BR>

  <A

   HREF="directive-dict.html#Status"

   REL="Help"

  ><STRONG>Status:</STRONG></A> Experimental

  <BR>

  <A

   HREF="directive-dict.html#Module"

   REL="Help"

  ><STRONG>Module:</STRONG></A> mod_mmap_static

  <BR>

  <A

   HREF="directive-dict.html#Compatibility"

   REL="Help"

  ><STRONG>Compatibility:</STRONG></A> Only available in Apache 1.3 or later



  <P>

  The <CODE>MMapFile</CODE> directive maps one or more files (given as

  whitespace separated arguments) into memory at server startup time.  They

  are automatically unmapped on a server shutdown. When the files have changed

  on the filesystem at least a HUP or USR1 signal should be send to the server

  to re-mmap them.

  </P>



  <P>

  Be careful with the <EM>filename</EM> arguments: They have to literally

  match the filesystem path Apache's URL-to-filename translation handlers

  create. We cannot compare inodes or other stuff to match paths through

  symbolic links etc. because that again would cost extra <CODE>stat()</CODE>

  system calls which is not acceptable.

  </P>

  

  <P>

  Notice: You cannot use this for speeding up CGI programs or other files

  which are served by special content handlers. It can only be used for

  regular files which are usually served by the Apache core content handler.

  </P>



  Example:



  <PRE>

  MMapFile /usr/local/apache/htdocs/index.html

  </PRE>



<!--#include virtual="footer.html" -->

 </BODY>

</HTML>