CONFIGURATION.md in pitchfork-0.2.0

- old
+ new

@@ -236,24 +236,31 @@
 application that are used in hooks.
 
 `pitchfork` also don't attempt to rescue hook errors. Raising from a worker hook will crash the worker,
 and raising from a master hook will bring the whole cluster down.
 
-### `before_fork`
+### `after_promotion`
 
 ```ruby
-before_fork do |server, worker|
+after_promotion do |server, mold|
   Database.disconnect!
 end
 ```
 
-Called in the context of the parent or mold.
+Called in the context of the mold when initially spawned or promotted.
+
+It's usage is similar to a `before_fork` callback found on other servers
+but it is called once on promotion rather than before forking each worker.
+
 For most protocols connections can be closed after fork, but some
 stateful protocols require to close connections before fork.
 
 That is the case for instance of many SQL databases protocols.
 
+This is also the callback in which memory optimizations, such as
+heap compaction should be done.
+
 ### `after_fork`
 
 ```ruby
 after_fork do |server, worker|
   NetworkClient.disconnect!
@@ -261,11 +268,24 @@
 ```
 
 Called in the worker after forking. Generally used to close inherited connections
 or to restart backgrounds threads for libraries that don't do it automatically.
 
+### `after_promotion`
 
+```ruby
+after_promotion do |server, mold|
+  NetworkClient.disconnect!
+  4.times { GC.start } # promote surviving objects to oldgen
+  GC.compact
+end
+```
+
+Called in the worker after it was promoted into a mold. Generally used to shutdown
+open connections and file descriptors, as well as to perform memory optimiations
+such as compacting the heap, trimming memory etc.
+
 ### `after_worker_ready`
 
 Called by a worker process after it has been fully loaded, directly before it
 starts responding to requests:
 
@@ -300,50 +320,28 @@
 The limit is per-worker, for instance with `refork_after [50]` a refork is triggered
 once at least one worker processed `50` requests.
 
 Each element is a limit for the next generation. On the example above a new generation
 is triggered when a worker has processed 50 requests, then the second generation when
-a worker from the new generation processed an additional 100 requests and finally after another
+a worker from the new generation processed an additional 100 requests and finally after *every*
 1000 requests.
 
+If you don't want unlimited reforking, you can set `false` as the last element of the array:
+
+```ruby
+refork_after [50, 100, 1000, false]
+```
+
 Generally speaking Copy-on-Write efficiency tend to degrade fast during the early requests,
 and then less and less frequently.
 
 As such you likely want to refork exponentially less and less over time.
 
 By default automatic reforking isn't enabled.
 
 Make sure to read the [fork safety guide](FORK_SAFETY.md) before enabling reforking.
 
-### `mold_selector`
-
-Sets the mold selector implementation.
-
-```ruby
-mold_selector do |server|
-  candidate = server.children.workers.sample # return an random worker
-  server.logger.info("worker=#{worker.nr} pid=#{worker.pid} selected as new mold")
-  candidate
-end
-```
-
-The has access to `server.children` a `Pitchfork::Children` instance.
-This object can be used to introspect the state of the cluster and select the most
-appropriate worker to be used as the new mold from which workers will be reforked.
-
-The default implementation selects the worker with the least
-amount of shared memory. This heuristic aim to select the most
-warmed up worker.
-
-This should be considered a very advanced API and it is discouraged
-to use it unless you are confident you have a clear understanding
-of pitchfork's architecture.
-
 ## Rack Features
-
-### `default_middleware`
-
-Sets whether to add Pitchfork's default middlewares. Defaults to `true`.
 
 ### `early_hints`
 
 Sets whether to enable the proposed early hints Rack API. Defaults to `false`.
 