
<h2>Server Documents</h2>

This flow is implemented in hphp/runtime/base/server/http_server.cpp:

                              +-------------+
                              | APC Priming |
                              +------+------+
                                     |
                                     V
                            +-----------------+
                            | StartupDocument |
                            +--------+--------+
                                     |
                                     V
                   +---------------------------------+
                   |                                 |
                   V                                 V
    +============================+          +=================+
    |       Worker Thread        |          | Service Threads |
    |____________________________|          |_________________|
    |                            |          |                 |
    |  +-----------+             |          | ThreadDocuments |
    |  |           |             |          |                 |
    |  |           V             |          +=================+
    |  |   +----------------+    |
    |  |   |  RequestInit   |    |
    |  |   +----------------+    |
    |  |           |             |
    |  |           +----<-----+  |
    |  |           V          |  |
    |  |   +----------------+ R  |
    |  |   |  URL Handling  | P  |
    |  |   +----------------+ C  |
    |  |           |          |  |
    |  |           +---->-----+  |
    |  |           |             |
    |  +--(sweep)--+             |
    |                            |
    +============================+


1. StartupDocument

This file is executed when web server starts, and it is executed before any
thread gets started but after APC is primed. Example use:

  * bootstrapping server
  * preparing parameters for service threads (see below): in this case, we have
    to use APC to pass those parameters into service threads.

2. ThreadDocuments

Each one of these files will be executed in its own thread, and they don't
share variables with any other threads. Therefore, if we need to pass data
between them, we have to use APC.

There is a system function "hphp_service_thread_started" that needs to be
called at certain point. This function tells the engine that this thread has
finished any initialization sequences that have to happen before any HTTP
request is handled. Even if a service thread doesn't have any work to do
before HTTP requests, hphp_service_thread_started() is still needed for engine
to proceed without infinite waiting for service threads to start.

There is also another variant of these threads, called ThreadLoopDocuments, that
differs from normal ThreadDocuments in that it executes the document in an
infinite loop, and doesn't have any requirements of hphp_service_thread_started
being called. It can be useful to recover memory after different execution of
the document.

3. RequestInitDocument and RequestInitFunction

When a worker thread resets, the RequestInitDocument and/or RequestInitFunction
are executed in order to initialize certain states or request specific coding.
If both RequestInitDocument and RequestInitFunction are specified, the
RequestInitDocument is executed before the RequestInitFunction.

4. RPCRequestHandler

RPCRequestHandler will call ExecutionContext::backupSession() right after
RequestInit function/document, and it will call ExecutionContext::
restoreSession() right after it finishes one request processing and it goes
back to a state right after RequestInit is executed.

RPCRequestHandler will reset a worker thread from time to time, either after
the worker thread has processed a certain number of requests or after certain
amount of time. When this happens, it will perform a sweep and re-execute
RequestInit function/document.