tips.txt in passenger-4.0.38

- old
+ new

@@ -458,22 +458,22 @@
  * `PASSENGER_SERVER_INSTANCE_DIR`
  * `PASSENGER_GENERATION_PATH`
 
 ==== Blocking and concurrency
 
-All hooks block. That is, Phusion Passenger waits until your hook command is finished. You should therefore be careful when writing hook scripts: if your script never finishes, so Phusion Passenger does not do that either.
+All hooks block in the background. That is, while your hook command is running, Phusion Passenger can still handle web requests, but the background thread which is running your hook will be blocked and won't be able to perform any further operations. For example, if you wrote a hook script for the `attached_process` event, then Phusion Passenger won't be able to attach further processes until your hook script finishes. You should therefore be careful when writing hook scripts.
 
 If you have a bug in your script and it blocks, then you will be able to see that using the command `passenger-status --show=backtraces` which prints the backtraces of all threads in the Phusion Passenger HelperAgent. Look for the `runSingleHookScript` function in the backtrace. The following example shows at line 2 that Phusion Passenger is waiting for the hook script `/home/phusion/badscript.sh`.
 
 ---------------------------------------------------------------------------------------------------
 Thread 'Group process spawner: /home/phusion/webapp.test#default' (0x1062d4000):
      in 'bool Passenger::runSingleHookScript(Passenger::HookScriptOptions &, const string &, const vector<pair<string, string> > &)' (Hooks.h:116) -- /home/phusion/badscript.sh
      in 'bool Passenger::runHookScripts(Passenger::HookScriptOptions &)' (Hooks.h:159)
      in 'void Passenger::ApplicationPool2::Group::spawnThreadRealMain(const SpawnerPtr &, const Passenger::ApplicationPool2::Options &, unsigned int)' (Implementation.cpp:878)
 ---------------------------------------------------------------------------------------------------
 
-Hooks may be called concurrently. For example, while the `attached_process` hook is being called, a `detached_process` hook may be called, perhaps even for the same application. It is your responsibility to ensure that your hook scripts are concurrency-safe, e.g. by employing locks and other concurrency control techniques.
+Hooks may be called concurrently, because Phusion Passenger sometimes uses multiple background threads. For example, while the `attached_process` hook is being called, a `detached_process` hook may be called, perhaps even for the same application. It is your responsibility to ensure that your hook scripts are concurrency-safe, e.g. by employing locks and other concurrency control techniques.
 
 ==== Error handling
 
 If a hook script fails -- that is, if it exits with anything other than exit code 0 -- then the error handling depends on the hook. Some hooks will abort, other hooks will ignore the error. In all cases, the result of the hook script is printed to the log.
 
@@ -494,9 +494,10 @@
 +
  - The process has crashed, and Phusion Passenger noticed it.
  - Phusion Passenger has shut down a process because it's been idle for too long.
  - The administrator configured different resource limits, and Phusion Passenger is starting or shutting down processes in response.
  - Phusion Passenger itself is shutting down.
+
 +
 Extra environment variables: `PASSENGER_PROCESS_PID`, `PASSENGER_APP_ROOT`. Errors in the hook script are ignored.
 
 `after_initialize_supergroup`::
 	Called right after Phusion Passenger has allocated data structures for an application, and is about to spawn a process for the first time for this application. Errors in the hook script are ignored. Extra environment variables: `PASSENGER_APP_ROOT`.