trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From iga...@apache.org
Subject svn commit: r1068228 - in /trafficserver/site/branches/ats-cms/content/docs/trunk: ./ sdk/actions-guide/ sdk/continuations/ sdk/plugin-configurations/
Date Tue, 08 Feb 2011 00:01:04 GMT
Author: igalic
Date: Tue Feb  8 00:01:04 2011
New Revision: 1068228

URL: http://svn.apache.org/viewvc?rev=1068228&view=rev
Log:
"Translated" two more chapters to Markdown.

Modified:
    trafficserver/site/branches/ats-cms/content/docs/trunk/STATUS
    trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/actions-guide/hosts-lookup-api.en.mdtext
    trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/actions-guide/index.en.mdtext
    trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/continuations/how-to-activate-continuations.en.mdtext
    trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/continuations/index.en.mdtext
    trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/continuations/writing-handler-functions.en.mdtext
    trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/plugin-configurations/index.en.mdtext

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/STATUS
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/STATUS?rev=1068228&r1=1068227&r2=1068228&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/STATUS (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/STATUS Tue Feb  8 00:01:04 2011
@@ -61,8 +61,8 @@ http-hooks-and-transactions -- igalic
 misc-interface-guide -- igalic
 http-headers  -- igalic
 mutex-guide  -- igalic
-continuations
-plugin-configurations
+continuations -- igalic
+plugin-configurations -- igalic
 actions-guide
 io-guide
 plugin-management

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/actions-guide/hosts-lookup-api.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/actions-guide/hosts-lookup-api.en.mdtext?rev=1068228&r1=1068227&r2=1068228&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/actions-guide/hosts-lookup-api.en.mdtext
(original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/actions-guide/hosts-lookup-api.en.mdtext
Tue Feb  8 00:01:04 2011
@@ -0,0 +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](../actions-guide) - Actions Guide
+
+IO Guide - [Next](../io-guide)
+
+## Hosts Lookup API ## {#HostsLookupAPI}
+
+The hosts lookup enables plugins to ask Traffic Server to do a host lookup 
+of a host name, much like a DNS lookup.
+
+The hosts lookup functions are as follows:
+
+* [`TSHostLookup`](link/to/doxygen)
+* [`TSHostLookupResultIPGet`](link/to/doxygen)
+
+
+

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/actions-guide/index.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/actions-guide/index.en.mdtext?rev=1068228&r1=1068227&r2=1068228&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/actions-guide/index.en.mdtext
(original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/actions-guide/index.en.mdtext
Tue Feb  8 00:01:04 2011
@@ -0,0 +1,177 @@
+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
+
+[Prev](../plugin-configurations) - Plugin Configurations
+
+Hosts Lookup API - [Next](hosts-lookup-api)
+
+##  Actions Guide ## {#ActionsGuide}
+
+**Table of Contents**
+
+* [Actions](#Actions)
+* [Hosts Lookup API](hosts-lookup-api)
+
+## Actions ## {#Actions}
+
+An **action** is a handle to an operation initiated by a plugin that has not 
+yet completed. For example: when a plugin connects to a remote server, it uses 
+the call `TSNetConnect` - which takes `TSCont` as an argument to call back 
+when the connection is established. `TSNetConnect` might not call the continuation 
+back immediately and will return an `TSAction` structure that the caller can 
+use to cancel the operation. Cancelling the operation does not necessarily 
+mean that the operation will not occur; it simply means that the continuation 
+passed into the operation will not be called back. In such an example, the 
+connection might still occur if the action is cancelled; however, the continuation 
+that initiated the connection would not be called back.
+
+In the preceding example, it is also possible that the connection will complete 
+and call back the continuation before `TSNetConnect` returns. If that occurs, 
+then `TSNetConnect` returns a special action that causes `TSActionDone` to 
+return `1`. This specifies that the operation has already completed, so it's 
+pointless to try to cancel the operation. Also note that an action will never 
+change from non-completed to completed. When the operation actually succeeds 
+and the continuation is called back, the continuation must zero out its action 
+pointer to indicate to itself that the operation succeeded.
+
+The asynchronous nature of all operations in Traffic Server necessitates actions. 
+You should notice from the above discussion that once a call to a function 
+like `TSNetConnect` is made by a continuation and that function returns a 
+valid action (`TSActionDone` returns `0`), it is not safe for the continuation 
+to do anything else except return from its handler function. It is not safe 
+to modify or examine the continuation's data because the continuation may have 
+already been destroyed.
+
+Below is an example of typical usage for an action:
+
+        ::::c
+        #include <ts/ts.h>
+        static int
+        handler (TSCont contp, TSEvent event, void *edata)
+        {
+        	if (event == TS_EVENT_IMMEDIATE) {
+        		TSAction actionp = TSNetConnect (contp, 127.0.0.1, 9999);
+        		if (!TSActionDone (actionp)) {
+        			TSContDataSet (contp, actionp);
+        		} else {
+        			/* We've already been called back... */
+        			return 0;
+        		}
+        	} else if (event == TS_EVENT_NET_CONNECT) {
+        		/* Net connection succeeded */
+        		TSContDataSet (contp, NULL);
+        		return 0;
+        	} else if (event == TS_EVENT_NET_CONNECT_FAILED) {
+        		/* Net connection failed */
+        		TSContDataSet (contp, NULL);
+        		return 0;
+        	} 
+        	return 0;
+        }
+
+       	void
+        TSPluginInit (int argc, const char *argv[])
+        {
+        	TSCont contp;
+
+        	contp = TSContCreate (handler, TSMutexCreate ());
+
+        	/* We don't want to call things out of TSPluginInit
+        	   directly since it's called before the rest of the
+        	   system is initialized. We'll simply schedule an event
+        	   on the continuation to occur as soon as the rest of
+        	   the system is started up. */
+        	TSContSchedule (contp, 0);
+        }
+
+
+The example above shows a simple plugin that creates a continuation and then 
+schedules it to be called immediately. When the plugin's handler function is 
+called the first time, the event is `TS_EVENT_IMMEDIATE`. The plugin then 
+tries to open a net connection to port 9999 on `localhost` (127.0.0.1). The 
+IP description was left in cider notation to further clarify what is going 
+on; also note that the above won't actually compile until the IP address is 
+modified. The action returned from `TSNetConnect` is examined by the plugin. 
+If the operation has not completed, then the plugin stores the action in its 
+continuation. Otherwise, the plugin knows it has already been called back and 
+there is no reason to store the action pointer.
+
+A final question might be, "why would a plugin want to cancel an action?" In 
+the above example, a valid reason could be to place a limit on the length of 
+time it takes to open a connection. The plugin could schedule itself to get 
+called back in 30 seconds and then initiate the net connection. If the timeout 
+expires first, then the plugin would cancel the action. The following sample 
+code implements this:
+
+        :::::c
+        #include <ts/ts.h>
+        static int
+        handler (TSCont contp, TSEvent event, void *edata)
+        {
+        	switch (event) {
+        		case (TS_EVENT_IMMEDIATE):
+        			TSContSchedule (contp, 30000);
+        			TSAction actionp = TSNetConnect(contp, 127.0.0.1, 9999);
+        			if (!TSActionDone (actionp)) {
+        				TSContDataSet (contp, actionp);
+        			} else {
+        				/* We've already been called back ... */
+        			}
+        			break;
+
+        		case (TS_EVENT_TIMEOUT):
+        			TSAction actionp = TSContDataGet (contp);
+        			if (!TSActionDone(actionp)) {
+        				TSActionCancel (actionp);
+        			}
+        			break;
+
+        		case (TS_EVENT_NET_CONNECT):
+        			/* Net connection succeeded */
+        			TSContDataSet (contp, NULL);
+        			break;
+
+        		case (TS_EVENT_NET_CONNECT_FAILED):
+        			/* Net connection failed */
+        			TSContDataSet (contp, NULL);
+        			break;
+
+        	} 
+        	return 0;
+        }
+
+      	void
+        TSPluginInit (int argc, const char *argv[])
+        {
+        	TSCont contp;
+
+        	contp = TSContCreate (handler, TSMutexCreate ());
+        	/* We don't want to call things out of TSPluginInit
+        	   directly since it's called before the rest of the
+        	   system is initialized. We'll simply schedule an event
+        	   on the continuation to occur as soon as the rest of
+        	   the system is started up. */
+        	TSContSchedule (contp, 0);
+        }
+
+The action functions are:
+
+* [`TSActionCancel`](link/to/doxygen)
+* [`TSActionDone`](link/to/doxygen)
+
+
+

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/continuations/how-to-activate-continuations.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/continuations/how-to-activate-continuations.en.mdtext?rev=1068228&r1=1068227&r2=1068228&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/continuations/how-to-activate-continuations.en.mdtext
(original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/continuations/how-to-activate-continuations.en.mdtext
Tue Feb  8 00:01:04 2011
@@ -0,0 +1,41 @@
+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](../continuations) - Continuations
+
+Writing Handler Functions - [Next](writing-handler-functions)
+
+## How to Activate Continuations ## {#HowActivateContinuations}
+
+Continuations are activated when they receive an event or by `TSContSchedule` 
+(which schedules a continuation to receive an event). Continuations might receive 
+an event because:
+
+* Your plugin calls `TSContCall`
+
+* The Traffic Server HTTP state machine sends an event corresponding to a particular 
+HTTP hook
+
+* A Traffic Server IO processor (such as a cache processor or net processor) 
+is letting a continuation know there is data (cache or network) available to 
+read or write. These callbacks are a result of using functions such `TSVConnRead`/`Write`

+or `TSCacheRead`/`Write`
+
+
+

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/continuations/index.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/continuations/index.en.mdtext?rev=1068228&r1=1068227&r2=1068228&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/continuations/index.en.mdtext
(original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/continuations/index.en.mdtext
Tue Feb  8 00:01:04 2011
@@ -0,0 +1,129 @@
+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](../mutex-guide) - Mutex Guide
+
+How to Activate Continuations - [Next](how-to-activate-continuations)
+
+##  Continuations ## {#Continuations}
+
+**Table of Contents**
+
+[Mutexes and Data](#MutexesData)
+[How to Activate Continuations](how-to-activate-continuations)
+[Writing Handler Functions](writing-handler-functions)
+
+The continuation interface is Traffic Server's basic callback mechanism. **Continuations**

+are instances of the opaque data type `TSCont`. In its basic form, a continuation 
+represents a handler function and a mutex. 
+
+This chapter covers the following topics:
+
+* [Mutexes and Data](MutexesData)
+
+* [How to Activate Continuations](ActivateContinuations.html)
+
+* [Writing Handler Functions](WritingHandlerFunctions.html)
+
+## Mutexes and Data ## {#MutexesData}
+
+A continuation must be created with a mutex if your continuation does one of 
+the following:
+
+* is registered globally (`TSHttpHookAdd` or `TSHttpSsnHookAdd`) to an HTTP 
+hook and uses `TSContDataSet/Get`
+
+* is registered locally (`TSHttpTxnHookAdd`), but for multiple transactions 
+uses `TSContDataSet/Get`
+
+* uses `TSCacheXXX`, `TSNetXXX`, `TSHostLookup`, or `TSContSchedule` 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](../new-protocol-plugins#AboutSampleProtocol) for 
+usage). The data protected by the mutex is any global or continuation data 
+associated to the continuation by `TSContDataSet`. 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](../new-protocol-plugins#OneWayImplementaTransactionStateMachine)).

+
+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 `TSCacheRead` (`contp, mykey`), it is possible that 
+`contp`'s handler will be called directly and then `TSCacheRead` returns. 
+ 
+
+Caveats that could cause issues include the following:
+
+* a continuation has data associated with it (`TSContDataGet`).
+
+*   
+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.
+
+        ::::c
+	continuation_handler (TSCont contp, TSEvent event, void *edata) {
+		switch (event) {
+			case event1:
+				TSReentrantCall (contp);
+				/* Return right away after this call */
+				break;
+			case event2:
+				TSContDestroy (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 
+`TSHttpHookAdd`. 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., `TSContDataGet/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/continuations/writing-handler-functions.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/continuations/writing-handler-functions.en.mdtext?rev=1068228&r1=1068227&r2=1068228&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/continuations/writing-handler-functions.en.mdtext
(original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/continuations/writing-handler-functions.en.mdtext
Tue Feb  8 00:01:04 2011
@@ -0,0 +1,242 @@
+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](how-to-activate-continuations) - How to Activate Continuations
+
+Chapter 13. Plugin Configurations - [Next](../plugin-configurations)
+
+## Writing Handler Functions ## {#WritingHandlerFunctions}
+
+The handler function is the key component of a continuation. It is supposed 
+to examine the event and event data, and then do something appropriate. The 
+probable action might be to schedule another event for the continuation to 
+received, to open up a connection to a server, or simply to destroy itself. 
+
+The continuation's handler function is a function of type `TSEventFunc`. Its 
+arguments are a continuation, an event, and a pointer to some data (this data 
+is passed to the continuation by the caller - do not confuse this data with 
+the continuation's own data, associated by `TSContDataSet`). When the continuation 
+is called back, the continuation and an event are passed to the handler function. 
+The continuation is a handle to the same continuation that is invoked. The 
+handler function typically has a switch statement to handle the events it receives: 
+
+        ::::c
+        static int some_handler (TScont contp, TSEvent event, void *edata)
+        {
+        	.....
+        		switch(event) {
+        			case TS_EVENT_SOME_EVENT_1:
+        				do_some_thing_1;
+        				return;
+        			case TS_EVENT_SOME_EVENT_2:
+        				do_some_thing_2;
+        				return;
+        			case TS_EVENT_SOME_EVENT_3:
+        				do_some_thing_3;
+        				return;
+        			default: break;
+        		}
+        	return 0;
+        }
+
+
+![[Caution]](/images/docbook/caution.png)
+
+**Caution** 
+
+You might notice that a continuation cannot determine if more events are "in 
+flight" toward it. Do not use `TSContDestroy` to delete a continuation before 
+you make sure that all incoming events, such as those sent because of `TSHttpTxnHookAdd`,

+have been handled.
+
+The following table lists events and the corresponding type of `void * `data 
+passed to handler functions:
+
+`TS_EVENT_HTTP_READ_REQUEST_HDR`
+:   `TS_HTTP_READ_REQUEST_HDR_HOOK`
+:   `TSHttpTxn`
+
+`TS_EVENT_HTTP_OS_DNS`
+:   `TS_HTTP_OS_DNS_HOOK`
+:   `TSHttpTxn`
+
+`TS_EVENT_HTTP_SEND_REQUEST_HDR`
+:   `TS_HTTP_SEND_REQUEST_HDR_HOOK`
+:   `TSHttpTxn`
+
+`TS_EVENT_HTTP_READ_CACHE_HDR`
+:   `TS_HTTP_READ_CACHE_HDR_HOOK`
+:   `TSHttpTxn`
+
+`TS_EVENT_HTTP_READ_RESPONSE_HDR`
+:   `TS_HTTP_READ_RESPONSE_HDR_HOOK`
+:   `TSHttpTxn`
+
+`TS_EVENT_HTTP_SEND_RESPONSE_HDR`
+:   `TS_HTTP_SEND_RESPONSE_HDR_HOOK`
+:   `TSHttpTxn`
+
+`TS_EVENT_HTTP_SELECT_ALT`
+:   `TS_HTTP_SELECT_ALT_HOOK`
+:   `TSHttpTxn`
+
+`TS_EVENT_HTTP_TXN_START`
+:   `TS_HTTP_TXN_START_HOOK`
+:   `TSHttpTxn`
+
+`TS_EVENT_HTTP_TXN_CLOSE`
+:   `TS_HTTP_TXN_CLOSE_HOOK`
+:   `TSHttpTxn`
+
+`TS_EVENT_HTTP_SSN_START`
+:   `TS_HTTP_SSN_START_HOOK`
+:   `TSHttpSsn`
+
+`TS_EVENT_HTTP_SSN_CLOSE`
+:   `TS_HTTP_SSN_CLOSE_HOOK`
+:   `TSHttpSsn`
+
+
+`TS_EVENT_NONE`
+:   ` `
+:   ` `
+
+
+`TS_EVENT_CACHE_LOOKUP_COMPLETE`
+:   `TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK`
+:   `TSHttpTxn`
+
+`TS_EVENT_IMMEDIATE`
+:   `TSVConnClose, TSVIOReenable, TSContSchedule`
+:   ` `
+
+`TS_EVENT_IMMEDIATE`
+:   `TS_HTTP_REQUEST_TRANSFORM_HOOK`
+:   ` `
+
+`TS_EVENT_IMMEDIATE`
+:   `TS_HTTP_RESPONSE_TRANSFORM_HOOK`
+:   ` `
+
+`TS_EVENT_CACHE_OPEN_READ`
+:   `TSCacheRead`
+:   Cache VC
+
+`TS_EVENT_CACHE_OPEN_READ_FAILED`
+:   `TSCacheRead`
+:   Error code, see `TS_CACHE_ERROR_XXX`
+
+`TS_EVENT_CACHE_OPEN_WRITE`
+:   `TSCacheWrite`
+:   Cache VC
+
+`TS_EVENT_CACHE_OPEN_WRITE_FAILED`
+:   `TSCacheWrite`
+:   Error code, see `TS_CACHE_ERROR_XXX`
+
+`TS_EVENT_CACHE_REMOVE`
+:   `TSCacheRemove`
+:   Nothing
+
+`TS_EVENT_CACHE_REMOVE_FAILED`
+:   `TSCacheRemove`
+:   Error code, see `TS_CACHE_ERROR_XXX`
+
+`TS_EVENT_NET_ACCEPT`
+:   	TSNetAccept, TSHttpTxnServerIntercept,
+    	              TSHttpTxnIntercept:   Net VConnection
+
+`TS_EVENT_NET_ACCEPT_FAILED`
+:   	TSNetAccept, TSHttpTxnServerIntercept,
+    	              TSHttpTxnIntercept:   Nothing
+
+`TS_EVENT_HOST_LOOKUP`
+:   `TSHostLookup`
+:   Null pointer - error Non null pointer - `TSHostLookupResult`
+
+`TS_EVENT_TIMEOUT`
+:   `TSContSchedule`
+:   ` `
+
+`TS_EVENT_ERROR`
+:   ` `
+:   ` `
+
+
+
+`TS_EVENT_VCONN_READ_READY`
+:   `TSVConnRead`
+:   `TSVConn`
+
+`TS_EVENT_VCONN_WRITE_READY`
+:   `TSVConnWrite`
+:   `TSVConn`
+
+`TS_EVENT_VCONN_READ_COMPLETE`
+:   `TSVConnRead`
+:   `TSVConn`
+
+`TS_EVENT_VCONN_WRITE_COMPLETE`
+:   `TSVConnWrite`
+:   `TSVConn`
+
+`TS_EVENT_VCONN_EOS`
+:   `TSVConnRead`
+:   `TSVConn`
+
+`TS_EVENT_NET_CONNECT`
+:   `TSNetConnect`
+:   `TSVConn`
+
+`TS_EVENT_NET_CONNECT_FAILED`
+:   `TSNetConnect`
+:   `TSVConn`
+
+
+
+`TS_EVENT_HTTP_CONTINUE`
+:   ` `
+:   ` `
+
+`TS_EVENT_HTTP_ERROR`
+:   ` `
+:   ` `
+
+`TS_EVENT_MGMT_UPDATE`
+:   `TSMgmtUpdateRegister`
+:   `NULL`
+
+
+The continuation functions are listed below:
+
+* `TSContCall`
+
+* `TSContCreate`
+
+* `TSContDataGet`
+
+* `TSContDataSet`
+
+* `TSContDestroy`
+
+* `TSContMutexGet`
+
+* `TSContSchedule`
+
+

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/plugin-configurations/index.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/plugin-configurations/index.en.mdtext?rev=1068228&r1=1068227&r2=1068228&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/plugin-configurations/index.en.mdtext
(original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/plugin-configurations/index.en.mdtext
Tue Feb  8 00:01:04 2011
@@ -0,0 +1,116 @@
+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](../continuations/writing-handler-functions) - Writing Handler Functions
+
+Actions Guide - [Next](../actions-guide)
+
+##  Plugin Configurations ## {#PluginConfigurations}
+
+This chapter contains the following section:
+
+* [Plugin Configurations](#PluginConfigurations)
+
+## Plugin Configurations ## {#PluginConfigurations}
+
+The `TSConfig` family of functions provides a mechanism for accessing and 
+changing global configuration information within a plugin.
+
+The functions discussed in this section do not examine or modify Traffic Server 
+configuration variables. To examine Traffic Server configuration and statistics 
+variables, see ["Reading Traffic Server Settings and Statistics"]( ../plugin-management/reading-trafficserver-settings-and-statistics)
+
+The `TSConfig` family of functions is designed to provide a fast and efficient 
+mechanism for accessing and changing global configuration information within 
+a plugin. Such a mechanism is simple enough to provide in a single-threaded 
+program, but the translation to a multi-threaded program such as Traffic Server 
+is difficult. A common technique is to have a single mutex protect the global 
+configuration information; however, the problem with this solution is that 
+a single mutex becomes a performance bottleneck very quickly.
+
+The `TSConfig` family of functions define an interface to storing and retrieving 
+an opaque data pointer. Internally, Traffic Server maintains reference count 
+information about the data pointer so that a call to `TSConfigSet` will not 
+disturb another thread using the current data pointer. The philosophy is that 
+once a user has a hold of the configuration pointer, it is okay for it to be 
+used even if the configuration changes; all that a user typically wants is 
+a non-changing snapshot of the configuration. You should use `TSConfigSet` 
+for all global data updates.
+
+Here's how the interface works:
+
+        ::::c
+	/* Assume that you have previously defined a plugin configuration
+	 * data structure named ConfigData, along with its constructor
+	 * plugin_config_allocator () and its destructor 
+	 * plugin_config_destructor (ConfigData *data)
+	 */
+	ConfigData *plugin_config;
+	
+	/* You will need to assign plugin_config a unique identifier of type
+	 * unsigned int. It is important to initialize this identifier to zero
+	 * (see the documentation of the  function). 
+	 */
+	static unsigned int   my_id = 0;
+	
+	/* You will need an TSConfig pointer to access a snapshot of the 
+	 * current plugin_config. 
+	 */
+	TSConfig config_ptr;
+	
+	/* Initialize plugin_config. */
+	plugin_config = plugin_config_allocator();
+	
+	/* Assign plugin_config an identifier using TSConfigSet. */
+	my_id = TSConfigSet (my_id, plugin_config, plugin_config_destructor);
+	
+	/* Get a snapshot of the current configuration using TSConfigGet. */
+	config_ptr = TSConfigGet (my_id);
+	
+	/* With an TSConfig pointer to the current configuration, you can 
+	 * retrieve the configuration's current data using TSConfigDataGet. 
+	 */
+	plugin_config = (ConfigData*) TSConfigDataGet (config_ptr);
+	
+	/* Do something with plugin_config here. */
+	
+	/* When you are done with retrieving or modifying the plugin data, you
+	 * release the pointers to the data with a call to TSConfigRelease.
+	 */
+	TSConfigRelease (my_id, config_ptr);
+	
+	/* Any time you want to modify plugin_config, you must repeat these
+	 * steps, starting with 
+	 * my_id = TSConfigSet (my_id,plugin_config, plugin_config_destructor);
+	 * and continuing up to TSConfigRelease. 
+	 */
+
+The configuration functions are:
+
+* [`TSConfigDataGet`](link/to/doxygen)
+
+* [`TSConfigGet`](link/to/doxygen)
+
+* [`TSConfigRelease`](link/to/doxygen)
+
+* [`TSConfigSet`](link/to/doxygen)
+
+
+



Mime
View raw message