Hello all, my name is Eddie and I hope that you all get to hear a lot
of me in the foreseeable future. I'm a web developer with the
eventual goal of contributing to the PHP source code itself, but it
is, to say the least, a bit intimidating. I usually idle and chat in
##php on freenode and there was a documentation inconsistency /
confusion that arose, and after talking to TML (I don't know what his
real name is, sorry) and Rasmus in IRC, I decided I would start
contributing to the documentation.
In reading through the guide, I noticed that professionalism came up a
few times, so if patches where grammatical errors are fixed are not
wanted, tell me now so I don't go about making patches that change a
sentence structure to prevent back-to-back prepositions or something
equally ridiculous. While I was in college, I volunteer copy-edited
our school newspaper, so I fully expect to build up a reputation as an
absolute grammar nazi. But that's okay, as that's the best kind of
nazi :)
I look forward to contributing to this effort :)
-Eddie
Oh, and I guess I should put my money where my mouth is, so to speak,
so I've attached a handful of patches to fix some documentation
"bugs." I understand that a lot of these patches are entirely
linguistic (and subjective) in nature, and I fully expect some of them
to be rejected. Each is explained:
1. apc_book.diff changes the sentence "it was conceived of to..." to
"Its goals are to" as dual prepositions are a grammatical error and
sound really, really awkward.
2. apc_ini.diff is a pretty thorough reconstruction of the
introductory paragraphs (and few directives) to eliminate use of the
second person and offer a more fine-tuned, professional voice (imho).
Let me know if I've done something egregiously wrong :)
Index: en/reference/apc/book.xml
===================================================================
RCS file: /repository/phpdoc/en/reference/apc/book.xml,v
retrieving revision 1.3
diff -u -r1.3 book.xml
--- en/reference/apc/book.xml 16 Apr 2009 20:11:47 -0000 1.3
+++ en/reference/apc/book.xml 23 Jun 2009 06:03:11 -0000
@@ -11,7 +11,7 @@
&reftitle.intro;
<para>
The Alternative PHP Cache (APC) is a free and open opcode cache for PHP.
- It was conceived of to provide a free, open, and robust framework for
+ Its goal is to provide a free, open, and robust framework for
caching and optimizing PHP intermediate code.
</para>
</preface>
Index: en/reference/apc/ini.xml
===================================================================
RCS file: /repository/phpdoc/en/reference/apc/ini.xml,v
retrieving revision 1.26
diff -u -r1.26 ini.xml
--- en/reference/apc/ini.xml 3 Jun 2009 19:23:04 -0000 1.26
+++ en/reference/apc/ini.xml 23 Jun 2009 06:41:50 -0000
@@ -8,28 +8,28 @@
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.
+ There are two primary decisions to be made configuring APC. First,
+ how much memory is going to be allocated to APC; and second, whether APC
+ will check if a file has been modified on every request. The two ini
+ directives that control these settings are <literal>apc.shm_size</literal>
+ and <literal>apc.stat</literal>, respectively. Read the sections on these
+ two directive 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.
+ Once the server is running, the <literal>apc.php</literal> script that
+ is bundled with the extension should be copied somewhere into the docroot and
+ viewed with a browser as it provides a detailed analysis of the internal
+ workings of APC. If GD is enabled in PHP, it will even display some
+ interesting graphs. The first thing to ensure, of course, is that it is
+ actually caching files. If APC is working, the <literal>Cache full count
+ </literal> number (on the left) will display the number of times the cache
+ has reached maximum capacity and has had to forcefully clean any entries that
+ haven't been accessed in the last <literal>apc.ttl</literal> seconds. This
+ number is minimized in a well-configured cache. If the cache is constantly
+ being filled, and thusly forcefully freed, the resulting churning will have
+ disparaging effects on script performance. The easiest way to minimize this
+ number is to allocate more memory for APC. Barring that, the
<literal>apc.filters
+ </literal> ought to be used to cache fewer scripts.
</para>
<para>
<table>
@@ -246,9 +246,9 @@
<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.
+ shared memory but <literal>apc.shm_size</literal>
+ is set as high as the system allows, raising
+ this value might prevent APC from exhausting its memory.
</para>
</listitem>
</varlistentry>
@@ -289,7 +289,7 @@
<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;
+ server. Set to zero or omit if unsure;
this setting is mainly useful for sites that have
many thousands of source files.
</para>
@@ -318,7 +318,7 @@
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
+ means that APC's cache could potentially fill up
with stale entries while newer entries won't be
cached. In the event of a cache running out of
available memory, the cache will be completely
@@ -338,7 +338,7 @@
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
+ means that APC's cache could potentially fill up
with stale entries while newer entries won't be
cached. In the event of a cache running out of
available memory, the cache will be completely
@@ -454,26 +454,26 @@
</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
+ When a file is modified on a live web server it really
+ ought to be done in an atomic manner. That is, written to a
+ temporary file and renamed (<literal>mv</literal>) the file into its
permanent position when it is ready. Many text editors,
<command>cp</command>, <command>tar</command> 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
+ 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 <command>rsync</command> 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.
+ If all of the webserver's files are atomically updated, via
+ some method like <command>rsync</command> (which updates correctly),
+ this protection can be disabled by setting this directive to 0.
+ If the system is flooded with i/o and some update procedures
+ are taking longer than 2 seconds, this setting should be increased
+ to enable the protection on those slower update operations.
</para>
</listitem>
</varlistentry>
@@ -485,10 +485,10 @@
<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.
+ for the CLI version of PHP. Under normal circumstances, it is
+ not ideal to create, populate and destroy the APC cache on every
+ CLI request, but for various test scenarious it is useful to be
+ able to enable APC for the CLI version of PHP easily.
</para>
</listitem>
</varlistentry>
@@ -511,18 +511,19 @@
</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.
+ Be careful changing this setting. This defaults to on, forcing APC to
+ stat (check) the script on each request to determine if it has been
modified.
+ If it has been modified it will recompile and cache the new version.
+ If this setting is off, APC will not check, which usually means that to
+ force APC to recheck files, the web server will have to be restarted or
the
+ cache will have to be manually cleared. Note that FastCGI web server
configurations
+ may not clear the cache on restart. On a production server where the
+ script files rarely change, a significant performance boost can be
+ achieved by disabled stats.
</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
+ for 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.
@@ -537,11 +538,12 @@
</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.
+ On busy servers, when the web server is first started, or when many files
+ have been modified at the same time, APC may try to compile and cache
the
+ same file multiple times. Write_lock guaranttes that only one process
+ will attempt to compile and cache an uncached script. The other
processes
+ attempting to use the script will run without using the opcode cache,
rather
+ than locking and waiting for the cache to prime.
</para>
</listitem>
</varlistentry>
@@ -579,8 +581,8 @@
</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
+ RFC1867 File Upload Progress hook handler is only available if APC
+ was compiled 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
