Doc #42683 [Opn->Asn]: Need APC theory-of-operation documentation

Edit report at http://bugs.php.net/bug.php?id=42683&edit=1 ID: 42683 Updated by: kalle@php.net Reported by: tony at tigerheron dot com Summary: Need APC theory-of-operation documentation -Status: Open +Status: Assigned Type: Documentation Problem Package: Documentation problem Operating System: ANY PHP Version: Irrelevant -Assigned To: +Assigned To: kalle Block user comment: N New Comment: Assigning myself and Gopal to this one. Gopal said he will provide some of the material he had for APC that we can incorporate for the intermediate user into the manual so that you don't need to be a systems hacker to get it running in a nice manner Previous Comments: ------------------------------------------------------------------------ [2007-10-15 18:49:36] philip@php.net Sounds reasonable, let's keep it open so someone will find and tackle this. Everyone should feel free to add knowledge and/or links to resources here too. In the very least we could find information to link to from ref.apc. Also, the upcoming documentation style allows this type of information (like extension specific tutorials). ------------------------------------------------------------------------ [2007-09-20 08:51:47] bjori@php.net Personally I would like to see tutorials, howto and best practices for each extension in the manual.. :) Please use our mailing list (phpdoc@lists.php.net) for these kind of discussions. ------------------------------------------------------------------------ [2007-09-19 22:10:06] tony at tigerheron dot com Thanks for the reassurance nlopess, but it sounds like you could use a good APC reference yourself. Then you wouldn't have to guess as to whether the behavior was a bug or a feature. I believe there are conditions under which APC will not and cannot cache the compiled code. Certainly, Rasmus seems to think so and I would think he would know. I also do not believe he considers it a bug in APC, although you would have to check with him. Finally, I don't know that anyone is working on this or intends to work on it. There are hints throughout the Web about some of the conditions under which code will be or won't be cached. I'm trying to get these documented. I'm sure you want PHP to have the best documentation possible, so I'm puzzled by your resistance and why this bug report remains WONTFIX. Because it's in the WONTFIX state, that also means no one else can comment on it besides you and me, so we're missing out from whatever wisdom others could contribute to this discussion. Would it be possible for you to re-open it? ------------------------------------------------------------------------ [2007-09-19 21:16:26] nlopess@php.net ok, so not caching all the (compiled) files can be seen like a bug and I'm sure somebody is working on that. My advise is: don't worry with that, because the situation will improve over the time. ------------------------------------------------------------------------ [2007-09-17 16:23:46] tony at tigerheron dot com > the php manual isn't a book for a computer science course. Yes, you are correct in that the PHP manual is not the place for tutorials or a how-to-program guide. I apologize for the awkward phrasing. > If you want to know how a opcode cache works, the php manual is > surely not the best place to look at. First, I am not interested in the general theory of opcode caching. Not all opcode caches work the same way. I want to know how APC works. > Anyway, all code you write in PHP is compiled to opcodes (and it > is not the job of APC to compile the code). Thanks for the clarification. You can understand the confusion, I'm sure, given the low-quality of the APC documentation, the presence of a function called apc_compile_file and the presence of a setting named apc.optimization. But let me rephrase as: When writing code, for example, I don't know under which conditions I may be creating code whose opcodes will not be cached by APC. I'm asking for a precise specification of the APC module, not a tutorial. Recently, a blogger posted a quote from Rasmus about the behavior of APC with regards to __autoload (http://pooteeweet.org/blog/538). This triggered a discussion on PECL-DEV where Rasmus somewhat modified his statement (http://marc.info/?l=pecl-dev&m=116512075914909&w=2) after some speculation from various people about what APC would or wouldn't do. I don't know about the documentation quality goals for PHP, but it should be possible for a reasonably experienced programmer to inspect reference-quality documentation and correctly answer questions about what APC does and doesn't do. The main question that the current documentation doesn't answer is: under what conditions will APC cache a file's opcodes vs. the original file vs. not cache at all. I just read the entire APC manual page (http://www.php.net/manual/en/ref.apc.php) and, while one could guess that APC performs some sort of automatic caching, I couldn't find a single sentence that actually stated this. Perhaps I missed it and you can point it out. This seems like something that should be explicit. I also looked at apc_compile_file. It sounds as though any file can be compiled and cached. But Rasmus says there are conditions under which APC will not cache (http://marc.info/?l=pecl-dev&m=116515671021728&w=2). Can we document those conditions, at least the ones that APC tests for? ------------------------------------------------------------------------ The remainder of the comments for this report are too long. To view the rest of the comments, please view the bug report online at http://bugs.php.net/bug.php?id=42683 -- Edit this bug report at http://bugs.php.net/bug.php?id=42683&edit=1