Au test spawning a blocking thread in a transaction hook continuation.

NOTICE

@@ -35,7 +35,7 @@ Copyright (C) 2013 GoDaddy Operating Company, LLC
 
 ~~~
 
-lib/cppapi developed by LinkedIn
+include/tscpp/api, src/tscpp/api developed by LinkedIn
 Copyright (c) 2013 LinkedIn
 
 ~~~

build/plugins.mk

@@ -25,10 +25,6 @@ TS_PLUGIN_LD_FLAGS = \
   -export-symbols-regex '^(TSRemapInit|TSRemapDone|TSRemapDoRemap|TSRemapNewInstance|TSRemapDeleteInstance|TSRemapOSResponse|TSPluginInit|TSRemapPreConfigReload|TSRemapPostConfigReload)$$'
 
 TS_PLUGIN_CPPFLAGS = \
-  -I$(abs_top_builddir)/proxy/api \
-  -I$(abs_top_srcdir)/proxy/api \
-  -I$(abs_top_srcdir)/include/cppapi/include \
-  -I$(abs_top_builddir)/lib/cppapi/include \
   -I$(abs_top_srcdir)/include \
   -I$(abs_top_srcdir)/lib
 

doc/developer-guide/api/functions/TSHttpHookAdd.en.rst

@@ -44,26 +44,34 @@ function for callback amounts to adding the function to a hook. You
 can register your plugin to be called back for every single
 transaction, or for specific transactions only.
 
-HTTP :term:`transaction` hooks are set on a global basis using the function
-:func:`TSHttpHookAdd`. This means that the continuation specified
-as the parameter to :func:`TSHttpHookAdd` is called for every
-transaction. :func:`TSHttpHookAdd` must only be called from
-:func:`TSPluginInit` or :func:`TSRemapInit`.
+HTTP :term:`transaction` and :term:`session` hooks are set on a
+global basis using the function :func:`TSHttpHookAdd`. This means
+that the continuation specified as the parameter to :func:`TSHttpHookAdd`
+is called for every transaction. :func:`TSHttpHookAdd` must only be called from
+:func:`TSPluginInit` or :func:`TSRemapInit`.  Continuations set on a
+global hook will run before any continuations set on the session/transaction
+hook with the same hook ID.
 
 :func:`TSHttpSsnHookAdd` adds :arg:`contp` to
 the end of the list of HTTP :term:`session` hooks specified by :arg:`id`.
 This means that :arg:`contp` is called back for every transaction
 within the session, at the point specified by the hook ID. Since
 :arg:`contp` is added to a session, it is not possible to call
 :func:`TSHttpSsnHookAdd` from the plugin initialization routine;
-the plugin needs a handle to an HTTP session.
+the plugin needs a handle to an HTTP session.  Continuations set on a
+session hook will run before any continuations set on the transaction
+hook with the same hook ID.  This fucnction can be called from handler
+functions of continuations on a global per-session hook, including for
+the session hook with the same ID.
 
 :func:`TSHttpTxnHookAdd` adds :arg:`contp`
 to the end of the list of HTTP transaction hooks specified by
 :arg:`id`. Since :arg:`contp` is added to a transaction, it is
 not possible to call :func:`TSHttpTxnHookAdd` from the plugin
 initialization routine but only when the plugin has a handle to an
-HTTP transaction.
+HTTP transaction.  This fucnction can be called from handler
+functions of continuations on a global or session per-transaction
+hook, including the for transaction hook with the same ID.
 
 A single continuation can be attached to multiple hooks at the same time.
 It is good practice to conserve resources by reusing hooks in this way

doc/developer-guide/api/functions/TSMutexLock.en.rst

@@ -32,3 +32,6 @@ Synopsis
 
 Description
 ===========
+
+Locks the mutex (recursively).  Should only be called from a continuation
+handler function or a :type:`TSThread` function.

doc/developer-guide/api/functions/TSMutexUnlock.en.rst

@@ -32,3 +32,9 @@ Synopsis
 
 Description
 ===========
+
+Decrements the recursive lock count.  If the count thus becomes zero, unlocks
+the mutex.  This should only be called within the continuation handler function or
+:type:`TSThread` function that locked the mutex.  Can also be called within
+the continuation handler for the continuation's mutex.  (This is normally done
+before the continution handler destroys the continuation running it.)

doc/developer-guide/plugins/continuations/writing-handler-functions.en.rst

@@ -140,3 +140,10 @@ The continuation functions are listed below:
 -  :func:`TSContSchedule`
 -  :func:`TSContScheduleOnPool`
 -  :func:`TSContScheduleOnThread`
+
+When a handler function blocks, it blocks the event thread running it.  This blocks all the continuations (internal ones
+along with those of plugins) in the event thread's queue.  This may increase the worst-case latency for HTTP request
+processing.  If there is enough blocking, this could increase CPU idle time, which may reduce proxy throughput.  The
+Au test **polite_hook_wait** illustrates a method for using dynamic threading to do a blocking call without blocking
+any handler function.  But the overhead of this method may cancel out the performance improvement, if blocking times
+are short.

plugins/experimental/fastcgi/src/Readme

@@ -32,7 +32,6 @@ tsxs -o ats_fastcgi.so \
      -c ats_fastcgi.cc \
      -L "${ats_dir}lib/" \
      -I "${ats_dir}lib" \
-     -I "${ats_dir}lib/cppapi/include/" \
      -c ats_fcgi_client.cc \
      -latscppapi
 

tests/Makefile.am

@@ -33,6 +33,7 @@ AM_LDFLAGS += -rpath $(abs_builddir)
 include gold_tests/bigobj/Makefile.inc
 include gold_tests/continuations/plugins/Makefile.inc
 include gold_tests/chunked_encoding/Makefile.inc
+include gold_tests/pluginTest/polite_hook_wait/Makefile.inc
 include gold_tests/pluginTest/tsapi/Makefile.inc
 include gold_tests/timeout/Makefile.inc
 include gold_tests/tls/Makefile.inc

tests/gold_tests/pluginTest/polite_hook_wait/Makefile.inc

@@ -0,0 +1,18 @@
+#  Licensed to the Apache Software Foundation (ASF) under one
+#  or more contributor license agreements.  See the NOTICE file
+#  distributed with this work for additional information
+#  regarding copyright ownership.  The ASF licenses this file
+#  to you under the Apache License, Version 2.0 (the
+#  "License"); you may not use this file except in compliance
+#  with the License.  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+noinst_LTLIBRARIES += gold_tests/pluginTest/polite_hook_wait/polite_hook_wait.la
+gold_tests_pluginTest_polite_hook_wait_polite_hook_wait_la_SOURCES = gold_tests/pluginTest/polite_hook_wait/polite_hook_wait.cc

tests/gold_tests/pluginTest/polite_hook_wait/curl.gold

@@ -0,0 +1,2 @@
+> GET / HTTP/1.1
+< HTTP/1.1 403 Forbidden