refactor: add drain() seam to threadHandler interface

Third step of the split suggested in #2287: land the handler-interface
extension point that later handler types (background workers) need,
without introducing any new behaviour.

Each handler gains a drain() method, called by drainWorkerThreads
right before drainChan is closed. All current implementations
(regularThread, workerThread, inactiveThread, taskThread) are no-ops,
so observable behaviour is unchanged. A later handler that needs to
wake up a thread parked in a blocking C call (e.g. by closing a stop
pipe) plugs its signal in here without modifying drainWorkerThreads
again.

- phpthread.go: interface gains drain().
- threadregular.go / threadworker.go / threadinactive.go /
  threadtasks_test.go: empty drain() on each handler.
- worker.go: drainWorkerThreads calls thread.handler.drain() right
  before close(thread.drainChan).

Full test suite and caddy module tests pass under -race.

Author: nicolas-grekas

phpthread.go

@@ -34,6 +34,12 @@ type threadHandler interface {
 	afterScriptExecution(exitStatus int)
 	context() context.Context
 	frankenPHPContext() *frankenPHPContext
+	// drain is a hook called by drainWorkerThreads right before drainChan is
+	// closed. Handlers that need to wake up a thread parked in a blocking C
+	// call (e.g. by closing a stop pipe) plug their signal in here. All
+	// current handlers are no-ops; this is the seam later handler types use
+	// without having to modify drainWorkerThreads.
+	drain()
 }
 
 func newPHPThread(threadIndex int) *phpThread {

threadinactive.go

@@ -58,3 +58,5 @@ func (handler *inactiveThread) context() context.Context {
 func (handler *inactiveThread) name() string {
 	return "Inactive PHP Thread"
 }
+
+func (handler *inactiveThread) drain() {}

threadregular.go

@@ -83,6 +83,8 @@ func (handler *regularThread) name() string {
 	return "Regular PHP Thread"
 }
 
+func (handler *regularThread) drain() {}
+
 func (handler *regularThread) waitForRequest() string {
 	// max_requests reached: restart the thread to clean up all ZTS state
 	if maxRequestsPerThread > 0 && handler.requestCount >= maxRequestsPerThread {

threadtasks_test.go

@@ -79,6 +79,8 @@ func (handler *taskThread) name() string {
 	return "Task PHP Thread"
 }
 
+func (handler *taskThread) drain() {}
+
 func (handler *taskThread) waitForTasks() {
 	for {
 		select {

threadworker.go

@@ -105,6 +105,8 @@ func (handler *workerThread) name() string {
 	return "Worker PHP Thread - " + handler.worker.fileName
 }
 
+func (handler *workerThread) drain() {}
+
 func setupWorkerScript(handler *workerThread, worker *worker) {
 	metrics.StartWorker(worker.name)
 

worker.go

@@ -189,6 +189,7 @@ func drainWorkerThreads() []*phpThread {
 				continue
 			}
 
+			thread.handler.drain()
 			close(thread.drainChan)
 			drainedThreads = append(drainedThreads, thread)