FREQUENTLY ASKED QUESTIONS
1. How does all this stuff work?
2. Why are there two implementations? Which one is right for me?
3. What sort of performance benefit will I receive?
4. When I make changes to my files, the changes do not appear. Why not?
5. I'm running the shm implementation and it leaks semaphores. How can I fix this?
6. Why do I get "call to undefined function" PHP errors with APC but not without it?
7. Why do I keep running out of open files when I use the mmap version?
8. What use are per object TTLs?
9. Why can't I specify multiple exclusion filters in php.ini?
10. How do I remove all the cache entries under the mmap version?
11. Why don't my derived classes work correctly?
12. I just upgraded my version of PHP, and now I get unresolved symbol errors. What gives?
13. Why do weird things happen when I pass relative paths to include?
14. Why is the value of include_path in my php.ini being ignored?
1. How does all this stuff work?
The APC cache works by storing the compiled instructions for a PHP script in
shared memory (either SystemV shared memory or memory-mapped files). When a
file is run, the extension checks to see if it is cached. If so, the
instructions are read from memory and the compilation step is bypassed.
Otherwise the file is compiled as usual and inserted into the cache.
2. Why are there two implementations? Which one is right for me?
We wrote two implementations, one using SystemV semaphores and shared memory
and the other using memory-mapped files and file locking, for portability
between Unix systems and for testing. Both support all of the basic cache
operations, but they are not functionally identical. For example, the shared
memory implementation (shm) is capable of much finer control of cached objects
than the memory-mapped file implementation (mmap).
Here is a list of pros and cons for each:
shm
pros:
- supports per object time-to-live values
- cache statistics available for entire webserver
cons:
- as with all programs that use SystemV semaphores, it has the
potential to "leak" semaphores
mmap
pros:
- greater visibility into the inner workings of the cache
- can be used as a general compiler, because the cached objects
are stored as files
cons:
- may require many open files
- cache statistics are per process, not per host
- cache management is more difficult
Our internal tests have shown little difference in speed between the two
implementations under typical conditions. There are unusual situations,
however, under which one implementation will perform better than the other.
For example, in common situations, shm tends to perform slightly better;
but if a webserver serves a very small number of pages, mmap may perform
better because it reduces contention between the webserver processes. If
you need optimal performance, our advice is to try both implementations
and make a decision based on benchmark data.
3. What sort of performance benefit will I receive?
Ahh... the magic question. This really depends on the size and complexity
of your PHP code. A 50% performance improvement is typical for a "Hello
World" program, but the potential benefit is greater as the code increases
in complexity. We saw a roughly 400% performance improvement in our production
environment. As always, your mileage may vary.
4. When I make changes to my files, the changes do not appear. Why not?
APC does not know when you have updated a file, and it will continue to use
the older, cached version of the page, unless one of the following occurs:
you call the PHP function apc_reset_cache; you call the PHP
function apc_rm and provide the filename as an argument; the page
expires; or you restart the webserver. The default time-to-live for all cached
objects is set in the php.ini file; you can also set the TTL for
an individual file by calling apc_set_my_ttl in the file.
Another option is to set apc.check_mtime to 1 in your
php.ini file; at a slight cost in efficiency, APC will
automatically update the cache whenever files are modified. Note that this
works only with the shm implementation.
5. I'm running the shm implementation and it leaks semaphores. How can I fix this?
The simple answer is you can't. If you are willing and able to make minor adjustments to your webserver startup or shutdown scripts, and if ipcs and ipcrm are installed on your system (they should be), you can practically eliminate the problem. You simply need to remove all remaining semaphores from your system when your webservers starts or stops (one or the other). (Beware that this technique, if applied naively, will break other applications running on the webserver that also use semaphores.)
6. Why do I get "call to undefined function" PHP errors with APC but not without it?
Your code creates a conflict in the global namespace, but PHP manages to deal
with it. APC, however, will fail to correctly cache the conflicting modules if
it finds a namespace conflict. Here is an example of how this can occur:
File
PHP permits this kind of conditional inclusion, but it will fail with APC
because A.php includes file B.php, which
defines the function foobar and sets some variable,
say, $B_INCLUDED, to indicate that it has been included.
File A.php now includes file C.php, which
also defines a function named foobar. Before it gets to
the function definition, though, C.php returns if
$B_INCLUDED is true.
C.php is always included and compiled, even though it
never reaches the statement that declares foobar for the second
time. We made the (possibly questionable) decision to designate this a
programming error, so you must "correct" your code before you can use
APC.
7. Why do I keep running out of open files when I use the mmap version?
The mmap implementation of APC requires a lot of open files. One per source
file per webserver process, to be precise. On most Unix systems, it is easy
to raise the maximum number of open files per process. Under Linux, for
example, you can change the value in /proc/sys/fs/file-max.
8. What use are per object TTLs?
Specifying the time-to-live, i.e. the lifetime, of a file (by calling the PHP
function apc_set_my_ttl) allows you cache files that are changed
frequently. If, for example, you know that a page is updated every five
minutes but you would still like to cache it for those five minutes, you can
simply set that page's individual TTL to 300 seconds:
<?
// Set TTL for this page to 5 minutes.
apc_set_my_ttl(300);
// Your code here...
?>
Thus, you can even cache pages that change frequently. Note that this works
only with the shm implementation.
9. Why can't I specify multiple exclusion filters in php.ini?
Because PHP does not support multiple values for a single ini entry and we
were too lazy to provide a workaround. If there is a great need for this
feature from the public, we may implement it in the future. Of course, you
are encouraged to implement and contribute it yourself!
10. How do I remove all the cache entries under the mmap version?
find /your/cache/dir -name '\*_apc' -exec rm {} \;
For what should be obvious reasons we felt uncomfortable adding that
functionality to apc_reset_cache.
11. Why don't my derived classes work correctly?
Support for class inheritance was introduced in version 1.0.4 of APC.
12. I just upgraded my version of PHP, and now I get unresolved symbol errors. What gives?
Between versions of PHP, the definitions of certain internal macros may
change. If you compile APC with one version of PHP and then run it under
another version, APC may fail to load because the PHP symbols in the prior
version no longer exist. The only way to fix this is to recompile APC under
the same version of PHP you are currently running.
13. Why do weird things happen when I pass relative paths to include?
Because you haven't enabled apc.relative_includes in your
php.ini file. Unless instructed not to do so, APC treats
identical relative include paths that point to different files as the same
file.
Note: relative include paths may add substantial overhead to APC, because
it forces APC to perform multiple file system operations for each file.
Without relative include support, APC performs no file system operations
(shm implementation) or about three (mmap implementation) per file.
Using the PHP include_path imposes even more overhead. (Of
course, running with APC is always faster than running without any caching
at all.)
14. Why is the value of include_path in my php.ini being ignored?
Because you haven't enabled apc.relative_includes in your
php.ini file. See question 13 for details.