<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<section id="apc.configuration">
 &reftitle.runtime;
 &extension.runtime;
 <para>
  Although the default APC settings are fine for many installations, serious
  users should consider tuning the following parameters.
 </para>
 <para>
  There are two main decisions you have to make.  First, how much shared
  memory do you want to set aside for APC, and second, whether you want APC
  to check if a file has been modified on every request.  The two ini
  directives involved here are <literal>apc.shm_size</literal> and 
  <literal>apc.stat</literal>.  Read the sections on these two directives
  carefully below.
 </para>
 <para>
  Once you have a running server, you should copy the
  <literal>apc.php</literal> script that comes with the extension to
  somewhere in your docroot and load it up in your browser.  It provides
  you with a detailed look at what is happening in your cache.  If you
  have GD enabled in PHP, it will even have pretty graphs.  First thing
  to check is of course that it is actually caching files.  Assuming it is
  working you should then pay close attention to the <literal>Cache full
  count</literal> number on the left.  That tells you the number of times
  the cache has filled up and has had to forcefully clean up any entries
  not accessed within the last <literal>apc.ttl</literal> seconds.  You
  should configure your cache to minimize this number.  If you are constantly
  filling your cache, the resulting cache churn is going to hurt performance.
  You should either set more memory aside for APC, or use
  <literal>apc.filters</literal> to cache fewer scripts.
 </para>
 <para>
  <table>
   <title>APC configuration options</title>
   <tgroup cols="4">
    <thead>
     <row>
      <entry>Name</entry>
      <entry>Default</entry>
      <entry>Changeable</entry>
      <entry>Changelog</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>apc.enabled</entry>
      <entry>"1"</entry>
      <entry>PHP_INI_ALL</entry>
      <entry></entry>
     </row>
     <row>
      <entry>apc.shm_segments</entry>
      <entry>"1"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry></entry>
     </row>
     <row>
      <entry>apc.shm_size</entry>
      <entry>"30"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry></entry>
     </row>
     <row>
      <entry>apc.optimization</entry>
      <entry>"0"</entry>
      <entry>PHP_INI_ALL</entry>
      <entry></entry>
     </row>
     <row>
      <entry>apc.num_files_hint</entry>
      <entry>"1000"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry></entry>
     </row>
     <row>
      <entry>apc.ttl</entry>
      <entry>"0"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry></entry>
     </row>
     <row>
      <entry>apc.gc_ttl</entry>
      <entry>"3600"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry></entry>
     </row>
     <row>
      <entry>apc.cache_by_default</entry>
      <entry>"1"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry></entry>
     </row>
     <row>
      <entry>apc.filters</entry>
      <entry>NULL</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry></entry>
     </row>
     <row>
      <entry>apc.mmap_file_mask</entry>
      <entry>NULL</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry></entry>
     </row>
     <row>
      <entry>apc.slam_defense</entry>
      <entry>"0"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry></entry>
     </row>
     <row>
      <entry>apc.file_update_protection</entry>
      <entry>"2"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry></entry>
     </row>
     <row>
      <entry>apc.enable_cli</entry>
      <entry>"0"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry>&gt; APC 3.0.6</entry>
     </row>
     <row>
      <entry>apc.max_file_size</entry>
      <entry>"1M"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry>&gt; APC 3.0.6</entry>
     </row>
     <row>
      <entry>apc.stat</entry>
      <entry>"1"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry>&gt; APC 3.0.9</entry>
     </row>
    </tbody>
   </tgroup>
  </table>
  &ini.php.constants;
 </para>
 
 &ini.descriptions.title;
 
 <para>
  <variablelist>
   <varlistentry id="ini.apc.enabled">
    <term>
     <parameter>apc.enabled</parameter>
     <type>boolean</type>
    </term>
    <listitem>
     <para>
      <literal>apc.enabled</literal> can be set to 0 to disable APC. This is
      primarily useful when APC is statically compiled
      into PHP, since there is no other way to disable
      it (when compiled as a DSO, the <literal>extension</literal>
      line in <literal>php.ini</literal> can just be commented-out).
     </para>
    </listitem>
   </varlistentry>
   <varlistentry id="ini.apc.shm-segments">
    <term>
     <parameter>apc.shm_segments</parameter>
     <type>integer</type>
    </term>
    <listitem>
     <para>
      The number of shared memory segments to allocate
      for the compiler cache. If APC is running out of
      shared memory but you have already set
      <literal>apc.shm_size</literal> as high as your system allows, you
      can try raising this value.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry id="ini.apc.shm-size">
    <term>
     <parameter>apc.shm_size</parameter>
     <type>integer</type>
    </term>
    <listitem>
     <para>
      The size of each shared memory segment in MB.
      By default, some systems (including most BSD
      variants) have very low limits on the size of a
      shared memory segment.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry id="ini.apc.optimization">
    <term>
     <parameter>apc.optimization</parameter>
     <type>integer</type>
    </term>
    <listitem>
     <para>
      The optimization level. Zero disables the
      optimizer, and higher values use more aggressive
      optimizations. Expect very modest speed
      improvements. This is experimental.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry id="ini.apc.num-files-hint">
    <term>
     <parameter>apc.num_files_hint</parameter>
     <type>integer</type>
    </term>
    <listitem>
     <para>
      A "hint" about the number of distinct source files
      that will be included or requested on your web
      server. Set to zero or omit if you're not sure;
      this setting is mainly useful for sites that have
      many thousands of source files.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry id="ini.apc.ttl">
    <term>
     <parameter>apc.ttl</parameter>
     <type>integer</type>
    </term>
    <listitem>
     <para>
      The number of seconds a cache entry is allowed to
      idle in a slot in case this cache entry slot is
      needed by another entry.  Leaving this at zero
      means that your cache could potentially fill up
      with stale entries while newer entries won't be
      cached.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry id="ini.apc.gc-ttl">
    <term>
     <parameter>apc.gc_ttl</parameter>
     <type>integer</type>
    </term>
    <listitem>
     <para>
      The number of seconds that a cache entry may
      remain on the garbage-collection list. This value
      provides a fail-safe in the event that a server
      process dies while executing a cached source file;
      if that source file is modified, the memory
      allocated for the old version will not be
      reclaimed until this TTL reached. Set to zero to
      disable this feature.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry id="ini.apc.cache-by-default">
    <term>
     <parameter>apc.cache_by_default</parameter>
     <type>boolean</type>
    </term>
    <listitem>
     <para>
      On by default, but can be set to off and used in
      conjunction with positive <literal>apc.filters</literal> so that files
      are only cached if matched by a positive filter.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry id="ini.apc.filters">
    <term>
     <parameter>apc.filters</parameter>
     <type>string</type>
    </term>
    <listitem>
     <para>
      A comma-separated list of POSIX extended regular
      expressions. If any pattern matches the source
      filename, the file will not be cached. Note that
      the filename used for matching is the one passed
      to include/require, not the absolute path.  If the
      first character of the expression is a <literal>+</literal> then the
      expression will be additive in the sense that any
      files matched by the expression will be cached, and
      if the first character is a <literal>-</literal> then anything matched
      will not be cached.  The <literal>-</literal> case is the default, so
      it can be left off.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry id="ini.apc.mmap-file-mask">
    <term>
     <parameter>apc.mmap_file_mask</parameter>
     <type>string</type>
    </term>
    <listitem>
     <para>
      If compiled with MMAP support by using <literal>--enable-mmap</literal>
      this is the mktemp-style file_mask to pass to the
      mmap module for determing whether your mmap'ed memory
      region is going to be file-backed or shared memory
      backed.  For straight file-backed mmap, set it to
      something like <literal>/tmp/apc.XXXXXX</literal>
      (exactly 6 <literal>X</literal>s).
      To use POSIX-style shm_open/mmap put a <literal>.shm</literal>
      somewhere in your mask.  e.g. <literal>/apc.shm.XXXXXX</literal>
      You can also set it to <literal>/dev/zero</literal> to use your
      kernel's <literal>/dev/zero</literal> interface to anonymous mmap'ed
      memory.  Leaving it undefined will force an anonymous mmap.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry id="ini.apc.slam-defense">
    <term>
     <parameter>apc.slam_defense</parameter>
     <type>integer</type>
    </term>
    <listitem>
     <para>
      On very busy servers whenever you start the server or
      modify files you can create a race of many processes
      all trying to cache the same file at the same time.
      This option sets the percentage of processes that will
      skip trying to cache an uncached file.  Or think of it
      as the probability of a single process to skip caching.
      For example, setting <literal>apc.slam_defense</literal>
      to <literal>75</literal> would mean that there is
      a 75% chance that the process will not cache an uncached
      file. So, the higher the setting the greater the defense
      against cache slams.  Setting this to <literal>0</literal>
      disables this feature.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry id="ini.apc.file-update-protection">
    <term>
     <parameter>apc.file_update_protection</parameter>
     <type>integer</type>
    </term>
    <listitem>
     <para>
      When you modify a file on a live web server you really
      should do so in an atomic manner.  That is, write to a
      temporary file and rename (<literal>mv</literal>) the file into its
      permanent position when it is ready.  Many text editors, cp, tar and
      other such programs don't do this.  This means that there
      is a chance that a file is accessed (and cached) while it
      is still being written to.  This <literal>apc.file_update_protection</literal>
      setting puts a delay on caching brand new files.  The
      default is 2 seconds which means that if the modification
      timestamp (<literal>mtime</literal>) on a file shows that it is less than 2
      seconds old when it is accessed, it will not be cached.
      The unfortunate person who accessed this half-written file
      will still see weirdness, but at least it won't persist.
      If you are certain you always atomically update your files
      by using something like rsync which does this correctly, you
      can turn this protection off by setting it to 0.  If you
      have a system that is flooded with io causing some update
      procedure to take longer than 2 seconds, you may want to
      increase this a bit.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry id="ini.apc.enable-cli">
    <term>
     <parameter>apc.enable_cli</parameter>
     <type>integer</type>
    </term>
    <listitem>
     <para>
      Mostly for testing and debugging.  Setting this enables APC
      for the CLI version of PHP.  Normally you wouldn't want to
      create, populate and tear down the APC cache on every CLI
      request, but for various test scenarios it is handy to be
      able to enable APC for the CLI version of APC easily.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry id="ini.apc.max_file_size">
    <term>
     <parameter>apc.max_file_size</parameter>
     <type>integer</type>
    </term>
    <listitem>
     <para>
      Prevent files larger than this value from getting cached.  Defaults to
      1M. 
     </para>
    </listitem>
   </varlistentry>
   <varlistentry id="ini.apc.stat">
    <term>
     <parameter>apc.stat</parameter>
     <type>integer</type>
    </term>
    <listitem>
     <para>
      Be careful if you change this setting.  The default is for this to be On
      which means that APC will stat (check) the script on each request to see
      if it has been modified.  If it has been modified it will recompile and
      cache the new version.  If you turn this setting off, it will not check.
      That means that in order to have changes become active you need to
      restart your web server.  On a production server where you rarely
      change the code, turning stats off can produce a significant performance
      boost.
     </para>
     <para>
      For included/required files this option applies as well, but note that
      if you are using relative path includes (any path that doesn't start
      with / on Unix) APC has to check in order to uniquely identify the file.
      If you use absolute path includes APC can skip the stat and use that
      absolute path as the unique identifier for the file.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </para>
</section>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->