<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.17 $ -->
<section xml:id="apc.configuration" xmlns="http://docbook.org/ns/docbook">
 &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_SYSTEM</entry>
      <entry>PHP_INI_SYSTEM in APC 2. PHP_INI_ALL in APC &lt;= 3.0.12.</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>PHP_INI_SYSTEM in APC 2. Removed in APC 3.0.13.</entry>
     </row>
     <row>
      <entry>apc.num_files_hint</entry>
      <entry>"1000"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry></entry>
     </row>
     <row>
      <entry>apc.user_entries_hint</entry>
      <entry>"4096"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry>Available since APC 3.0.0.</entry>
     </row>
     <row>
      <entry>apc.ttl</entry>
      <entry>"0"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry>Available since APC 3.0.0.</entry>
     </row>
     <row>
      <entry>apc.user_ttl</entry>
      <entry>"0"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry>Available since APC 3.0.0.</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_ALL</entry>
      <entry>PHP_INI_SYSTEM in APC &lt;= 3.0.12. Available since APC 3.0.0.</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>Available since APC 3.0.0.</entry>
     </row>
     <row>
      <entry>apc.file_update_protection</entry>
      <entry>"2"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry>Available since APC 3.0.6.</entry>
     </row>
     <row>
      <entry>apc.enable_cli</entry>
      <entry>"0"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry>Available since APC 3.0.7.</entry>
     </row>
     <row>
      <entry>apc.max_file_size</entry>
      <entry>"1M"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry>Available since APC 3.0.7.</entry>
     </row>
     <row>
      <entry>apc.stat</entry>
      <entry>"1"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry>Available since APC 3.0.10.</entry>
     </row>
     <row>
      <entry>apc.write_lock</entry>
      <entry>"1"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry>Available since APC 3.0.11.</entry>
     </row>
     <row>
      <entry>apc.report_autofilter</entry>
      <entry>"0"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry>Available since APC 3.0.11.</entry>
     </row>
     <row>
      <entry>apc.include_once_override</entry>
      <entry>"0"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry>Available since APC 3.0.12.</entry>
     </row>
     <row>
      <entry>apc.rfc1867</entry>
      <entry>"0"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry>Available since APC 3.0.13.</entry>
     </row>
     <row>
      <entry>apc.rfc1867_prefix</entry>
      <entry>"upload_"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry></entry>
     </row>
     <row>
      <entry>apc.rfc1867_name</entry>
      <entry>"APC_UPLOAD_PROGRESS"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry></entry>
     </row>
     <row>
      <entry>apc.rfc1867_freq</entry>
      <entry>"0"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry></entry>
     </row>
     <row>
      <entry>apc.localcache</entry>
      <entry>"0"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry>Available since APC 3.0.14.</entry>
     </row>
     <row>
      <entry>apc.localcache.size</entry>
      <entry>"512"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry>Available since APC 3.0.14.</entry>
     </row>
     <row>
      <entry>apc.coredump_unmap</entry>
      <entry>"0"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry>Available since APC 3.0.16.</entry>
     </row>
    </tbody>
   </tgroup>
  </table>
  &ini.php.constants;
 </para>
 
 &ini.descriptions.title;
 
 <para>
  <variablelist>
   <varlistentry xml: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 xml: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 xml: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 xml: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 xml: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 xml:id="ini.apc.user-entries-hint">
    <term>
     <parameter>apc.user_entries_hint</parameter>
     <type>integer</type>
    </term>
    <listitem>
     <para>
      Just like <link linkend="ini.apc.num-files-hint">apc.num_files_hint</link>,
      a "hint" about the number of distinct user cache variables to store.
      Set to zero or omit if not sure.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml: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 xml:id="ini.apc.user-ttl">
    <term>
     <parameter>apc.user_ttl</parameter>
     <type>integer</type>
    </term>
    <listitem>
     <para>
      The number of seconds a user 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 xml: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 xml: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 xml: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 xml: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 xml: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>
     <para>
      Deprecated by <link linkend="ini.apc.write-lock">apc.write_lock</link>.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml: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 xml: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 xml: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 xml: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>
   
   <varlistentry xml:id="ini.apc.write-lock">
    <term>
     <parameter>apc.write_lock</parameter>
     <type>boolean</type>
    </term>
    <listitem>
     <para>
      On busy servers when you first start up the server, or when many files
      are modified, you can end up with all your processes trying to compile
      and cache the same files. With write_lock enabled, only one process at a
      time will try to compile an uncached script while the other processes
      will run uncached instead of sitting around waiting on a lock.
     </para>
    </listitem>
   </varlistentry>
   
   <varlistentry xml:id="ini.apc.report-autofilter">
    <term>
     <parameter>apc.report_autofilter</parameter>
     <type>boolean</type>
    </term>
    <listitem>
     <para>
      Logs any scripts that were automatically excluded from being cached due
      to early/late binding issues.
     </para>
    </listitem>
   </varlistentry>
   
   <varlistentry xml:id="ini.apc.include-once-override">
    <term>
     <parameter>apc.include_once_override</parameter>
     <type>boolean</type>
    </term>
    <listitem>
     <para>
      Optimize <function>include_once</function> and <function>require_once</function>
      calls and avoid the expensive system calls used.
     </para>
    </listitem>
   </varlistentry>
   
   <varlistentry xml:id="ini.apc.rfc1867">
    <term>
     <parameter>apc.rfc1867</parameter>
     <type>boolean</type>
    </term>
    <listitem>
     <para>
      RFC1867 File Upload Progress hook handler is only available if you
      compiled APC against PHP 5.2.0 or later. When enabled, any file uploads
      which includes a field called <literal>APC_UPLOAD_PROGRESS</literal>
      before the file field in an upload form will cause APC to automatically
      create an upload_<emphasis>key</emphasis> user cache entry where
      <emphasis>key</emphasis> is the value of the
      <literal>APC_UPLOAD_PROGRESS</literal> form entry.
     </para>
     <para>
      Note that the file upload tracking is not threadsafe at this point, so
      new uploads that happen while a previous one is still going will disable
      the tracking for the previous.
     </para>
     <para>
      <example>
       <title>An apc.rfc1867 example</title>
       <programlisting role="php">
