+++ /dev/null
-APC Quick-Start Braindump
-
-This is a rapidly written braindump of how APC currently works in the
-form of a quick-start guide to start hacking on APC.
-
-1. Install and use APC a bit so you know what it does from the end-user's
- perspective.
- user-space functions are all explained here:
-
-2. Grab the current APC code from CVS:
-
- cvs -d:pserver:cvsread@cvs.php.net:/repository login
- Password: phpfi
- cvs -d:pserver:cvsread@cvs.php.net:/repository co pecl/apc
-
- apc/php_apc.c has most of the code for the user-visible stuff. It is
- also a regular PHP extension in the sense that there are MINIT, MINFO,
- MSHUTDOWN, RSHUTDOWN, etc. functions.
-
-3. Build it.
-
- cd pecl/apc
- phpize
- ./configure --enable-apc --enable-mmap
- make
- cp modules/apc.so /usr/local/lib/php
- apachectl restart
-
-4. Debugging Hints
-
- apachectl stop
- gdb /usr/bin/httpd
- break ??
- run -X
-
- Grab the .gdbinit from the PHP source tree and have a look at the macros.
-
-5. Look through apc/apc_sma.c
- It is a pretty standard memory allocator.
-
- apc_sma_malloc, apc_sma_realloc, apc_sma_strdup and apc_sma_free behave to the
- caller just like malloc, realloc, strdup and free
-
- On server startup the MINIT hook in php_apc.c calls apc_module_init() in
- apc_main.c which in turn calls apc_sma_init(). apc_sma_init calls into
- apc_mmap.c to mmap the specified sized segment (I tend to just use a single
- segment). apc_mmap.c should be self-explanatory. It mmaps a temp file and
- then unlinks that file right after the mmap to provide automatic shared memory
- cleanup in case the process dies.
-
- Once the region has been initialized we stick a header_t at the beginning
- of the region. It contains the total size in header->segsize and the number
- of bytes available in header->avail.
-
- After the header comes a bit of a hack. A zero-sized block is inserted just
- to make things easier later on. And then a huge block that is basically
- the size of the entire segment minus the two (for the 0-sized block, and this one)
- block headers.
-
- The code for this is:
-
- header = (header_t*) shmaddr;
- header->segsize = sma_segsize;
- header->avail = sma_segsize - sizeof(header_t) - sizeof(block_t) - alignword(sizeof(int));
- memset(&header->lock,0,sizeof(header->lock));
- sma_lock = &header->lock;
- block = BLOCKAT(sizeof(header_t));
- block->size = 0;
- block->next = sizeof(header_t) + sizeof(block_t);
- block = BLOCKAT(block->next);
- block->size = header->avail;
- block->next = 0;
-
- So the shared memory looks like this:
-
- +--------+-------+---------------------------------+
- | header | block | block |
- +--------+-------+---------------------------------+
-
- sma_shmaddrs[0] gives you the address of header
-
- The blocks are just a simple offset-based linked list (so no pointers):
-
- typedef struct block_t block_t;
- struct block_t {
- size_t size; /* size of this block */
- size_t next; /* offset in segment of next free block */
- size_t canary; /* canary to check for memory overwrites */
-#ifdef __APC_SMA_DEBUG__
- int id; /* identifier for the memory block */
-#endif
- };
-
- The BLOCKAT macro turns an offset into an actual address for you:
-
- #define BLOCKAT(offset) ((block_t*)((char *)shmaddr + offset))
-
- where shmaddr = sma_shaddrs[0]
-
- And the OFFSET macro goes the other way:
-
- #define OFFSET(block) ((int)(((char*)block) - (char*)shmaddr))
-
- Allocating a block with a call to apc_sma_allocate() walks through the
- linked list of blocks until it finds one that is >= to the requested size.
- The first call to apc_sma_allocate() will hit the second block. We then
- chop up that block so it looks like this:
-
- +--------+-------+-------+-------------------------+
- | header | block | block | block |
- +--------+-------+-------+-------------------------+
-
- Then we unlink that block from the linked list so it won't show up
- as an available block on the next allocate. So we actually have:
-
- +--------+-------+ +-------------------------+
- | header | block |------>| block |
- +--------+-------+ +-------------------------+
-
- And header->avail along with block->size of the remaining large
- block are updated accordingly. The arrow there representing the
- link which now points to a block with an offset further along in
- the segment.
-
- When the block is freed using apc_sma_deallocate() the steps are
- basically just reversed. The block is put back and then the deallocate
- code looks at the block before and after to see if the block immediately
- before and after are free and if so the blocks are combined. So you never
- have 2 free blocks next to each other, apart from at the front with that
- 0-sized dummy block. This mostly prevents fragmentation. I have been
- toying with the idea of always allocating block at 2^n boundaries to make
- it more likely that they will be re-used to cut down on fragmentation further.
- That's what the POWER_OF_TWO_BLOCKSIZE you see in apc_sma.c is all about.
-
- Of course, anytime we fiddle with our shared memory segment we lock using
- the locking macros, LOCK() and UNLOCK().
-
- That should mostly take care of the low-level shared memory handling.
-
-6. Next up is apc_main.c and apc_cache.c which implement the meat of the
- cache logic.
-
- The apc_main.c file mostly calls functions in apc_sma.c to allocate memory
- and apc_cache.c for actual cache manipulation.
-
- After the shared memory segment is created and the caches are initialized,
- apc_module_init() installs the my_compile_file() function overriding Zend's
- version. I'll talk about my_compile_file() and the rest of apc_compile.c
- in the next section. For now I will stick with apc_main.c and apc_cache.c
- and talk about the actual caches. A cache consists of a block of shared
- memory returned by apc_sma_allocate() via apc_sma_malloc(). You will
- notice references to apc_emalloc(). apc_emalloc() is just a thin wrapper
- around PHP's own emalloc() function which allocates per-process memory from
- PHP's pool-based memory allocator. Don't confuse apc_emalloc() and
- apc_sma_malloc() as the first is per-process and the second is shared memory.
-
- The cache is stored in/described by this struct allocated locally using
- emalloc():
-
- struct apc_cache_t {
- void* shmaddr; /* process (local) address of shared cache */
- header_t* header; /* cache header (stored in SHM) */
- slot_t** slots; /* array of cache slots (stored in SHM) */
- int num_slots; /* number of slots in cache */
- int gc_ttl; /* maximum time on GC list for a slot */
- int ttl; /* if slot is needed and entry's access time is older than this ttl, remove it */
- };
-
- Whenever you see functions that take a 'cache' argument, this is what they
- take. And apc_cache_create() returns a pointer to this populated struct.
-
- At the beginning of the cache we have a header. Remember, we are down a level now
- from the sma stuff. The sma stuff is the low-level shared-memory allocator which
- has its own header which is completely separate and invisible to apc_cache.c.
- As far as apc_cache.c is concerned the block of memory it is working with could
- have come from a call to malloc().
-
- The header looks like this:
-
- typedef struct header_t header_t;
- struct header_t {
- int num_hits; /* total successful hits in cache */
- int num_misses; /* total unsuccessful hits in cache */
- slot_t* deleted_list; /* linked list of to-be-deleted slots */
- };
-
- Since this is at the start of the shared memory segment, these values are accessible
- across all the yapache processes and hence access to them has to be locked.
-
- After the header we have an array of slots. The number of slots is user-defined
- through the apc.num_slots ini hint. Each slot is described by:
-
- typedef struct slot_t slot_t;
- struct slot_t {
- apc_cache_key_t key; /* slot key */
- apc_cache_entry_t* value; /* slot value */
- slot_t* next; /* next slot in linked list */
- int num_hits; /* number of hits to this bucket */
- time_t creation_time; /* time slot was initialized */
- time_t deletion_time; /* time slot was removed from cache */
- time_t access_time; /* time slot was last accessed */
- };
-
- The slot_t *next there is a linked list to other slots that happened to hash to the
- same array position.
-
- apc_cache_insert() shows what happens on a new cache insert.
-
- slot = &cache->slots[hash(key) % cache->num_slots];
-
- cache->slots is our array of slots in the segment. hash() is simply:
-
- static unsigned int hash(apc_cache_key_t key)
- {
- return key.data.file.device + key.data.file.inode;
- }
-
- That is, we use the file's device and inode to uniquely identify it. Initially
- we had used the file's full path, but getting that requires a realpath() call which
- is amazingly expensive since it has to stat each component of the path to resolve
- symlinks and get rid of relative path components. By using the device+inode we
- can uniquely identify a file with a single stat.
-
- So, on an insert we find the array position in the slots array by hasing the device+inode.
- If there are currently no other slots there, we just create the slot and stick it into
- the array:
-
- *slot = make_slot(key, value, *slot, t)
-
- If there are other slots already at this position we walk the link list to get to
- the end. Here is the loop:
-
- while (*slot) {
- if (key_equals((*slot)->key.data.file, key.data.file)) {
- /* If existing slot for the same device+inode is different, remove it and insert the new version */
- if ((*slot)->key.mtime != key.mtime) {
- remove_slot(cache, slot);
- break;
- }
- UNLOCK(cache);
- return 0;
- } else if(cache->ttl && (*slot)->access_time < (t - cache->ttl)) {
- remove_slot(cache, slot);
- continue;
- }
- slot = &(*slot)->next;
- }
-
- That first key_equals() check sees if we have an exact match meaning the file
- is already in the cache. Since we try to find the file in the cache before doing
- an insert, this will generally only happen if another process managed to beat us
- to inserting it. If we have a newer version of the file at this point we remove
- it an insert the new version. If our version is not newer we just return without
- doing anything.
-
- While walking the linked list we also check to see if the cache has a TTL defined.
- If while walking the linked list we see a slot that has expired, we remove it
- since we are right there looking at it. This is the only place we remove stale
- entries unless the shared memory segment fills up and we force a full expunge via
- apc_cache_expunge(). apc_cache_expunge() walks the entire slots array and walks
- down every linked list removing stale slots to free up room. This is obviously
- slow and thus only happens when we have run out of room.
-
- apc_cache_find() simply hashes and returns the entry if it is there. If it is there
- but older than the mtime in the entry we are looking for, we delete the one that is
- there and return indicating we didn't find it.
-
- Next we need to understand what an actual cache entry looks like. Have a look at
- apc_cache.h for the structs. I sort of glossed over the key part earlier saying
- that we just used the device+inode to find a hash slot. It is actually a bit more
- complex than that because we have two kinds of caches. We have the standard file
- cache containing opcode arrays, but we also have a user-controlled cache that the
- user can insert whatever they want into via apc_store(). For the user cache we
- obviously don't have a device+inode. The actual identifier is provided by the user
- as a char *. So the key is actually a union that looks like this:
-
- typedef union _apc_cache_key_data_t {
- struct {
- int device; /* the filesystem device */
- int inode; /* the filesystem inode */
- } file;
- struct {
- char *identifier;
- } user;
- } apc_cache_key_data_t;
-
- struct apc_cache_key_t {
- apc_cache_key_data_t data;
- int mtime; /* the mtime of this cached entry */
- };
-
- And we have two sets of functions to do inserts and finds. apc_cache_user_find()
- and apc_cache_user_insert() operate on the user cache.
-
- Ok, on to the actual cache entry. Again, because we have two kinds of caches, we
- also have the corresponding two kinds of cache entries described by this union:
-
- typedef union _apc_cache_entry_value_t {
- struct {
- char *filename; /* absolute path to source file */
- zend_op_array* op_array; /* op_array allocated in shared memory */
- apc_function_t* functions; /* array of apc_function_t's */
- apc_class_t* classes; /* array of apc_class_t's */
- } file;
- struct {
- char *info;
- zval *val;
- unsigned int ttl;
- } user;
- } apc_cache_entry_value_t;
-
- And then the actual cache entry:
-
- struct apc_cache_entry_t {
- apc_cache_entry_value_t data;
- unsigned char type;
- int ref_count;
- };
-
- The user entry is pretty simple and not all that important for now. I will
- concentrate on the file entries since that is what holds the actual compiled
- opcode arrays along with the functions and classes required by the executor.
-
- apc_cache_make_file_entry() in apc_cache.c shows how an entry is constructed.
- The main thing to understand here is that we need more than just the opcode
- array, we also need the functions and classes created by the compiler when it
- created the opcode array. As far as the executor is concerned, it doesn't know
- that it isn't operating in normal mode being called right after the parse/compile
- phase, so we need to recreate everything so it looks exactly like it would at
- that point.
-
-7. my_compile_file() and apc_compile.c
-
- my_compile_file() in apc_main.c controls where we get the opcodes from. If
- the user-specified filters exclude the file from being cached, then we just
- call the original compile function and return. Otherwise we fetch the request
- time from Apache to avoid an extra syscall, create the key so we can look up
- the file in the cache. If we find it we stick it on a local stack which we
- use at cleanup time to make sure we return everything back to normal after a
- request and call cached_compile() which installs the functions and classes
- associated with the op_array in this entry and then copy the op_array down
- into our memory space for execution.
-
- If we didn't find the file in the cache, we need to compile it and insert it.
- To compile it we simply call the original compile function:
-
- op_array = old_compile_file(h, type TSRMLS_CC);
-
- To do the insert we need to copy the functions, classes and the opcode array
- the compile phase created into shared memory. This all happens in apc_compile.c
- in the apc_copy_op_array(), apc_copy_new_functions() and apc_copy_new_classes()
- functions. Then we make the file entry and do the insert. Both of these
- operations were described in the previous section.
-
-8. The Optimizer
-
- The optimizer has been deprecated.
-
-If you made it to the end of this, you should have a pretty good idea of where things are in
-the code. I skimmed over a lot of things, so plan on spending some time reading through the code.
-
projects / php5-apc.git / blobdiff