You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by am...@apache.org on 2013/08/29 16:49:41 UTC
git commit: Doc: Add lifecycle hook documentation.
Updated Branches:
refs/heads/master 9d2acd0a5 -> dc4dfdf1b
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/master
Commit: dc4dfdf1bad2ae535a100b118ae772a33606df22
Parents: 9d2acd0
Author: Alan M. Carroll <am...@network-geographics.com>
Authored: Thu Aug 29 09:49:21 2013 -0500
Committer: Alan M. Carroll <am...@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