trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From a..@apache.org
Subject git commit: Doc: Add lifecycle hook documentation.
Date Thu, 29 Aug 2013 14:49:41 GMT
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 <amc@network-geographics.com>
Authored: Thu Aug 29 09:49:21 2013 -0500
Committer: Alan M. Carroll <amc@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


Mime
View raw message