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**
+
+
+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**
+
+
+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**
+
+
+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**
+
+
+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**
+
+
+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
+
+