Doc: Add lifecycle hook documentation.
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/dc4dfdf1 Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/dc4dfdf1 Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/dc4dfdf1 Branch: refs/heads/5.0.x Commit: dc4dfdf1bad2ae535a100b118ae772a33606df22 Parents: 9d2acd0 Author: Alan M. Carroll <a...@network-geographics.com> Authored: Thu Aug 29 09:49:21 2013 -0500 Committer: Alan M. Carroll <a...@network-geographics.com> Committed: Thu Aug 29 09:49:21 2013 -0500 ---------------------------------------------------------------------- doc/glossary.en.rst | 6 +- doc/reference/api/TSHttpHookAdd.en.rst | 16 ++-- doc/reference/api/TSLifecycleHookAdd.en.rst | 103 +++++++++++++++++++++++ doc/reference/api/TSTypes.en.rst | 4 + doc/reference/api/index.en.rst | 29 ++++--- 5 files changed, 131 insertions(+), 27 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/trafficserver/blob/dc4dfdf1/doc/glossary.en.rst ---------------------------------------------------------------------- diff --git a/doc/glossary.en.rst b/doc/glossary.en.rst index 76accf9..e477540 100644 --- a/doc/glossary.en.rst +++ b/doc/glossary.en.rst @@ -30,10 +30,12 @@ Glossary suspended processing. This can be considered similar to co-routines. session - A single connection from a client to Traffic Server, covering all requests and responses on that connection. + A single connection from a client to Traffic Server, covering all requests and responses on that connection. A + session starts when the client connection opens, and ends when the connection closes. transaction - A client request and response, either from the origin server or from the cache. + A client request and response, either from the origin server or from the cache. A transaction begins when Traffic + Server receives a request, and ends when Traffic Server sends the response. cache volume Persistent storage for the cache, defined and manipulable by the user. http://git-wip-us.apache.org/repos/asf/trafficserver/blob/dc4dfdf1/doc/reference/api/TSHttpHookAdd.en.rst ---------------------------------------------------------------------- diff --git a/doc/reference/api/TSHttpHookAdd.en.rst b/doc/reference/api/TSHttpHookAdd.en.rst index 1c4fa08..eebcb21 100644 --- a/doc/reference/api/TSHttpHookAdd.en.rst +++ b/doc/reference/api/TSHttpHookAdd.en.rst @@ -38,27 +38,21 @@ 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 transaction hooks are set on a global basis using the function +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` is typically called from :func:`TSPluginInit` or :func:`TSRemapInit`. -A session consists of a single client connection to Traffic Server. -A session can consist of several transactions in succession. The -session starts when the client connection opens, and ends when the -connection closes. :func:`TSHttpSsnHookAdd` adds :arg:`contp` to -the end of the list of HTTP transaction hooks specified by :arg:`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. -A transaction consists of a single HTTP request from a client and -the response that Traffic Server sends to that client. A transaction -begins when Traffic Server receives a request, and ends when Traffic -Server sends the response. :func:`TSHttpTxnHookAdd` adds :arg:`contp` +: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 @@ -114,4 +108,4 @@ transaction hooks:: See also ======== -:manpage:`TSAPI(3ts)`, :manpage:`TSContCreate(3ts)` +:manpage:`TSAPI(3ts)`, :manpage:`TSContCreate(3ts)`, :manpage:`TSLifecycleHookAdd(3ts)` http://git-wip-us.apache.org/repos/asf/trafficserver/blob/dc4dfdf1/doc/reference/api/TSLifecycleHookAdd.en.rst ---------------------------------------------------------------------- diff --git a/doc/reference/api/TSLifecycleHookAdd.en.rst b/doc/reference/api/TSLifecycleHookAdd.en.rst new file mode 100644 index 0000000..31dc461 --- /dev/null +++ b/doc/reference/api/TSLifecycleHookAdd.en.rst @@ -0,0 +1,103 @@ +.. 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. + +.. default-domain:: c + +.. _ts-lifecycle-hook-add: + +================== +TSLifecycleHookAdd +================== + +Synopsis +======== +`#include <ts/ts.h>` + +.. function:: void TSLifecycleHookAdd(TSLifecycleHookID id, TSCont contp) + +Description +=========== + +:func:`TSLifecycleHookAdd` adds :arg:`contp` to the list of lifecycle hooks specified by :arg:`id`. Lifecycle hooks are +based on the Traffic Server process, not on any specific transaction or session. These will typically be called only +once during the execution of the Traffic Server process and therefore should be added in :func:`TSPluginInit` (which could itself be considered a lifecyle hook). Unlike other hooks, lifecycle hooks may not have a well defined ordering and use of them should not assume that one of the hooks is always called before another unless specifically mentioned. + +These were introduced to solve process initialization ordering issues (TS-1487). Different API calls required different +modules of Traffic Server to be initialized and all of them had to be called from :func:`TSPluginInit`. The solution was +to move :func:`TSPluginInit` as early as possible in the process initialization and provide hooks for API calls that +needed to be invoked later. + +`TS_LIFECYCLE_PORTS_INITIALIZED_HOOK` + Called after the :ts:cv:`proxy server port <proxy.config.http.server_ports>` data structures have been initialized + but before connections are accepted on those ports. The sockets corresponding to the ports may or may not be open + depending on how the `traffic_server` process was invoked. Other API functions that depend on server ports should be + called from this hook and not :func:`TSPluginInit`. + + Invoked with the event `TS_EVENT_LIFECYCLE_PORTS_INITIALIZED` and `NULL` data. + +`TS_LIFECYCLE_PORTS_READY_HOOK` + Called after enabling connections on the proxy server ports. Because Traffic Server is threaded this may or may not + be called before any connections are accepted. The hook code may assume that any connection to Traffic Server started + after this hook is called will be accepted by Traffic Server, making this a convenient place to signal external + processes of that. + + Invoked with the event `TS_EVENT_LIFECYCLE_PORTS_READY` and `NULL` data. + +`TS_LIFECYCLE_CACHE_READY_HOOK` + Called after Traffic Server cache initialization has finished. + + Invoked with the event `TS_EVENT_LIFECYCLE_CACHE_READY` and `NULL` data. + +Ordering +======== + +`TS_LIFECYCLE_PORTS_INITIALIZED_HOOK` will always be called before `TS_LIFECYCLE_PORTS_READY_HOOK`. + +Examples +======== + +The following example demonstrates how to correctly use :func:`TSNetAcceptNamedProtocol`, which does not work if called +from :func:`TSPluginInit` directly. :: + + #include <ts/ts.h> + + #define SSL_PROTOCOL_NAME "blah blah" + + static int + ssl_proto_handler(TSCont contp, TSEvent event, void* data) + { + /// Do named protocol handling. + } + + static int + local_ssl_init(TSCont contp, TSEvent event, void *edata) + { + if (TS_EVENT_LIFECYCLE_PORTS_INITIALIZED) { // just to be safe. + TSNetAcceptNamedProtocol(TSContCreate(ssl_proto_handler, NULL), SSL_PROTOCOL_NAME); + } + return 0; + } + + void + TSPluginInit (int argc, const char *argv[]) + { + TSLifecycleHookAdd(TS_LIFECYCLE_PORTS_INITIALIZED_HOOK, TSContCreate(local_ssl_init, NULL)); + } + +See also +======== +:manpage:`TSAPI(3ts)`, :manpage:`TSContCreate(3ts)` http://git-wip-us.apache.org/repos/asf/trafficserver/blob/dc4dfdf1/doc/reference/api/TSTypes.en.rst ---------------------------------------------------------------------- diff --git a/doc/reference/api/TSTypes.en.rst b/doc/reference/api/TSTypes.en.rst index adc8b38..e24d603 100644 --- a/doc/reference/api/TSTypes.en.rst +++ b/doc/reference/api/TSTypes.en.rst @@ -52,6 +52,10 @@ The Apache Traffic Server API provides large number of types. An opaque type that represents a Traffic Server HTTP :term:`transaction`. +.. type:: TSLifecycleHookID + + An enumeration that identifies a :ref:`life cycle hook <ts-lifecycle-hook-add>`. + .. type:: TSReturnCode An indicator of the results of an API call. A value of :const:`TS_SUCCESS` means the call was successful. Any other value http://git-wip-us.apache.org/repos/asf/trafficserver/blob/dc4dfdf1/doc/reference/api/index.en.rst ---------------------------------------------------------------------- diff --git a/doc/reference/api/index.en.rst b/doc/reference/api/index.en.rst index 77c02be..b1fa32f 100644 --- a/doc/reference/api/index.en.rst +++ b/doc/reference/api/index.en.rst @@ -21,17 +21,18 @@ API Reference .. toctree:: :maxdepth: 2 - TSAPI.en.rst - TSDebug.en.rst - TSHttpHookAdd.en.rst - TSHttpParserCreate.en.rst - TSHttpTxnMilestoneGet.en.rst - TSIOBufferCreate.en.rst - TSInstallDirGet.en.rst - TSMBufferCreate.en.rst - TSPluginInit.en.rst - TSRemap.en.rst - TSTrafficServerVersionGet.en.rst - TSUrlCreate.en.rst - TSmalloc.en.rst - TSTypes.en.rst + TSAPI.en + TSDebug.en + TSHttpHookAdd.en + TSHttpParserCreate.en + TSHttpTxnMilestoneGet.en + TSIOBufferCreate.en + TSInstallDirGet.en + TSMBufferCreate.en + TSPluginInit.en + TSRemap.en + TSTrafficServerVersionGet.en + TSUrlCreate.en + TSLifecycleHookAdd.en + TSmalloc.en + TSTypes.en