<![CDATA[
<?php
print_r(apc_fetch("upload_$_POST[APC_UPLOAD_PROGRESS]"));
?>
]]>
       </programlisting>
       &example.outputs.similar;
       <screen>
<![CDATA[
Array
(
    [total] => 1142543
    [current] => 1142543
    [rate] => 1828068.8
    [filename] => test
    [name] => file
    [temp_filename] => /tmp/php8F
    [cancel_upload] => 0
    [done] => 1
)
]]>
       </screen>
      </example>
     </para>
    </listitem>
   </varlistentry>
   
   <varlistentry xml:id="ini.apc.rfc1867_prefix">
    <term>
     <parameter>apc.rfc1867_prefix</parameter>
     <type>string</type>
    </term>
    <listitem>
     <para>
      Key prefix to use for the user cache entry generated by rfc1867 upload
      progress functionality.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="ini.apc.rfc1867_name">
    <term>
     <parameter>apc.rfc1867_name</parameter>
     <type>string</type>
    </term>
    <listitem>
     <para>
      Specify the hidden form entry name that activates APC upload progress
      and specifies the user cache key suffix.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="ini.apc.rfc1867_freq">
    <term>
     <parameter>apc.rfc1867_freq</parameter>
     <type>string</type>
    </term>
    <listitem>
     <para>
      The frequency that updates should be made to the user cache entry for
      upload progress.  This can take the form of a percentage of the total
      file size or a size in bytes optionally suffixed with 'k', 'm', or 'g'
      for kilobytes, megabytes, or gigabytes respectively (case insensitive).
      A setting of 0 updates as often as possible, which may cause slower
      uploads.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="ini.apc.localcache">
    <term>
     <parameter>apc.localcache</parameter>
     <type>boolean</type>
    </term>
    <listitem>
     <para>
      This enables a lock-free local process shadow-cache which reduces lock
      contention when the cache is being written to.
     </para>
    </listitem>
   </varlistentry>
   
   <varlistentry xml:id="ini.apc.localcache.size">
    <term>
     <parameter>apc.localcache.size</parameter>
     <type>integer</type>
    </term>
    <listitem>
     <para>
      The size of the local process shadow-cache, should be set to a
      sufficently large value, approximately half of
      <link linkend="ini.apc.num-files-hint">apc.num_files_hint</link>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="ini.apc.coredump_unmap">
    <term>
     <parameter>apc.coredump_unmap</parameter>
     <type>boolean</type>
    </term>
    <listitem>
     <para>
      Enables APC handling of signals, such as SIGSEGV, that write
      core files when signaled. When these signals are received,
      APC will attempt to unmap the shared memory segment in order
      to exclude it from the core file. This setting may improve
      system stability when fatal signals are received and a large 
      APC shared memory segment is configured.
     </para>
     <warning>
      <para>
       This feature is potentially dangerous. Unmapping the shared
       memory segment in a fatal signal handler may cause undefined
       behaviour if a fatal error occurs.
      </para>
     </warning>
     <note>
      <para>
       Although some kernels may provide a facility to ignore various
       types of shared memory when generating a core dump file, these 
       implementations may also ignore important shared memory segments
       such as the Apache scoreboard.
      </para>
     </note>
    </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
-->