xcache how does it work? code coverage? clogs? OOM

I've searched all over the web for documentation including on the XCache website.

I'm new to PHP opcode caching and XCache. I'd like an explanation of how XCache works. I know that it stores compiled php code so that it doesn't need to be recompiled everytime. But how does XCache know when php code has been updated and thus the cache is out of date?

How do I know if I need to clear the cache?

Does XCache compile and cache all php code on the server? If so can this be configured?

What are clogs? OOMs? I see large numbers for both of these in the XCache Admin page interface.

In the Code Coverage Viewer... what does Percent mean? Is this the percentage of code that has been cached? Does hits mean the number of lines of compiled code that has been read from cache? Does lines mean the total number of lines of code? What is the ToDo column for? Why are some lines highlighted in red?

I'm using PHP 5.3.2, XCache 1.3.0, and Ubuntu 10.04 if it helps.

Xcache:

optimizes performance by removing the compilation time of PHP scripts by caching the compiled state of PHP scripts into the shm (RAM) and uses the compiled version straight from the RAM.

Based on observations using PHP 5.5.3 and Xcache 3.1.0 this is what I can deduce:

Cacher

This module deals with two kinds of caching Opcode and Variable.

The Opcode caching is designed to be a simple drop-in. You can't customize how it decides to cache, just how much:

xcache.count setting refers to how many cache threads and correlates to how many processor cores you want to utilize — the idea is that multithreading should be the fastest, but there is no guarantee so experiment yourself
As a guideline, valid count values would be 2^n like 1, 2, 4, 8 — 0 will disable the cacher and other values will get rounded to the nearest valid value
xcache.size setting refers to the aggregate memory of all cache threads. So, each thread gets roughly size/count amount of memory
OOM aka Out of Memory, refers to the event of a cache thread hitting it's maximum size

Variable caching requires using a simple get/set api in your app code. After enabling it using xcache.var_size and xcache.var_count (similar to Opcode settings) you use xcache_set($var1) and xcache_get($var1) in your scripts.

Invalidation

The xcache.stat setting controls whether or not to check if the file was modified since it was cached:

When set to On files get checked and re-cached
When set to Off skips the check will keep the first cached version as long as the expiration time, which could help performance by limiting disk i/o

In your dev environment it's a good idea to keep it On so you can update and check your code continuously — otherwise you have to flush the cache to see updates to files.

Flushing

There is a web admin interface which allows you to flush a particular cache. The web admin uses a php api: xcache_clear_cache(…).

Since the cache is RAM based anytime the server restarts the cache should be flushed.

Expiration

Cached items expire according to xcache.ttl and xcache.var_ttl which respectively control the number of seconds a cached item lives (0 is indefinite and the default).

Coverager

The coverager module, aka Code Coverage, is a little mysterious. According to the FeatureList it seems like a diagnostic tool intended to be enabled for temporary administrative/testing situations:

Coverager + real life testcase framework, this include: [TOSHARE]

real life testcase framework, a control script with real browser. you have to write the test cases.

builtin Coverager + its viewer from web, to see how much script you have tested.

the testcase+Coverager just help you make sure all real life php web applications is running correctly when

after enabling XCache

after upgrading php4 to php5

after upgrading php4/5 to php6