You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by ig...@apache.org on 2010/11/06 07:30:02 UTC

svn commit: r1031963 [3/13] - in /trafficserver/site/branches/ats-cms: content/docs/trunk/sdk/ templates/

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/ConceptIndex.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/ConceptIndex.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/ConceptIndex.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/ConceptIndex.en.mdtext Sat Nov  6 06:29:56 2010
@@ -1,2 +1,151 @@
+Title: Apache Traffic Server™ Software Developers Kit
+Notice:    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.
+
+[Prev](TypeIndex) - Appendix E. Type Index
+## Index
+
+### C
+
+compiling on HPUX,
+[HPUX Example](ASimplePlugin#Compiling_HPUX)
+compiling on UNIX,
+[UNIX Example](ASimplePlugin#Compiling_Unix)
+compiling plugins, examples,
+[Compile Your Plugin](ASimplePlugin#CompilingYourPlugin)
+### D
+
+deprecated functions,
+[Deprecated Functions](DeprecatedMarshBufFuncs)
+duplicate MIME fields,
+[Duplicate MIME Fields Are Not Coalesced](DuplicateMIMEFlds)
+### G
+
+global hook, [Setting a Global Hook](SettingGlobalHook)
+global HTTP hooks, [Adding Hooks](AddingHooks)
+### H
+
+`hello-world` example, [A Simple Plugin](ASimplePlugin)
+HTTP header, [MIME Headers](MIMEHeaders)
+HTTP session, [HTTP Sessions](HTTPSessions)
+HTTP transaction, [HTTP Sessions](HTTPSessions)
+### I
+
+`INKEventFunc`,
+[Accessing the Transaction Being Processed](AccessingTransactionProc)
+`INKHttpAltInfo`,
+[HTTP Alternate Selection](HTTPAlternateSelection)
+`INKHttpTxn`,
+[Accessing the Transaction Being Processed](AccessingTransactionProc),
+[HTTP Transactions](HTTP_Transactions)
+`INKMBufferCreate`, [HTTP Headers](HTTPHeaders2)
+`INKVIO`, [VIOs](HTTPTransformationPlugins#VIOs)
+`INK_HTTP_RESPONSE_TRANSFORM_HOOK`,
+[The Append-Transform Plugin](AppendTransformPlugin)
+`INK_HTTP_SSN_CLOSE_HOOK`, [HTTP Sessions](HTTPSessions)
+`INK_HTTP_SSN_START_HOOK`, [HTTP Sessions](HTTPSessions)
+`INK_LOG_MODE_ADD_TIMESTAMP`,
+[`blacklist-1.c`](App_SampleSourceCode#Sample_blacklist-1.c)
+`INT_MAX`,
+[The vconnection user's view](IOGuide#VconnectionUsersView)
+### L
+
+lock, [Mutexes](MutexGuide#Mutexes)
+### M
+
+memory leak
+in transformation plugins,
+[Transformation VConnection](Transformations_IO#TransformVconnection)
+method (HTTP),
+[About HTTP Headers](HTTPHeaders#AboutHTTPHeaders)
+MIME field,
+[About HTTP Headers](HTTPHeaders#AboutHTTPHeaders),
+[MIME Headers](MIMEHeaders)
+MIME field name, [MIME Headers](MIMEHeaders)
+MIME field value, [MIME Headers](MIMEHeaders)
+MIME fields,
+[MIME Fields Always Belong to an Associated MIME Header](MIMEFldsBelongAssocMIMEHdr)
+MIME header,
+[About HTTP Headers](HTTPHeaders#AboutHTTPHeaders),
+[MIME Headers](MIMEHeaders)
+Backus-Naur form, [MIME Headers](MIMEHeaders)
+multiple plugins,
+[Update the plugin.config File](Updatingplugin.configFile)
+mutexes, [Mutexes](MutexGuide#Mutexes)
+### N
+
+new MIME field functions,
+[MIME Fields Always Belong to an Associated MIME Header](MIMEFldsBelongAssocMIMEHdr)
+null-terminated strings,
+[No Null-Terminated Strings](GuideTSHTTPHdrSyst#NoNullTerminatedStrings)
+### P
+
+parent continuation,
+[Creating the Parent Continuation](BlacklistPlugin#CreatingParentContinuation)
+parent `INKMLoc`,
+[Release Marshal Buffer Handles](RlsMarshalBufHandles)
+parent MIME header,
+[MIME Fields Always Belong to an Associated MIME Header](MIMEFldsBelongAssocMIMEHdr)
+`plugin.config`,
+[Plugin Configuration](GetingStarted#PluginConfiguration)
+### R
+
+read VIO,
+[Writing Content Transform Plugins](HTTPTransformationPlugins#WritingContentTransformPlugins)
+releasing mbuffer handles,
+[Release Marshal Buffer Handles](RlsMarshalBufHandles)
+### S
+
+sample code
+`INKPluginRegister`,
+[Plugin Registration and Version Checking](PlusingRegisAndVersionCkg)
+version check,
+[Plugin Registration and Version Checking](PlusingRegisAndVersionCkg)
+statistics
+viewing,
+[Viewing Statistics Using Traffic Line](ViewStatsUsingTrafLine)
+### T
+
+thread locking, [Mutexes](MutexGuide#Mutexes)
+Traffic Edge,
+[Plugin Registration and Version Checking](PlusingRegisAndVersionCkg)
+Traffic Line,
+[Viewing Statistics Using Traffic Line](ViewStatsUsingTrafLine)
+Traffic Server,
+[Plugin Registration and Version Checking](PlusingRegisAndVersionCkg)
+transaction,
+[Accessing the Transaction Being Processed](AccessingTransactionProc)
+getting a handle to,
+[Accessing the Transaction Being Processed](AccessingTransactionProc)
+transaction hook,
+[Setting Up a Transaction Hook](SettingUpTransacHook)
+transformation,
+[Writing Content Transform Plugins](HTTPTransformationPlugins#WritingContentTransformPlugins)
+### V
+
+vconnection,
+[Writing Content Transform Plugins](HTTPTransformationPlugins#WritingContentTransformPlugins)
+version checking,
+[Plugin Registration and Version Checking](PlusingRegisAndVersionCkg)
+VIO,
+[Writing Content Transform Plugins](HTTPTransformationPlugins#WritingContentTransformPlugins)
+### W
+
+write VIO,
+[Writing Content Transform Plugins](HTTPTransformationPlugins#WritingContentTransformPlugins)
 
 

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/ContinuationFunctions.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/ContinuationFunctions.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/ContinuationFunctions.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/ContinuationFunctions.en.mdtext Sat Nov  6 06:29:56 2010
@@ -1,2 +1,52 @@
+Title: Apache Traffic Server™ Software Developers Kit
+Notice:    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.
+
+[Prev](INKMutexUnlock) - INKMutexUnlock
+INKContCreate - [Next](INKContCreate)
+## Continuation Functions
+
+****
+[INKContCall](ContinuationFunctions#INKContCall)
+[INKContCreate](INKContCreate)
+[INKContDataGet](INKContDataGet)
+[INKContDataSet](INKContDataSet)
+[INKContDestroy](INKContDestroy)
+[INKContMutexGet](INKContMutexGet)
+[INKContSchedule](INKContSchedule)
+### INKContCall
+
+Calls a continuation.
+
+**Prototype**
+  ~ `int INKContCall (INKCont               <em class="replaceable"><code>contp`,
+    INKEvent *`event`*, void \**`edata`*)
+
+**Description**
+  ~ Sends `<em class="replaceable"><code>event` and
+    `<em class="replaceable"><code>edata` to the
+    `<em class="replaceable"><code>contp`'s handler function. It is an
+    error to call a continuation without holding the continuation's
+    lock.
+
+**Returns**
+  ~ The values returned by the continuation `contp` event
+    handler.
+
+
 
 

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Continuations.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Continuations.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Continuations.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Continuations.en.mdtext Sat Nov  6 06:29:56 2010
@@ -1,2 +1,137 @@
+Title: Apache Traffic Server™ Software Developers Kit
+Notice:    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.
+
+[Prev](MutexGuide) - Chapter 11. Mutex Guide
+How to Activate Continuations - [Next](ActivateContinuations)
+## Chapter 12. Continuations
+
+**Table of Contents**
+
+[Mutexes and Data](Continuations#MutexesAndData)
+[How to Activate Continuations](ActivateContinuations)
+[Writing Handler Functions](WritingHandlerFunctions)
+The continuation interface is Traffic Server's basic callback
+mechanism. **Continuations** are instances of the opaque data type
+`INKCont`. In its basic form, a continuation represents a handler
+function and a mutex.
+
+This chapter covers the following topics:
+
+-   [Mutexes and Data](Continuations#MutexesAndData "Mutexes and Data")
+
+-   [How to Activate Continuations](ActivateContinuations "How to Activate Continuations")
+
+-   [Writing Handler Functions](WritingHandlerFunctions)
+
+## Mutexes and Data
+
+A continuation must be created with a mutex if your continuation
+does one of the following:
+
+-   is registered globally (`INKHttpHookAdd` or
+    `INKHttpSsnHookAdd`) to an HTTP hook and uses `INKContDataSet/Get`
+
+-   is registered locally (`INKHttpTxnHookAdd`), but for multiple
+    transactions uses `INKContDataSet/Get`
+
+-   uses `INKCacheXXX`, `INKNetXXX`, `INKHostLookup`, or
+    `INKContSchedule` APIs
+
+
+Before being activated, a caller must grab the continuation's
+mutex. This requirement makes it possible for a continuation's
+handler function to safely access its data and to prevent multiple
+callers from running it at the same time (see the
+[sample Protocol plugin](NewProtocolPlugins#AboutSampleProtocol)
+for usage). The data protected by the mutex is any global or
+continuation data associated to the continuation by
+`INKContDataSet`. This does not include the local data created by
+the continuation handler function. A typical example of
+continuations created with associated data structures and mutexes
+is the transaction state machine created in the sample Protocol
+plugin (see
+[One Way to Implement a Transaction State Machine](NewProtocolPlugins#ImplementTransStMachine "One Way to Implement a Transaction State Machine")).
+
+A reentrant call occurs when the continuation passed as an argument
+to the API can be called in the same stack trace as the function
+calling the API. For example, if you call `INKCacheRead`
+(`contp, mykey`), it is possible that `contp`'s handler will be
+called directly and then `INKCacheRead` returns.
+
+Caveats that could cause issues include the following:
+
+-   a continuation has data associated with it (`INKContDataGet`).
+
+-   the reentrant call passes itself as a continuation to the
+    reentrant API. In this case, the continuation should not try to
+    access its data after calling the reentrant API. The reason for
+    this is that data may be modified by the section of code in the
+    continuation's handler that handles the event sent by the API. It
+    is recommended that you always return after a reentrant call to
+    avoid accessing something that has been deallocated.
+
+
+Below is an example, followed by an explanation.
+
+    continuation_handler (INKCont contp, INKEvent event, void *edata) {
+       switch (event) {
+       case event1:
+          INKReentrantCall (contp);
+          /* Return right away after this call */
+          break;
+       case event2:
+          INKContDestroy (contp);
+          break;
+       }
+    }
+
+The above example first assumes that the continuation is called
+back with `event1`; it then does the first reentrant call that
+schedules the continuation to receive `event2`. Because the call is
+reentrant, the processor calls back the continuation right away
+with `event2` and the continuation is destroyed. If you try to
+access the continuation or one of its members after the reentrant
+call, then you might access something that has been deallocated. To
+avoid accessing something that has been deallocated, never access
+the continuation or any of its members after a reentrant call -
+just exit the handler.
+
+**Note:** Most HTTP transaction plugin continuations do not need
+non-null mutexes because they're called within the processing of an
+HTTP transaction, and therefore have the transaction's mutex.
+
+It is also possible to specify a continuation's mutex as `NULL`.
+This should be done only when registering a continuation to a
+global hook, by a call to `INKHttpHookAdd`. In this case, the
+continuation can be called simultaneously by different instances of
+HTTP SM running on different threads. Having a mutex here would
+slow and/or hinder Traffic Server performance, since all the
+threads will try to lock the same mutex. The drawback of not having
+a mutex is that such a continuation cannot have data associated
+with it (i.e., `INKContDataGet/Set` cannot be used).
+
+When using a `NULL` mutex it is dangerous to access the
+continuation's data, but usually continuations with `NULL` mutexes
+have no data associated with them anyway. An example of such a
+continuation is one that gets called back every time an HTTP
+request is read, and then determines from the request alone if the
+request should go through or be rejected. An HTTP transaction gives
+its continuation data to the `contp`.
+
 
 

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Conventions.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Conventions.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Conventions.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Conventions.en.mdtext Sat Nov  6 06:29:56 2010
@@ -1,2 +1,39 @@
+Title: Apache Traffic Server™ Software Developers Kit
+Notice:    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.
+
+[Prev](pr01s02) - How to Use This Book
+Chapter 1. Getting Started - [Next](GetingStarted)
+## Typographical Conventions
+
+This document uses the following typographic conventions:
+
+**Table 1. Typographical Conventions**
+
+Convention
+Purpose
+*italics* or**bold**
+Used to introduce terms.
+`monospaced face`
+Represents C language statements, commands, file content, and
+computer output.
+`<em class="replaceable"><code>monospaced               italic`
+Represents variables for which you should substitute a value.
+`...` (ellipsis)
+Indicates the omission of irrelevant or unimportant information.
 
 

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/CoupledStatistics.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/CoupledStatistics.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/CoupledStatistics.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/CoupledStatistics.en.mdtext Sat Nov  6 06:29:56 2010
@@ -1,2 +1,122 @@
+Title: Apache Traffic Server™ Software Developers Kit
+Notice:    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.
+
+[Prev](AddingStatistics) - Chapter 17. Adding Statistics
+Viewing Statistics Using Traffic Line -
+[Next](ViewStatsUsingTrafLine)
+## Coupled Statistics
+
+Use coupled statistics for quantities that are related and
+therefore must be updated jointly.
+
+As a very simple example, suppose you have three statistics: `sum`,
+`part_1`, and `part_2`. They must always preserve the relationship
+that `sum = part_1 + part_2`. If you update `part_1` without
+updating `sum` at the same time, then the equation becomes untrue.
+Therefore, the statistics are said to be *coupled*.
+
+The mechanism for updating coupled statistics jointly is to create
+local copies of global coupled statistics in the routines that
+modifiy them. When each local copy is updated appropriately, do a
+global update using `INKStatsCoupledUpdate`. To specify which
+statistics are related to one another, establish a coupled
+statistic category and make sure that each coupled statistic
+belongs to the appropriate category. When it is time to do the
+global update, specify the category to be updated.
+
+![[Note]](images/docbook/note.png)
+Note
+The local statistic copy must have a duplicate set of statistics as
+that of the master copy. Local statistics must also be added to the
+local statistic category in the same order as their master copy
+counterparts were originally added.
+
+Below are the steps you need to follow, along with a code example
+taken from the `redirect-1.c` sample plugin.
+
+### To add coupled statistics:
+
+1.  Declare the global category for your coupled statistics as a
+    global `INKCoupledStat` variable in your plugin.
+
+2.  Declare your coupled statistics as global `INKStat` variables
+    in your plugin.
+
+3.  In `INKPluginInit`, create a new global coupled category using
+    `INKStatCoupledGlobalCategoryCreate`.
+
+4.  In `INKPluginInit`, create new global coupled statistics using
+    `INKStatCoupledGlobalAdd`.
+
+    When you create a new statistic, you need to give it an "external"
+    name that the Traffic Server command line interface (Traffic Line)
+    uses to access the statistic.
+
+5.  In any routine wherein you want to modify (increment,
+    decrement, or other modification) your coupled statistics, declare
+    local copies of the coupled category and coupled statistics.
+
+6.  Create local copies using `INKStatCoupledLocalCopyCreate` and
+    `INKStatCoupledLocalAdd`.
+
+7.  Modify the local copies of your statistics. Then call
+    `INKStatsCoupledUpdate` to update the global copies jointly.
+
+8.  When you are finished, you must destroy all of the local copies
+    in the category via `INKStatCoupledLocalCopyDestroy`.
+
+
+### Example Using the redirect-1.c Sample Plugin
+
+    static INKCoupledStat request_outcomes;
+    
+    static INKStat requests_all;
+    static INKStat requests_redirects;
+    static INKStat requests_unchanged;
+    
+    request_outcomes = INKStatCoupledGlobalCategoryCreate ("request_outcomes"); 
+    
+    requests_all = INKStatCoupledGlobalAdd (request_outcomes, "requests.all", INKSTAT_TYPE_FLOAT);
+    requests_redirects = INKStatCoupledGlobalAdd (request_outcomes, "requests.redirects",
+        INKSTAT_TYPE_INT64);
+    requests_unchanged = INKStatCoupledGlobalAdd (request_outcomes, "requests.unchanged", 
+        INKSTAT_TYPE_INT64);
+    
+    INKCoupledStat local_request_outcomes;
+    INKStat local_requests_all;
+    INKStat local_requests_redirects;
+    INKStat local_requests_unchanged;
+    
+    local_request_outcomes = INKStatCoupledLocalCopyCreate("local_request_outcomes", 
+        request_outcomes); 
+    local_requests_all = INKStatCoupledLocalAdd(local_request_outcomes, "requests.all.local", 
+        INKSTAT_TYPE_FLOAT);
+    local_requests_redirects = INKStatCoupledLocalAdd(local_request_outcomes, 
+        "requests.redirects.local", INKSTAT_TYPE_INT64);
+    local_requests_unchanged = INKStatCoupledLocalAdd(local_request_outcomes, 
+        "requests.unchanged.local", INKSTAT_TYPE_INT64);
+    
+    INKStatFloatAddTo( local_requests_all, 1.0 ) ; 
+    ...
+    INKStatIncrement (local_requests_unchanged); 
+    INKStatsCoupledUpdate(local_request_outcomes); 
+    
+    INKStatCoupledLocalCopyDestroy(local_request_outcomes); 
+
 
 

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/CoupledStatsFunctions.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/CoupledStatsFunctions.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/CoupledStatsFunctions.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/CoupledStatsFunctions.en.mdtext Sat Nov  6 06:29:56 2010
@@ -1,2 +1,168 @@
+Title: Apache Traffic Server™ Software Developers Kit
+Notice:    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.
+
+[Prev](StatisticsFunctions) - Uncoupled Statistics Functions
+Logging Functions - [Next](LoggingFunctions)
+### Coupled Statistics Functions
+
+****
+-   [INKStatCoupledGlobalAdd](CoupledStatsFunctions#INKStatCoupledGlobalAdd)
+-   [INKStatCoupledGlobalCategoryCreate](CoupledStatsFunctions#INKStatCoupledGlobalCategoryCreate)
+-   [INKStatCoupledLocalAdd](CoupledStatsFunctions#INKStatCoupledLocalAdd)
+-   [INKStatCoupledLocalCopyCreate](CoupledStatsFunctions#INKStatCoupledLocalCopyCreate)
+-   [INKStatCoupledLocalCopyDestroy](CoupledStatsFunctions#INKStatCoupledLocalCopyDestroy)
+-   [INKStatsCoupledUpdate](CoupledStatsFunctions#INKStatsCoupledUpdate)
+
+#### INKStatCoupledGlobalAdd
+
+.Creates a global coupled statistic.
+
+**Prototype**
+  ~ `INKStat INKStatCoupledGlobalAdd (INKCoupledStat                 <em class="replaceable"><code>global_copy`
+    , const char \* *`the_name`* , INKStatTypes *`the_type`* )
+
+**Description**
+  ~ `<em class="replaceable"><code>global_copy` is the name of the
+    global coupled statistics category to which your new coupled
+    statistic belongs.
+
+    `<em class="replaceable"><code>the_name` is the name you use to
+    view the statistic using Traffic Line (see
+    [Viewing Statistics Using Traffic Line)](ViewStatsUsingTrafLine "Viewing Statistics Using Traffic Line").
+    There are two `INKStatTypes`: `INKSTAT_TYPE_INT64` and
+    `INKSTAT_TYPE_FLOAT` (see
+    [How to Add Coupled Statistics](CoupledStatistics#AddCoupledStats)).
+
+**Returns**
+  ~ A handle to the newly-created global coupled statistic.
+
+    `INK_ERROR_PTR` if an error occurs.
+
+
+#### INKStatCoupledGlobalCategoryCreate
+
+Creates a global coupled statistics category.
+
+**Prototype**
+  ~ `INKCoupledStat INKStatCoupledGlobalCategoryCreate                 ( const char * <em class="replaceable"><code>the_name`
+    )
+
+**Description**
+  ~ Returns a new global coupled statistics category; use this
+    function in `INKPluginInit`. The name argument is the name you use
+    to access this statistic in Traffic Line. For more information, see
+    [Viewing Statistics Using Traffic Line](ViewStatsUsingTrafLine "Viewing Statistics Using Traffic Line")
+    and
+    [How to Add Coupled Statistics](CoupledStatistics#AddCoupledStats).
+
+**Returns**
+  ~ A handle to a the newly-created global coupled statistics
+    category.
+
+    `INK_ERROR_PTR` if an error occurs.
+
+
+#### INKStatCoupledLocalAdd
+
+Creates a local copy of a global coupled statistic.
+
+**Prototype**
+  ~ `INKStat INKStatCoupledLocalAdd (INKCoupledStat                 <em class="replaceable"><code>local_copy`,
+    const char \* *`the_name`*, INKStatTypes *`the_type`* )
+
+**Description**
+  ~ `<em class="replaceable"><code>local_copy` is the name of the
+    local coupled stat category to which your new coupled stat
+    belongs.
+
+    `<em class="replaceable"><code>the_name` is the name you use to
+    view the statistic using Traffic Line (see
+    [Viewing Statistics Using Traffic Line](ViewStatsUsingTrafLine "Viewing Statistics Using Traffic Line")).
+    There are two `INKStatTypes`: `INKSTAT_TYPE_INT64` and
+    `INKSTAT_TYPE_FLOAT` (see
+    [How to Add Coupled Statistics](CoupledStatistics#AddCoupledStats)).
+
+**Returns**
+  ~ A handle to a local copy of the global coupled statistic.
+
+    `INK_ERROR_PTR` if an error occurs.
+
+
+#### INKStatCoupledLocalCopyCreate
+
+.Creates a local copy of a global coupled statistics category.
+
+**Prototype**
+  ~ `INKCoupledStat INKStatCoupledLocalCopyCreate (const char * <em class="replaceable"><code>the_name`,
+    INKCoupledStat *`global_copy`*)
+
+**Description**
+  ~ Returns a new local coupled statistics category; use this
+    function in any routine where you need to modify local copies of
+    global statistics. The name argument is the name you use to access
+    this statistic in Traffic Line. For additional information, see
+    [Viewing Statistics Using Traffic Line](ViewStatsUsingTrafLine "Viewing Statistics Using Traffic Line")
+    and
+    [How to Add Coupled Statistics](CoupledStatistics#AddCoupledStats).
+
+**Returns**
+  ~ A handle to the local copy of the global coupled statistics
+    category.
+
+    `INK_ERROR_PTR` if an error occurs.
+
+
+#### INKStatCoupledLocalCopyDestroy
+
+.Destroys a local category of statistics.
+
+**Prototype**
+  ~ `INKReturnCode INKStatCoupledLocalCopyDestroy                 (INKCoupledStat                 <em class="replaceable"><code>local_copy`)
+
+**Description**
+  ~ Destroys a local statistics category. You should always destroy
+    the local category when you are finished with it (see
+    [How to Add Coupled Statistics](CoupledStatistics#AddCoupledStats)).
+
+**Returns**
+  ~ `INK_SUCCESS` if the operation completes successfully.
+
+    `INK_ERROR` if an error occurs.
+
+
+#### INKStatsCoupledUpdate
+
+Updates a category of coupled statistics.
+
+**Prototype**
+  ~ `INKReturnCode INKStatsCoupledUpdate                 (INKCoupledStat                 <em class="replaceable"><code>local_copy`)
+
+**Description**
+  ~ Updates all of the coupled statistics belonging to the category
+    `<em class="replaceable"><code>local_copy`. For further
+    information, see
+    [How to Add Coupled Statistics](CoupledStatistics#AddCoupledStats).
+
+**Returns**
+  ~ `INK_SUCCESS` if the operation completes successfully.
+
+    `INK_ERROR` if an error occurs.
+
+
 
 

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/CreatingTSPlugins.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/CreatingTSPlugins.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/CreatingTSPlugins.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/CreatingTSPlugins.en.mdtext Sat Nov  6 06:29:56 2010
@@ -1,2 +1,228 @@
+Title: Apache Traffic Server™ Software Developers Kit
+Notice:    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.
+
+[Prev](NamingConventions) - Naming Conventions
+Roadmap for Creating Plugins - [Next](Roadmap_CreatingPlugins)
+## Chapter 2. How to Create Traffic Server Plugins
+
+**Table of Contents**
+
+-   [The Asynchronous Event Model](CreatingTSPlugins#AsynchronousEventModel)
+-   -   [HTTP Transaction](CreatingTSPlugins#HTTPTransaction_WhatIs)
+    -   [Types of Hooks](CreatingTSPlugins##TypesOfHooks)
+
+-   [Roadmap for Creating Plugins](Roadmap_CreatingPlugins)
+
+This chapter provides a foundation for designing and writing
+plugins. Reading this chapter will help you to understand:
+
+-   The asynchronous event mode. This is the design paradigm used
+    throughout Traffic Server; plugins must also follow this design. It
+    includes the callback mechanism for Traffic Server to "wake up"
+    your plugin and put it to work.
+
+-   Traffic Server's HTTP processing, with an overview of the HTTP
+    state machine.
+
+-   How plugins can hook onto and modify/extend Traffic Server's
+    HTTP processing.
+
+-   A [roadmap for writing plugins](Roadmap_CreatingPlugins),
+    with an overview of the functionality provided by the Traffic
+    Server API.
+
+
+## The Asynchronous Event Model
+
+Traffic Server is a multi-threaded process. There are two main
+reasons why a server might use multiple threads:
+
+-   To take advantage of the concurrency available with multiple
+    CPUs and multiple I/O devices.
+
+-   To manage concurrency from having many simultaneous client
+    connections. For example, a server could create one thread for each
+    connection, allowing the operating system (OS) to control switching
+    between threads.
+
+
+Traffic Server uses multiple threads for the first reason. However,
+Traffic Server does not use a separate OS thread per transaction
+because it would not be efficient when handling thousands of
+simultaneous connections.
+
+Instead, Traffic Server provides special event-driven mechanisms
+for efficiently scheduling work: the event system and
+continuations. The **event system** is used to schedule work to be
+done on threads. A **continuation** is a passive, event-driven
+state machine that can do some work until it reaches a waiting
+point; it then sleeps until it receives notification that
+conditions are right for doing more work. For example, HTTP state
+machines (which handle HTTP transactions) are implemented as
+continuations.
+
+Continuation objects are used throughout Traffic Server. Some might
+live for the duration of the Traffic Server process, while others
+are created (perhaps by other continuations) for specific needs and
+then destroyed.
+[Traffic Server Internals](CreatingTSPlugins#Fig_TSInternals "Figure 2.1. Traffic Server Internals")
+(below) shows how the major components of Traffic Server interact.
+Traffic Server has several **processors**, such as
+*cache processor* and *net processor*, that consolidate cache or
+network I/O tasks. Processors talk to the event system and schedule
+work on threads. An executing thread calls back a continuation by
+sending it an event. When a continuation receives an event, it
+wakes up, does some work, and either destroys itself or goes back
+to sleep & waits for the next event.
+
+**Figure 2.1. Traffic Server Internals**
+
+![Traffic Server Internals](images/event_sys80.jpg)
+Plugins are typically implemented as continuations. All of the
+sample code plugins (except `hello-world`) are continuations that
+are created when Traffic Server starts up; they then wait for
+events that trigger them into activity.
+
+**Figure 2.2. Traffic Server with Plugins**
+
+![Traffic Server with Plugins](images/evt_plugin120.jpg)
+A plugin may consist of just one static continuation that is called
+whenever certain events happen. Examples of such plugins include
+`blacklist-1.c`, `basic-auth.c`, and `redirect-1.c`. Alternatively,
+a plugin might dynamically create other continuations as needed.
+Transform plugins are built in this manner: a static parent
+continuation checks all transactions to see if any are
+transformable; when a transaction is transformable, the static
+continuation creates a type of continuation called a
+**vconnection**. The vconnection lives as long as it takes to
+complete the transform and then destroys itself. This design can be
+seen in all of the sample transform plugins. Plugins that support
+new protocols also have this architecture: a static continuation
+listens for incoming client connections and then creates
+transaction state machines to handle each protocol transaction.
+
+When you write plugins, there are several ways to send events to
+continuations. For HTTP plugins, there is a "hook" mechanism that
+enables the Traffic Server HTTP state machine to send your plugin
+wakeup calls when needed. Additionally, several Traffic Server API
+functions trigger Traffic Server sub-processes to send events to
+plugins: `INKContCall`, `INKVConnRead`, `INKCacheWrite`, and
+`INKMgmtUpdateRegister`, to name a few.
+
+### Traffic Server HTTP State Machine
+
+Traffic Server performs sophisticated HTTP caching and proxying.
+Important features include checking for alternates and document
+freshness, filtering, supporting cache hierarchies, and hosting.
+Traffic Server handles thousands of client requests at a time and
+each request is handled by an HTTP state machine. These machines
+follow a complex state diagram that includes all of the states
+required to support Traffic Server's features. The Traffic Server
+API provides hooks to a subset of these states, chosen for their
+relevance to plugins. You can view the API hooks and corresponding
+HTTP states in the
+[HTTP Transaction State Diagram](HTTPHooksAndTransactions#Fig_HHTTPTxStateDiag "Figure 8.1. HTTP Transaction State Diagram").
+
+The example in this section (below) explains how a plugin typically
+intervenes and extends Traffic Server's processing of an HTTP
+transaction. Complete details about hooking on to Traffic Server
+processes are provided in
+[HTTP Hooks and Transactions](HTTPHooksAndTransactions "Chapter 8. HTTP Hooks and Transactions").
+
+#### HTTP Transaction
+
+An HTTP transaction consists of a client request for a web document
+and Traffic Server's response. The response could be the requested
+web server content or it could be an error message. The content
+could come from the Traffic Server cache or Traffic Server might
+fetch it from the origin server. The following diagram shows some
+states in a typical transaction - specifically, the scenario
+wherein content is served from cache.
+
+**Figure 2.3. Simplified HTTP Transaction**
+
+![Simplified HTTP Transaction](images/transact75.jpg)
+In the diagram above, Traffic Server accepts the client connection,
+reads the request headers, looks up the origin server's IP address,
+and looks for the requested content in the cache. If the content is
+not in the cache (a "miss"), then Traffic Server opens a connection
+to the origin server and issues a request for the content. If the
+content is in the cache (a "hit"), then Traffic Server checks it
+for freshness.
+
+If the content is fresh, then Traffic Server sends a reply header
+to the client. If the content is stale, then Traffic Server opens a
+connection to the origin server and requests the content. The
+figure above,
+[Simplified HTTP Transaction](CreatingTSPlugins#Fig_HTTPTransaction "Figure 2.3. Simplified HTTP Transaction"),
+does *not* show behavior in the event of an error. If there is an
+error at a any stage, then the HTTP state machine jumps to the
+"send reply header" state and sends a reply. If the reply is an
+error, then the transaction closes. If the reply is not an error,
+then Traffic Server first sends the response content before it
+closes the transaction.
+
+**Figure 2.4. API Hooks Corresponding to States Listed in the previous [Simplified HTTP Transaction](CreatingTSPlugins#Fig_HTTPTransaction "Figure 2.3. Simplified HTTP Transaction") Diagram**
+
+![API Hooks Corresponding to States Listed in](images/transact_hook75.jpg)
+You use hooks as triggers to start your plugin. The name of a hook
+reflects the Traffic Server state that was *just completed*. For
+example, the "OS DNS lookup" hook wakes up a plugin right *after*
+the origin server DNS lookup. For a plugin that requires the IP
+address of the requested origin server, this hook is the right one
+to use. The Blacklist plugin works in this manner, as shown in the
+[Blacklist Plugin](CreatingTSPlugins#Fig_BlacklistPlugin "Figure 2.5. Blacklist Plugin")
+diagram below.
+
+**Figure 2.5. Blacklist Plugin**
+
+![Blacklist Plugin](images/blacklist75.jpg)
+Traffic Server calls the Blacklist plugin right after the origin
+server DNS lookup. The plugin checks the requested host against a
+list of blacklisted servers; if the request is allowed, then the
+transaction proceeds. If the host is forbidden, then the Blacklist
+plugin sends the transaction into an error state. When the HTTP
+state machine gets to the "send reply header" state, it then calls
+the Blacklist plugin to provide the error message that's sent to
+the client.
+
+#### Types of Hooks
+
+The Blacklist plugin's hook to the "origin server DNS lookup" state
+is a ****global hook****, meaning that the plugin is called
+*every time* there's an HTTP transaction with a DNS lookup event.
+The plugin's hook to the "send reply header" state is a
+**tr*****ansaction hook***, meaning that this hook is only invoked
+for *specified transactions* (in the Blacklist example, it's only
+used for requests to blacklisted servers). Several examples of
+setting up hooks are provided in the code example chapters:
+[Header-Based Plugin Examples](HeaderBasedPluginEx "Chapter 4. Header-Based Plugin Examples")
+and
+[HTTP Transformation Plugins](HTTPTransformationPlugins "Chapter 5. HTTP Transformation Plugins").
+
+**Header manipulation plugins**, such as filtering, basic
+authorization, or redirects, usually have a global hook to the DNS
+lookup or the read request header states. If specific actions need
+to be done to the transaction further on, then the plugin adds
+itself to a transaction hook. **Transformation plugins** require a
+**global hook**to check all transactions for transformability
+followed by a **transform hook**, which is a type of transaction
+hook used specifically for transforms.
+
 
 

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/CustInstallLicenseFunctions.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/CustInstallLicenseFunctions.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/CustInstallLicenseFunctions.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/CustInstallLicenseFunctions.en.mdtext Sat Nov  6 06:29:56 2010
@@ -1,2 +1,43 @@
+# Apache Traffic Server™ Software Developers Kit
+Notice:    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.
+
+[Prev](INKMgmtStringGet) - INKMgmtStringGet
+INKPluginDirGet - [Next](INKPluginDirGet)
+## Customer Installation and Licensing Functions
+
+****
+[INKInstallDirGet](CustInstallLicenseFunctions#INKInstallDirGet)
+[INKPluginDirGet](INKPluginDirGet)
+[INKPluginLicenseRequired](INKPluginLicenseRequired)
+### INKInstallDirGet
+
+Gets the Traffic Server install directory.
+
+**Prototype**
+  ~ `const char *INKInstallDirGet(void)`
+
+**Description**
+  ~ Gets the Traffic Server installation directory.
+
+**Returns**
+  ~ A pointer to a string containing Traffic Server's installation
+    directory.
+
+
 
 

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/DebuggingFunctions.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/DebuggingFunctions.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/DebuggingFunctions.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/DebuggingFunctions.en.mdtext Sat Nov  6 06:29:56 2010
@@ -1,2 +1,78 @@
+Title: Apache Traffic Server™ Software Developers Kit
+Notice:    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.
+
+[Prev](INKTrafficServerVersionGet) -
+INKTrafficServerVersionGet
+INKIsDebugTagSet - [Next](INKIsDebugTagSet)
+## Debugging Functions
+
+****
+-   [INKDebug](DebuggingFunctions#INKDebug)
+-   [INKIsDebugTagSet](INKIsDebugTagSet)
+-   [INKError](INKError)
+-   [INKAssert](INKAssert)
+-   [INKReleaseAssert](INKReleaseAssert)
+
+### INKDebug
+
+Issues debug statements.
+
+**Prototype**
+  ~ `void INKDebug (const char               <em class="replaceable"><code>*tag`,
+    const char *`*format_str`*, ...)
+
+**Arguments**
+  ~ `<em class="replaceable"><code>tag`*``*is the Traffic Server
+    parameter that enables Traffic Server to print out
+    *```<em class="replaceable"><code> format_str`*
+
+    `...`is a variable for `<i>format_str</i>`
+
+**Description**
+  ~ If debugging is enabled, then `INKDebug` prints out the
+    statement *`<em class="replaceable"><code>format_str`*. There are
+    two ways to enable debugging:
+
+    -   Run Traffic Server with the `-Ttag` option.   
+        For example, if the tag is
+
+            my-plugin: traffic_server -Tmy-plugin
+
+        then the debug output goes to `traffic.out`
+
+    -   Set the following variables in `records.config` (in the Traffic
+        Server `config` directory):
+
+            proxy.config.diags.debug.enabled INT 1
+            proxy.config.diags.debug.tags STRING debug-tag-name
+
+        In this case, the debug output goes to `traffic.out`
+
+
+**Example**
+  ~ `INKDebug ("my-plugin", "Starting my-plugin at %d\n",               the_time);`
+
+    The statement
+    `"Starting my-plugin at <em class="replaceable"><time></em>"`appears
+    whenever you run Traffic Server with the `my-plugin` tag:
+
+        traffic_server -Tmy-plugin
+
+
 
 

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Dep_IOBufferInterface.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Dep_IOBufferInterface.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Dep_IOBufferInterface.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Dep_IOBufferInterface.en.mdtext Sat Nov  6 06:29:56 2010
@@ -1,2 +1,114 @@
+Title: Apache Traffic Server™ Software Developers Kit
+Notice:    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.
+
+[Prev](OtherDeprecatedFunctions) - Other Deprecated Functions:
+Deprecated Statistics Fxns
+Deprecated Mutex Functions - [Next](Dep_MutexFunctions)
+### Deprecated IO Buffer Interface Functions
+
+****
+[INKIOBufferAppend](Dep_IOBufferInterface#INKIOBufferAppend)
+[INKIOBufferBlockCreate](Dep_IOBufferInterface#INKIOBufferBlockCreate)
+[INKIOBufferDataCreate](Dep_IOBufferInterface#INKIOBufferDataCreate)
+#### INKIOBufferAppend
+
+Appends to an IO buffer.
+
+**Prototype**
+  ~ `INKReturnCode INKIOBufferAppend (INKIOBuffer <span class="replaceable">bufp</span>,         INKIOBufferBlock <span class="replaceable">blockp</span>)`
+
+**Description**
+  ~ Appends a block to the IO buffer `bufp`. The data in the
+    appended block is made available for reading.
+
+**Returns**
+  ~ `INK_SUCCESS` if the block was successfully appended to the
+    specified IO buffer.
+
+    `INK_ERROR` if an error occurred.
+
+
+#### INKIOBufferBlockCreate
+
+Creates an IO buffer block.
+
+**Prototype**
+  ~ `INKIOBufferBlock INKIOBufferBlockCreate                 (INKIOBufferData <em class="replaceable"><code>datap`,
+    int *`size`*, int *`offset`*)
+
+**Description**
+  ~ Creates a new IO buffer block and initializes it with the IO
+    buffer data `<em class="replaceable"><code> datap`.
+
+  ~ The `<em class="replaceable"><code> size` parameter is the
+    amount of data initially available for reading in this new buffer
+    block.
+
+  ~ The `<em class="replaceable"><code>offset` parameter is the
+    offset into `<em class="replaceable"><code> datap` that will be
+    used as the start for the block.
+
+  ~ Two common uses for `INKIOBufferBlockCreate` are to create an
+    empty block (by specifying size as `0`) and to create a full block
+    (by specifying `<em class="replaceable"><code>size` as the total
+    size of `<em class="replaceable"><code>datap`).
+
+  ~ The newly-created block should be added almost immediately to
+    an IO buffer by a call to `INKIOBufferAppend`, since there is no
+    function for destroying a buffer block other than simply relying on
+    its automatic destruction by an IO buffer.
+
+**Returns**
+  ~ The newly-created IO buffer block.
+
+
+#### INKIOBufferDataCreate
+
+Creates IO buffer data.
+
+**Prototype**
+  ~ `INKIOBufferData INKIOBufferDataCreate (void*                 <em class="replaceable"><code>data`,
+    int *`size`*, INKIOBufferDataFlags *`flags`*)
+
+**Description**
+  ~ Creates new IO buffer data and initializes it with
+    `<em class="replaceable"><code> data`,
+    `<em class="replaceable"><code> size`. The
+    `<em class="replaceable"><code>flags` parameter specifies how to
+    interpret the data:
+
+    `<b>INK_DATA_ALLOCATE</b>`
+    The data pointer is `NULL` and the data associated with the
+    `INKIOBufferData` should be allocated. `INKIOBufferDataCreate`
+    rounds size to a power of 2 less than or equal to 32K.
+
+    `<b>INK_DATA_MALLOCED</b>`
+    The data pointer was allocated by `INKmalloc` and will be freed
+    when the last reference to the new `INKIOBufferData` is released by
+    a call to `INKfree`.
+
+    `<b>INK_DATA_CONSTANT</b>`
+    The data pointer is data that should not be freed when the last
+    reference to the new `INKIOBufferData` is released.
+
+**Returns**
+  ~ A handle to the newly-created IO buffer.
+
+
 
 

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Dep_MutexFunctions.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Dep_MutexFunctions.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Dep_MutexFunctions.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Dep_MutexFunctions.en.mdtext Sat Nov  6 06:29:56 2010
@@ -1,2 +1,65 @@
+Title: Apache Traffic Server™ Software Developers Kit
+Notice:    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.
+
+[Prev](Dep_IOBufferInterface) - Deprecated IO Buffer Interface
+Functions
+Appendix C. Troubleshooting Tips - [Next](App_Troubleshooting)
+### Deprecated Mutex Functions
+
+****
+[INKMutexTryLock](Dep_MutexFunctions#INKMutexTryLock)
+#### INKMutexTryLock
+
+Tries to lock an `INKMutex`. This API has been replaced by
+`INKMutexLockTry`.
+
+**Prototype**
+  ~ `INKReturnCode InkMutexTryLock (INKMutex                 <em class="replaceable"><code>mutex`,
+    int \**`is_mutex_lock`*)
+
+**Description**
+  ~ Tries to lock the `INKMutex` mutex.
+
+    In general, you should use `InkMutexTryLock` (or rather,
+    `INKMutexLockTry`) to obtain a mutex. See the example below.
+
+**Returns**
+  ~ If the mutex was successfully locked, then `1` is returned.
+
+    If the mutex is already locked, then `0` is returned.
+
+**Example**
+  ~     int handler (INKCont contp, INKEvent event, void *edata)
+        {
+           //This continuation tries to grab a mutex.
+           int lock = InkMutexTryLock (mutex);
+           if (!lock)
+           {
+           /* Schedule a retry; RETRY_TIME should be 10 ms or longer. */
+              INKContSchedule (contp, RETRY_TIME); 
+              return INK_EVENT_IMMEDIATE;
+           }
+        
+           // Now the mutex is grabbed.
+           do_some_job ...
+           INKMutexUnlock (mutexp);
+        }
+
+
 
 

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/DeprecatedMarshBufFuncs.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/DeprecatedMarshBufFuncs.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/DeprecatedMarshBufFuncs.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/DeprecatedMarshBufFuncs.en.mdtext Sat Nov  6 06:29:56 2010
@@ -1,2 +1,123 @@
+Title: Apache Traffic Server™ Software Developers Kit
+Notice:    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.
+
+[Prev](RlsMarshalBufHandles) - Release Marshal Buffer Handles
+Marshal Buffers - [Next](MarshalBuffers)
+### Deprecated Functions
+
+The following marshal buffer functions and MIME field functions are
+deprecated in this release; do not use them.
+
+-   `INKMBufferCompress`
+
+-   `INKMBufferDataGet`
+
+-   `INKMBufferDataSet`
+
+-   `INKMBufferLengthGet`
+
+-   `INKMBufferRef`
+
+-   `INKMBufferUnref`
+
+
+The following MIME field functions are deprecated. If you need to
+support these functions in existing code, then reference
+[Deprecated Functions](App_DeprecatedFunctions "Appendix B. Deprecated Functions").
+
+-   `INKMimeFieldCreate`
+
+-   `INKMimeFieldDestroy`
+
+-   `INKMimeFieldCopy`
+
+-   `INKMimeFieldCopyValues`
+
+-   `INKMimeFieldNext`
+
+-   `INKMimeFieldLengthGet`
+
+-   `INKMimeFieldNameGet`
+
+-   `INKMimeFieldNameSet`
+
+-   `INKMimeFieldValuesClear`
+
+-   `INKMimeFieldValuesCount`
+
+-   `INKMimeFieldValueGet`
+
+-   `INKMimeFieldValueGetInt`
+
+-   `INKMimeFieldValueGetUint`
+
+-   `INKMimeFieldValueGetDate`
+
+-   `INKMimeFieldValueSet`
+
+-   `INKMimeFieldValueSetInt`
+
+-   `INKMimeFieldValueSetUint`
+
+-   `INKMimeFieldValueSetDate`
+
+-   `INKMimeFieldValueAppend`
+
+-   `INKMimeFieldValueInsert`
+
+-   `INKMimeFieldValueInsertInt`
+
+-   `INKMimeFieldValueInsertUint`
+
+-   `INKMimeFieldValueInsertDate`
+
+-   `INKMimeFieldValueDelete`
+
+-   `INKMimeHdrFieldValueGet`
+
+-   `INKMimeHdrFieldValueGetDate`
+
+-   `INKMimeHdrFieldValueGetInt`
+
+-   `INKMimeHdrFieldValueGetUint`
+
+-   `INKMimeHdrFieldValueInsert`
+
+-   `INKMimeHdrFieldValueInsertDate`
+
+-   `INKMimeHdrFieldValueInsertInt`
+
+-   `INKMimeHdrFieldValueInsertUint`
+
+-   `INKMimeHdrFieldValueSet`
+
+-   `INKMimeHdrFieldValueSetDate`
+
+-   `INKMimeHdrFieldValueSetInt`
+
+-   `INKMimeHdrFieldValueSetUint`
+
+-   `INKMimeHdrFieldDelete`
+
+-   `INKMimeHdrFieldInsert`
+
+-   `INKMimeHdrFieldRetrieve`
+
+
 
 

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/DoACacheRemove.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/DoACacheRemove.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/DoACacheRemove.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/DoACacheRemove.en.mdtext Sat Nov  6 06:29:56 2010
@@ -1,2 +1,35 @@
+Title: Apache Traffic Server™ Software Developers Kit
+Notice:    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.
+
+[Prev](DoACacheWrite) - How to Do a Cache Write
+Errors - [Next](Errors_Cache)
+### How to Do a Cache Remove
+
+Use `INKCacheRemove` to remove items from the cache. Possible
+callback events include:
+
+-   `INK_EVENT_CACHE_REMOVE` - the item was removed. There is no
+    data payload for this event.
+
+-   `INK_EVENT_CACHE_REMOVE_FAILED` - indicates the cache was
+    unable to remove the item idetified by the cache key.
+    `INKCacheError` data indicates why the remove failed.
+
+
 
 

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/DoACacheWrite.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/DoACacheWrite.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/DoACacheWrite.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/DoACacheWrite.en.mdtext Sat Nov  6 06:29:56 2010
@@ -1,2 +1,38 @@
+Title: Apache Traffic Server™ Software Developers Kit
+Notice:    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.
+
+[Prev](CacheAPI) - Guide to the Cache API
+How to Do a Cache Remove - [Next](DoACacheRemove)
+### How to Do a Cache Write
+
+Use `INKCacheWrite` to write to a cache (see the
+[sample Protocol plugin](#NewProtocolPlugins#AboutSampleProtocol)).
+Possible callback events include:
+
+-   `INK_EVENT_CACHE_WRITE_READ` - indicates the lookup was
+    successful. The data passed back along with this event is a cache
+    vconnection that can be used to initiate a cache write.
+
+-   `INK_EVENT_CACHE_OPEN_WRITE_FAILED` - event returned when
+    another continuation is currently writing to this location in the
+    cache. Data payload for this event indicates the possible reason
+    for the write failing (`INKCacheError`).
+
+
 
 

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/DuplicateMIMEFlds.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/DuplicateMIMEFlds.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/DuplicateMIMEFlds.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/DuplicateMIMEFlds.en.mdtext Sat Nov  6 06:29:56 2010
@@ -1,2 +1,37 @@
+Title: Apache Traffic Server™ Software Developers Kit
+Notice:    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.
+
+[Prev](GuideTSHTTPHdrSyst) - Guide to Traffic Server HTTP
+Header System
+MIME Fields Always Belong to an Associated MIME Header -
+[Next](MIMEFldsBelongAssocMIMEHdr)
+### Duplicate MIME Fields Are Not Coalesced
+
+MIME headers can contain more than one MIME field with the same
+name. Earlier versions of Traffic Server joined multiple fields
+with the same name into one field with composite values. This
+behavior came at a performance cost and caused interoperability
+problems with older clients and servers. Therefore, this version of
+Traffic Server does not coalesce duplicate fields.
+
+Properly-behaving plugins should check for the presence of
+duplicate fields and then iterate over the duplicate fields via
+[`INKMimeHdrFieldNextDup`](MimeHeadersFunctions#INKMimeHdrFieldNextDup "INKMimeHdrFieldNextDup").
+
 
 

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Errors_Cache.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Errors_Cache.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Errors_Cache.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Errors_Cache.en.mdtext Sat Nov  6 06:29:56 2010
@@ -1,2 +1,36 @@
+Title: Apache Traffic Server™ Software Developers Kit
+Notice:    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.
+
+[Prev](DoACacheRemove) - How to Do a Cache Remove
+Example - [Next](CacheAPI_Example)
+### Errors
+
+Errors pertaining to the failure of various cache operations are
+indicated by `INKCacheError` (enumeration). They are as follows:
+
+-   `INK_CACHE_ERROR_NO_DOC` - the key does not match a cached
+    resource
+
+-   `INK_CACHE_ERROR_DOC_BUSY` - e.g, another continuation could be
+    writing to the cache location
+
+-   `INK_CACHE_ERROR_NOT_READY` - the cache is not ready
+
+