You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by bu...@apache.org on 2010/11/06 07:31:10 UTC
svn commit: r778776 [17/21] - in
/websites/staging/trafficserver/trunk/content/docs/trunk: admin/ sdk/
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MiscellaneousInterfaceGuide.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MiscellaneousInterfaceGuide.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MiscellaneousInterfaceGuide.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MiscellaneousInterfaceGuide.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,68 @@
<html>
<!-- This template is for the bulk of the site! -->
<head>
+ <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- 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. -->
</head>
<body>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
<div id="content">
-
+ <p><a href="HTTPAlternateSelection">Prev</a> - HTTP Alternate Selection
+The INKfopen Family - <a href="INKfopenFamily">Next</a></p>
+<h2 id="chapter_9_miscellaneous_interface_guide">Chapter 9. Miscellaneous Interface Guide</h2>
+<p>Most of the functions in the Traffic Server API provide an
+interface to specific code modules within Traffic Server. The
+miscellaneous functions described in this chapter provide some
+useful general capabilities. They are categorized as follows:</p>
+<ul>
+<li>
+<p><a href="DebuggingFunctions" title="Debugging Functions">Debugging Functions</a></p>
+</li>
+<li>
+<p><a href="INKfopenFamily" title="The INKfopen Family">The INKfopen Family</a></p>
+</li>
+<li>
+<p><a href="MemoryAllocation" title="Memory Allocation">Memory Allocation</a></p>
+</li>
+<li>
+<p><a href="ThreadFunctions" title="Thread Functions">Thread Functions</a></p>
+</li>
+</ul>
+<p>The C library already provides functions such as <code>printf</code>,
+<code>malloc</code>, and <code>fopen</code> to perform these tasks. The Traffic Server
+API versions, however, overcome various C library limitations (such
+as portability to all Traffic Server-supported platforms).</p>
+<h2 id="debugging_functions">Debugging Functions</h2>
+<ul>
+<li>
+<p><a href="DebuggingFunctions#INKDebug" title="INKDebug">INKDebug</a> prints
+ out a formatted statement if you are running Traffic Server in
+ debug mode.</p>
+</li>
+<li>
+<p><a href="INKIsDebugTagSet" title="INKIsDebugTagSet">INKIsDebugTagSet</a>
+ checks to see if a debug tag is set. If the debug tag is set, then
+ Traffic Server prints out all debug statements associated with the
+ tag.</p>
+</li>
+<li>
+<p><a href="INKError" title="INKError">INKError</a> prints error messages to
+ Traffic Server's error log</p>
+</li>
+<li>
+<p><a href="INKAssert" title="INKAssert">INKAssert</a> enables the use of
+ assertion in a plugin.</p>
+</li>
+<li>
+<p><a href="INKReleaseAssert" title="INKReleaseAssert">INKReleaseAssert</a>
+ enables the use of assertion in a plugin.</p>
+</li>
+</ul>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MutexFunctions.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MutexFunctions.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MutexFunctions.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MutexFunctions.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,35 @@
<html>
<!-- This template is for the bulk of the site! -->
<head>
+ <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- 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. -->
</head>
<body>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
<div id="content">
-
+ <p><a href="MimeHeadersFunctions">Prev</a> - MIIME Headers
+INKMutexLock - <a href="INKMutexLock">Next</a></p>
+<h2 id="mutex_functions">Mutex Functions</h2>
+<hr />
+<p><a href="MutexFunctions#INKMutexCreate">INKMutexCreate</a>
+<a href="INKMutexLock">INKMutexLock</a>
+<a href="INKMutexLockTry">INKMutexLockTry</a>
+<a href="INKMutexUnlock">INKMutexUnlock</a></p>
+<h3 id="inkmutexcreate">INKMutexCreate</h3>
+<p>Creates a new <code>INKMutex</code>.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKMutex INKMutexCreate (void)</code></p>
+<p><strong>Description</strong>
+ ~ Creates a new <code>INKMutex</code>.</p>
+<p><strong>Returns</strong>
+ ~ A handle to the newly-created mutex.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR_PTR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span><span class="o">.</span>
+</pre></div>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MutexGuide.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MutexGuide.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MutexGuide.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MutexGuide.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,383 @@
<html>
<!-- This template is for the bulk of the site! -->
<head>
+ <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- 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. -->
</head>
<body>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
<div id="content">
-
+ <p><a href="MIMEHeaders">Prev</a> - MIME Headers
+Chapter 12. Continuations - <a href="Continuations">Next</a></p>
+<h2 id="chapter_11_mutex_guide">Chapter 11. Mutex Guide</h2>
+<p>Mutexes are used to lock shared data. This chapter explains how to
+use the mutex interface.</p>
+<ul>
+<li><a href="MutexGuide#Mutexes"><strong>Mutexes</strong></a></li>
+<li><a href="MutexGuide#LockingGlobalData">Locking Global Data</a></li>
+<li><strong><a href="MutexGuide#ProtectContinuationData">Protecting a Continuation's Data</a></strong></li>
+<li><strong><a href="MutexGuide#AssocContinuationToHTTPTx">How to Associate a Continuation With Every HTTP Transaction</a></strong></li>
+<li><strong><a href="MutexGuide#AddNewContinuation">How to Add the New Continuation</a></strong></li>
+<li><strong><a href="MutexGuide#StoreDataSpecificHTTPTx">How to Store Data Specific to Each HTTP Transaction</a></strong></li>
+<li><strong><a href="MutexGuide#UsingLocks">Using Locks</a></strong></li>
+<li><strong><a href="MutexGuide#ContinuationsCreatedHTTPTx">Special Case: Continuations Created for HTTP Transactions</a></strong></li>
+</ul>
+<h2 id="mutexes">Mutexes</h2>
+<p>A <strong>mutex</strong> is the basic synchronization method used within Traffic
+Server to protect data from simultaneous access by multiple
+threads. A mutex acts as a lock that protects data in one program
+thread from being accessed by another thread.</p>
+<p>The Traffic Server API provides two functions that attempt to
+access and lock the data: <code>InkMutexLockTry</code> and <code>INKMutexLock</code>.
+<code><b>INKMutexLock</b></code> is a blocking call - if you use it, you can
+slow Traffic Server performance because transaction processing
+pauses until the mutex is unlocked. It should be used only on
+threads created by the plugin <code>INKContThreadCreate</code>. Never use it
+on a continuation handler called back by the Cache, Net, or Event
+Processor. Even if the critical section is very small, do not use
+it. If you need to update a flag, then set a variable and/or use
+atomic operations. If <code>INKMutexLock</code> is used in any case other than
+the one recommended above, then the result will be a serious
+performance impact.</p>
+<p><code><b>INKMutexLockTry</b></code>, on the other hand, attempts to lock the
+mutex only if it is unlocked (i.e., not being used by another
+thread). It should be used in all cases other than the above
+mentioned <code>INKMutexLock</code> case. If the <code>INKMutexLockTry</code> attempt
+fails, then you can schedule a future attempt (which must be at
+least 10 milliseconds later).</p>
+<p>In general, you should use <code>INKMutexLockTry</code> instead of
+<code>INKMutexLock</code>.</p>
+<ul>
+<li>
+<p><code>InkMutexLockTry</code> is required if you are tying to lock Traffic
+ Server internal or system resources (such as the network, cache,
+ event processor, HTTP state machines, and IO buffers).</p>
+</li>
+<li>
+<p><code>InkMutexLockTry</code> is required if you are making any blocking
+ calls (such as network, cache, or file IO calls).</p>
+</li>
+<li>
+<p><code>INKMutexLock</code> might not be necessary if you are not making
+ blocking calls and if you are only accessing local resources.</p>
+</li>
+</ul>
+<p>The Traffic Server API uses the <code>INKMutex</code> type for a mutex. There
+are two typical uses of mutex. One use is for locking global data
+or data shared by various continuations. The other typical usage is
+for locking data associated with a continuation (i.e., data that
+might be accessed by other continuations).</p>
+<h3 id="locking_global_data">Locking Global Data</h3>
+<p>The <code>blacklist-1.c</code> sample plugin implements a mutex that locks
+global data. The blacklist plugin reads its blacklisted sites from
+a configuration file; file read operations are protected by a mutex
+created in <code>INKPluginInit</code>. The <code>blacklist-1.c</code> code uses
+<code>INKMutexLockTry</code> instead of <code>InkMutexLock</code>. For more detailed
+information, see the
+<a href="App_SampleSourceCode#Sample_blacklist-1.c" title="blacklist-1.c"><code>blacklist-1.c</code></a>
+<code>` code; start by looking at the
+[</code>INKPluginInit`](InitializationFunctions#INKPluginInit "INKPluginInit")
+function.</p>
+<p>General guidelines for locking shared data are as follows:</p>
+<ol>
+<li>
+<p>Create a mutex for the shared data with
+ <a href="MutexFunctions#INKMutexCreate" title="INKMutexCreate"><code>INKMutexCreate</code></a>.</p>
+</li>
+<li>
+<p>Whenever you need to read or modify this data, first lock it by
+ calling
+ <a href="INKMutexLockTry" title="INKMutexLockTry"><code>INKMutexLockTry</code></a>; then
+ read or modify the data.</p>
+</li>
+<li>
+<p>When you are done with the data, unlock it with
+ <a href="INKMutexUnlock" title="INKMutexUnlock"><code>INKMutexUnlock</code></a>. If you
+ are unlocking data accessed during the processing of an HTTP
+ transaction, then you must unlock it before calling
+ <a href="HTTPTransactionFunctions#INKHttpTxnReenable" title="INKHttpTxnReenable"><code>INKHttpTxnReenable</code></a>.</p>
+</li>
+</ol>
+<h3 id="protecting_a_continuations_data">Protecting a Continuation's Data</h3>
+<p>You must create a mutex to protect a continuation's data if it
+might be accessed by other continuations or processes. Here's how:</p>
+<ol>
+<li>
+<p>Create a mutex for the continuation using <code>INKMutexCreate</code>. <br />
+ For example:</p>
+<div class="codehilite"><pre><span class="n">INKMutex</span> <span class="n">mutexp</span><span class="p">;</span>
+<span class="n">mutexp</span> <span class="o">=</span> <span class="n">INKMutexCreate</span> <span class="p">();</span>
+</pre></div>
+
+
+</li>
+<li>
+<p>When you create the continuation, specify this mutex as the
+ continuation's mutex. <br />
+ For example:
+ INKCont contp;
+ contp = INKContCreate (handler, mutexp);</p>
+</li>
+</ol>
+<p>If any other functions want to access <code>contp</code>'s data, then it is up
+to them to get <code>contp</code>'s mutex (using, for example,
+<code>INKContMutexGet</code>) to lock it. For usage, ssee the sample Protocol
+plugin.</p>
+<h3 id="how_to_associate_a_continuation_with_every_http_transaction">How to Associate a Continuation With Every HTTP Transaction</h3>
+<p>There could be several reasons why you'd want to create a
+continuation for each HTTP transaction that calls back your plugin.</p>
+<p>Some potential scenarios are listed below.</p>
+<ul>
+<li>
+<p>You want to register hooks locally with the new continuation
+ instead of registering them globally to the continuation plugin.</p>
+</li>
+<li>
+<p>You want to store data specific to each HTTP transaction that
+ you might need to reuse across various hooks.</p>
+</li>
+<li>
+<p>You're using APIs (like <code>INKHostLookup</code>) that will call back
+ the continuation with a certain event.</p>
+</li>
+</ul>
+<h3 id="how_to_add_the_new_continuation">How to Add the New Continuation</h3>
+<p>A typical way of adding the new continuation is by registering the
+plugin continuation to be called back by HTTP transactions globally
+when they reach <code>INK_HTTP_TXN_START_HOOK</code>. Refer to the example
+below, which uses a transaction-specific continuation called
+<code>txn_contp</code>.</p>
+<div class="codehilite"><pre> <span class="n">void</span> <span class="n">INKPluginInit</span><span class="p">(</span><span class="nb">int</span> <span class="n">argc</span><span class="p">,</span> <span class="n">const</span> <span class="n">char</span> <span class="o">*</span><span class="n">argv</span><span class="o">[]</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="sr">/* Plugin continuation */</span>
+ <span class="n">INKCont</span> <span class="n">contp</span><span class="p">;</span>
+ <span class="k">if</span> <span class="p">((</span><span class="n">contp</span> <span class="o">=</span> <span class="n">INKContCreate</span> <span class="p">(</span><span class="n">plugin_cont_handler</span><span class="p">,</span> <span class="n">NULL</span><span class="p">))</span> <span class="o">==</span> <span class="n">INK_ERROR_PTR</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">LOG_ERROR</span><span class="p">(</span><span class="s">"INKContCreate"</span><span class="p">);</span>
+ <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">INKHttpHookAdd</span> <span class="p">(</span><span class="n">INK_HTTP_TXN_START_HOOK</span><span class="p">,</span> <span class="n">contp</span><span class="p">)</span> <span class="o">==</span> <span class="n">INK_ERROR</span><span class="p">)</span> <span class="p">{</span>
+<span class="n">LOG_ERROR</span><span class="p">(</span><span class="s">"INKHttpHookAdd"</span><span class="p">);</span>
+<span class="p">}</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+</pre></div>
+
+
+<p>In the plugin continuation handler, create the new continuation
+<code>txn_contp</code> and then register it to be called back at
+<code>INK_HTTP_TXN_CLOSE_HOOK</code>:</p>
+<div class="codehilite"><pre><span class="n">static</span> <span class="nb">int</span> <span class="n">plugin_cont_handler</span><span class="p">(</span><span class="n">INKCont</span> <span class="n">contp</span><span class="p">,</span> <span class="n">INKEvent</span> <span class="n">event</span><span class="p">,</span> <span class="n">void</span> <span class="o">*</span><span class="n">edata</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="n">INKHttpTxn</span> <span class="n">txnp</span> <span class="o">=</span> <span class="p">(</span><span class="n">INKHttpTxn</span><span class="p">)</span><span class="n">edata</span><span class="p">;</span>
+ <span class="n">INKCont</span> <span class="n">txn_contp</span><span class="p">;</span>
+
+ <span class="n">switch</span> <span class="p">(</span><span class="n">event</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">case</span> <span class="n">INK_EVENT_HTTP_TXN_START:</span>
+ <span class="sr">/* Create the HTTP txn continuation */</span>
+ <span class="n">txn_contp</span> <span class="o">=</span> <span class="n">INKContCreate</span><span class="p">(</span><span class="n">txn_cont_handler</span><span class="p">,</span> <span class="n">NULL</span><span class="p">);</span>
+
+ <span class="sr">/* Register txn_contp to be called back when txnp reaches INK_HTTP_TXN_CLOSE_HOOK */</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">INKHttpTxnHookAdd</span> <span class="p">(</span><span class="n">txnp</span><span class="p">,</span> <span class="n">INK_HTTP_TXN_CLOSE_HOOK</span><span class="p">,</span> <span class="n">txn_contp</span><span class="p">)</span> <span class="o">==</span> <span class="n">INK_ERROR</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">LOG_ERROR</span><span class="p">(</span><span class="s">"INKHttpTxnHookAdd"</span><span class="p">);</span>
+ <span class="p">}</span>
+
+ <span class="n">break</span><span class="p">;</span>
+
+ <span class="n">default:</span>
+ <span class="n">INKAssert</span><span class="p">(</span><span class="o">!</span><span class="s">"Unexpected Event"</span><span class="p">);</span>
+ <span class="n">break</span><span class="p">;</span>
+ <span class="p">}</span>
+
+ <span class="k">if</span> <span class="p">(</span><span class="n">INKHttpTxnReenable</span><span class="p">(</span><span class="n">txnp</span><span class="p">,</span> <span class="n">INK_EVENT_HTTP_CONTINUE</span><span class="p">)</span> <span class="o">==</span> <span class="n">INK_ERROR</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">LOG_ERROR</span><span class="p">(</span><span class="s">"INKHttpTxnReenable"</span><span class="p">);</span>
+ <span class="p">}</span>
+
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="p">}</span>
+</pre></div>
+
+
+<p>Remember that the <code>txn_contp</code> handler must destory itself when the
+HTTP transaction is closed. If you forget to do this, then your
+plugin will have a memory leak.</p>
+<div class="codehilite"><pre><span class="n">static</span> <span class="nb">int</span> <span class="n">txn_cont_handler</span><span class="p">(</span><span class="n">INKCont</span> <span class="n">txn_contp</span><span class="p">,</span> <span class="n">INKEvent</span> <span class="n">event</span><span class="p">,</span> <span class="n">void</span> <span class="o">*</span><span class="n">edata</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="n">INKHttpTxn</span> <span class="n">txnp</span><span class="p">;</span>
+ <span class="n">switch</span> <span class="p">(</span><span class="n">event</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">case</span> <span class="n">INK_EVENT_HTTP_TXN_CLOSE:</span>
+ <span class="n">txnp</span> <span class="o">=</span> <span class="p">(</span><span class="n">INKHttpTxn</span><span class="p">)</span> <span class="n">edata</span><span class="p">;</span>
+ <span class="n">INKContDestroy</span><span class="p">(</span><span class="n">txn_contp</span><span class="p">);</span>
+ <span class="n">break</span><span class="p">;</span>
+
+ <span class="n">default:</span>
+ <span class="n">INKAssert</span><span class="p">(</span><span class="o">!</span><span class="s">"Unexpected Event"</span><span class="p">);</span>
+ <span class="n">break</span><span class="p">;</span>
+ <span class="p">}</span>
+
+ <span class="k">if</span> <span class="p">(</span><span class="n">INKHttpTxnReenable</span><span class="p">(</span><span class="n">txnp</span><span class="p">,</span> <span class="n">INK_EVENT_HTTP_CONTINUE</span><span class="p">)</span> <span class="o">==</span> <span class="n">INK_ERROR</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">LOG_ERROR</span><span class="p">(</span><span class="s">"INKHttpTxnReenable"</span><span class="p">);</span>
+ <span class="p">}</span>
+
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="p">}</span>
+</pre></div>
+
+
+<h3 id="how_to_store_data_specific_to_each_http_transaction">How to Store Data Specific to Each HTTP Transaction</h3>
+<p>For the example above, store the data in the <code>txn_contp</code> data
+structure - this means that you'll create your own data structure.
+Now suppose you want to store the state of the HTTP transaction:</p>
+<div class="codehilite"><pre> <span class="n">typedef</span> <span class="n">struct</span> <span class="p">{</span>
+ <span class="nb">int</span> <span class="n">state</span><span class="p">;</span>
+ <span class="p">}</span> <span class="n">ContData</span><span class="p">;</span>
+</pre></div>
+
+
+<p>You need to allocate the memory and initialize this structure for
+each HTTP <code>txnp</code>. You can do that in the plugin continuation
+handler when it is called back with <code>INK_EVENT_HTTP_TXN_START</code></p>
+<div class="codehilite"><pre><span class="n">static</span> <span class="nb">int</span> <span class="n">plugin_cont_handler</span><span class="p">(</span><span class="n">INKCont</span> <span class="n">contp</span><span class="p">,</span> <span class="n">INKEvent</span> <span class="n">event</span><span class="p">,</span> <span class="n">void</span> <span class="o">*</span><span class="n">edata</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="n">INKHttpTxn</span> <span class="n">txnp</span> <span class="o">=</span> <span class="p">(</span><span class="n">INKHttpTxn</span><span class="p">)</span><span class="n">edata</span><span class="p">;</span>
+ <span class="n">INKCont</span> <span class="n">txn_contp</span><span class="p">;</span>
+ <span class="n">ContData</span> <span class="o">*</span><span class="n">contData</span><span class="p">;</span>
+
+ <span class="n">switch</span> <span class="p">(</span><span class="n">event</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">case</span> <span class="n">INK_EVENT_HTTP_TXN_START:</span>
+ <span class="sr">/* Create the HTTP txn continuation */</span>
+ <span class="n">txn_contp</span> <span class="o">=</span> <span class="n">INKContCreate</span><span class="p">(</span><span class="n">txn_cont_handler</span><span class="p">,</span> <span class="n">NULL</span><span class="p">);</span>
+
+ <span class="sr">/* Allocate and initialize the txn_contp data */</span>
+ <span class="n">contData</span> <span class="o">=</span> <span class="p">(</span><span class="n">ContData</span><span class="o">*</span><span class="p">)</span> <span class="n">INKmalloc</span><span class="p">(</span><span class="n">sizeof</span><span class="p">(</span><span class="n">ContData</span><span class="p">));</span>
+ <span class="n">contData</span><span class="o">-></span><span class="n">state</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">INKContDataSet</span><span class="p">(</span><span class="n">txn_contp</span><span class="p">,</span> <span class="n">contData</span><span class="p">)</span> <span class="o">==</span> <span class="n">INK_ERROR</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">LOG_ERROR</span><span class="p">(</span><span class="s">"INKContDataSet"</span><span class="p">);</span>
+ <span class="p">}</span>
+
+ <span class="sr">/* Register txn_contp to be called back when txnp reaches INK_HTTP_TXN_CLOSE_HOOK */</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">INKHttpTxnHookAdd</span> <span class="p">(</span><span class="n">txnp</span><span class="p">,</span> <span class="n">INK_HTTP_TXN_CLOSE_HOOK</span><span class="p">,</span> <span class="n">txn_contp</span><span class="p">)</span> <span class="o">==</span> <span class="n">INK_ERROR</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">LOG_ERROR</span><span class="p">(</span><span class="s">"INKHttpTxnHookAdd"</span><span class="p">);</span>
+ <span class="p">}</span>
+
+ <span class="n">break</span><span class="p">;</span>
+
+ <span class="n">default:</span>
+ <span class="n">INKAssert</span><span class="p">(</span><span class="o">!</span><span class="s">"Unexpected Event"</span><span class="p">);</span>
+ <span class="n">break</span><span class="p">;</span>
+ <span class="p">}</span>
+
+ <span class="k">if</span> <span class="p">(</span><span class="n">INKHttpTxnReenable</span><span class="p">(</span><span class="n">txnp</span><span class="p">,</span> <span class="n">INK_EVENT_HTTP_CONTINUE</span><span class="p">)</span> <span class="o">==</span> <span class="n">INK_ERROR</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">LOG_ERROR</span><span class="p">(</span><span class="s">"INKHttpTxnReenable"</span><span class="p">);</span>
+ <span class="p">}</span>
+
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="p">}</span>
+<span class="n">For</span> <span class="n">accessing</span> <span class="n">this</span> <span class="n">data</span> <span class="n">from</span> <span class="n">anywhere</span><span class="p">,</span> <span class="k">use</span> <span class="n">INKContDataGet:</span>
+<span class="n">INKCont</span> <span class="n">txn_contp</span><span class="p">;</span>
+ <span class="n">ContData</span> <span class="o">*</span><span class="n">contData</span><span class="p">;</span>
+
+ <span class="n">contData</span> <span class="o">=</span> <span class="n">INKContDataGet</span><span class="p">(</span><span class="n">txn_contp</span><span class="p">);</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">contData</span> <span class="o">==</span> <span class="n">INK_ERROR_PTR</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">LOG_ERROR</span><span class="p">(</span><span class="s">"INKContDataGet"</span><span class="p">);</span>
+ <span class="p">}</span>
+ <span class="n">contData</span><span class="o">-></span><span class="n">state</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
+<span class="n">Remember</span> <span class="n">to</span> <span class="n">free</span> <span class="n">this</span> <span class="n">memory</span> <span class="n">before</span> <span class="n">destroying</span> <span class="n">the</span> <span class="n">continuation:</span>
+<span class="n">static</span> <span class="nb">int</span> <span class="n">txn_cont_handler</span><span class="p">(</span><span class="n">INKCont</span> <span class="n">txn_contp</span><span class="p">,</span> <span class="n">INKEvent</span> <span class="n">event</span><span class="p">,</span> <span class="n">void</span> <span class="o">*</span><span class="n">edata</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="n">INKHttpTxn</span> <span class="n">txnp</span><span class="p">;</span>
+ <span class="n">ContData</span> <span class="o">*</span><span class="n">contData</span><span class="p">;</span>
+ <span class="n">switch</span> <span class="p">(</span><span class="n">event</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">case</span> <span class="n">INK_EVENT_HTTP_TXN_CLOSE:</span>
+ <span class="n">txnp</span> <span class="o">=</span> <span class="p">(</span><span class="n">INKHttpTxn</span><span class="p">)</span> <span class="n">edata</span><span class="p">;</span>
+ <span class="n">contData</span> <span class="o">=</span> <span class="n">INKContDataGet</span><span class="p">(</span><span class="n">txn_contp</span><span class="p">);</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">contData</span> <span class="o">==</span> <span class="n">INK_ERROR_PTR</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">LOG_ERROR</span><span class="p">(</span><span class="s">"INKContDataGet"</span><span class="p">);</span>
+ <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+ <span class="n">INKfree</span><span class="p">(</span><span class="n">contData</span><span class="p">);</span>
+ <span class="p">}</span>
+ <span class="n">INKContDestroy</span><span class="p">(</span><span class="n">txn_contp</span><span class="p">);</span>
+ <span class="n">break</span><span class="p">;</span>
+
+ <span class="n">default:</span>
+ <span class="n">INKAssert</span><span class="p">(</span><span class="o">!</span><span class="s">"Unexpected Event"</span><span class="p">);</span>
+ <span class="n">break</span><span class="p">;</span>
+ <span class="p">}</span>
+
+ <span class="k">if</span> <span class="p">(</span><span class="n">INKHttpTxnReenable</span><span class="p">(</span><span class="n">txnp</span><span class="p">,</span> <span class="n">INK_EVENT_HTTP_CONTINUE</span><span class="p">)</span> <span class="o">==</span> <span class="n">INK_ERROR</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">LOG_ERROR</span><span class="p">(</span><span class="s">"INKHttpTxnReenable"</span><span class="p">);</span>
+ <span class="p">}</span>
+
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="p">}</span>
+</pre></div>
+
+
+<h3 id="using_locks">Using Locks</h3>
+<p>You do not need to use locks when a continuation has registered
+itself to be called back by HTTP hooks and it only uses the HTTP
+APIs. In the example above, the continuation <code>txn_contp</code> has
+registered itself to be called back at HTTP hooks and it only uses
+the HTTP APIs. In this case only, it's safe to access data shared
+between <code>txnp</code> and <code>txn_contp</code> without grabbing a lock. In the
+example above, <code>txn_contp</code> is created with a <code>NULL</code> mutex. This
+works because the HTTP transaction <code>txnp</code> is the only one that will
+call back <code>txn_contp</code>, and you are guaranteed that <code>txn_contp</code> will
+be called back only one hook at a time. After processing is
+finished, <code>txn_contp</code> will reenable <code>txnp</code>.</p>
+<p>In all other cases, you should create a mutex with the
+continuation. In general, a lock is needed when you're using iocore
+APIs or any other API where <code>txn_contp</code> is scheduled to be called
+back by a processor (such as the cache processor, the DNS
+processor, etc.). This ensures that <code>txn_contp</code> is called back
+sequentially and not simultaneously. In other words, you need to
+ensure that <code>txn_contp</code> will not be called back by both <code>txnp</code> and
+the cache processor at the same time, since this will result in a
+situation wherein you're executing two pieces of code in conflict.</p>
+<h3 id="special_case_continuations_created_for_http_transactions">Special Case: Continuations Created for HTTP Transactions</h3>
+<p>If your plugin creates a new continuation for each HTTP
+transaction, then you probably don't need to create a new mutex for
+it because each HTTP transaction (<code>INKHttpTxn</code> object) already has
+its own mutex.</p>
+<p>In the example below, it's not necessary to specify a mutex for the
+continuation created in <code>txn_handler</code>:</p>
+<div class="codehilite"><pre><span class="n">static</span> <span class="n">void</span>
+<span class="n">txn_handler</span> <span class="p">(</span><span class="n">INKHttpTxn</span> <span class="n">txnp</span><span class="p">,</span> <span class="n">INKCont</span> <span class="n">contp</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">INKCont</span> <span class="n">newCont</span><span class="p">;</span>
+ <span class="o">....</span>
+ <span class="n">newCont</span> <span class="o">=</span> <span class="n">INKContCreate</span> <span class="p">(</span><span class="n">newCont_handler</span><span class="p">,</span> <span class="n">NULL</span><span class="p">);</span>
+ <span class="sr">//</span><span class="n">It</span><span class="err">'</span><span class="n">s</span> <span class="ow">not</span> <span class="n">necessary</span> <span class="n">to</span> <span class="n">create</span> <span class="n">a</span> <span class="k">new</span> <span class="n">mutex</span> <span class="k">for</span> <span class="n">newCont</span><span class="o">.</span>
+
+ <span class="o">...</span>
+
+ <span class="n">INKHttpTxnReenable</span> <span class="p">(</span><span class="n">txnp</span><span class="p">,</span> <span class="n">INK_EVENT_HTTP_CONTINUE</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="n">static</span> <span class="nb">int</span>
+<span class="n">test_plugin</span> <span class="p">(</span><span class="n">INKCont</span> <span class="n">contp</span><span class="p">,</span> <span class="n">INKEvent</span> <span class="n">event</span><span class="p">,</span> <span class="n">void</span> <span class="o">*</span><span class="n">edata</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">INKHttpTxn</span> <span class="n">txnp</span> <span class="o">=</span> <span class="p">(</span><span class="n">INKHttpTxn</span><span class="p">)</span> <span class="n">edata</span><span class="p">;</span>
+
+ <span class="n">switch</span> <span class="p">(</span><span class="n">event</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">case</span> <span class="n">INK_EVENT_HTTP_READ_REQUEST_HDR:</span>
+ <span class="n">txn_handler</span> <span class="p">(</span><span class="n">txnp</span><span class="p">,</span> <span class="n">contp</span><span class="p">);</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="n">default:</span>
+ <span class="n">break</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>The mutex functions are listed below:</p>
+<ul>
+<li><a href="MutexFunctions#INKMutexCreate" title="INKMutexCreate"><code>INKMutexCreate</code></a></li>
+<li><code><a href="INKMutexLock.html" title="INKMutexLock">INKMutexLock</a></code></li>
+<li><code><a href="INKMutexLockTry.html" title="INKMutexLockTry">INKMutexLockTry</a></code></li>
+</ul>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/NamingConventions.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/NamingConventions.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/NamingConventions.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/NamingConventions.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,62 @@
<html>
<!-- This template is for the bulk of the site! -->
<head>
+ <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- 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. -->
</head>
<body>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
<div id="content">
-
+ <p><a href="PlusingRegisAndVersionCkg">Prev</a> - Plugin Registration and
+Version Checking
+Chapter 2. How to Create Traffic Server Plugins -
+<a href="CreatingTSPlugins">Next</a></p>
+<h2 id="naming_conventions">Naming Conventions</h2>
+<p>The Traffic Server API adheres to the following naming
+conventions:</p>
+<ul>
+<li>
+<p>The <code>INK</code> prefix is used for all function and variable names
+ defined in the Traffic Server API. <strong>Examples</strong>:
+ <code>INK_EVENT_NONE</code>,<code>INKMutex</code>, and <code>INKContCreate</code></p>
+</li>
+<li>
+<p>Enumerated values are always written in all uppercase letters.
+ <strong>Examples</strong>: <em><code>INK_EVENT_NONE</code></em> and <em><code>INK_VC_CLOSE_ABORT</code></em></p>
+</li>
+<li>
+<p>Constant values are all uppercase; enumerated values can be
+ seen as a subset of constants. <strong>Examples</strong>:
+ <code><code class="constant">INK_URL_SCHEME_FILE</code> and
+ <code>INK_MIME_FIELD_ACCEPT</code></p>
+</li>
+<li>
+<p>The names of defined types are mixed-case. <strong>Examples</strong>:
+ <em><code>INKHttpSsn</code></em> and <em><code>INKHttpTxn</code></em></p>
+</li>
+<li>
+<p>Function names are mixed-case. <strong>Examples</strong>: <code>INKUrlCreate</code> and
+ <code>INKContDestroy</code></p>
+</li>
+<li>
+<p>Function names use the following subject-verb naming style:
+ <code>INK-<subject>-<verb></code>, where <code><subject></code> goes from general to
+ specific. This makes it easier to determine what a function does by
+ reading its name. <strong>For</strong> <strong>example</strong>: the function to retrieve the
+ password field (the specific subject) from a URL (the general
+ subject) is <code>INKUrlPasswordGet</code>.</p>
+</li>
+<li>
+<p>Common verbs like <code>Create</code>, <code>Destroy</code>, <code>Get</code>, <code>Set</code>, <code>Copy</code>,
+ <code>Find</code>, <code>Retrieve</code>, <code>Insert</code>, <code>Remove</code>, and <code>Delete</code> are used only
+ when appropriate.</p>
+</li>
+</ul>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/NetVconnections.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/NetVconnections.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/NetVconnections.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/NetVconnections.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,31 @@
<html>
<!-- This template is for the bulk of the site! -->
<head>
+ <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- 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. -->
</head>
<body>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
<div id="content">
-
+ <p><a href="IOGuide">Prev</a> - Chapter 15. IO Guide
+Transformations - <a href="Transformations_IO">Next</a></p>
+<h2 id="net_vconnections">Net Vconnections</h2>
+<p>A <strong>network</strong> <strong>vconnection</strong> (or<strong>netvconnection</strong>) is a wrapper
+around a TCP socket that enables the socket to work within the
+Traffic Server vconnection framework. See
+<a href="IOGuide#Vconnections" title="Vconnections">vconnections</a> for more
+information about the Traffic Server abstraction for doing
+asynchronous IO.</p>
+<p>The netvconnection functions are listed below:</p>
+<ul>
+<li><a href="NetvconnectionFunctions#INKNetAccept" title="INKNetAccept">INKNetAccept</a></li>
+<li><a href="INKNetConnect" title="INKNetConnect">INKNetConnect</a></li>
+</ul>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/NetvconnectionFunctions.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/NetvconnectionFunctions.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/NetvconnectionFunctions.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/NetvconnectionFunctions.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,64 @@
<html>
<!-- This template is for the bulk of the site! -->
<head>
+ <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- 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. -->
</head>
<body>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
<div id="content">
-
+ <p><a href="INKVConnWriteVIOGet">Prev</a> - INKVConnWriteVIOGet
+INKNetConnect - <a href="INKNetConnect">Next</a></p>
+<h2 id="netvconnection_functions">Netvconnection Functions</h2>
+<hr />
+<p><a href="NetvconnectionFunctions#INKNetAccept">INKNetAccept</a>
+<a href="INKNetConnect">INKNetConnect</a>
+<a href="INKNetVConnRemoteIPGet">INKNetVConnRemoteIPGet</a>
+<a href="INKNetVConnRemotePortGet">INKNetVConnRemotePortGet</a></p>
+<h3 id="inknetaccept">INKNetAccept</h3>
+<p>Accepts a TCP/IP connection on a specified port.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKAction INKNetAccept (INKCont <em class="replaceable"><code>contp</code>,
+ int <em><code>port</code></em>)</p>
+<p><strong>Arguments</strong>
+ ~ <code>INKCont</code> <code><em class="replaceable"><code>contp</code> is the
+ continuation that's called back when a connection is accepted.</p>
+<div class="codehilite"><pre><span class="sb">`int``<em class="replaceable"><code>port`</span> <span class="n">is</span> <span class="n">the</span> <span class="n">port</span> <span class="n">that</span> <span class="n">will</span>
+<span class="nb">listen</span> <span class="k">for</span> <span class="n">incoming</span> <span class="n">TCP</span><span class="o">/</span><span class="n">IP</span> <span class="n">connections</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Description</strong>
+ ~ Accepts a TCP/IP connection on
+ <code><em class="replaceable"><code>port</code>. When Traffic Server receives
+ a connection on a specified port, it calls back
+ <code><em class="replaceable"><code>contp</code> with the event
+ <code>INK_EVENT_NET_ACCEPT</code> or <code>INK_EVENT_NET_ACCEPT_FAILED</code>.</p>
+<div class="codehilite"><pre><span class="n">If</span> <span class="n">the</span> <span class="n">event</span> <span class="n">is</span> <span class="sb">`INK_EVENT_NET_ACCEPT`</span><span class="p">,</span> <span class="k">then</span> <span class="n">the</span>
+<span class="sb">`void *``<em class="replaceable"><code>data`</span> <span class="n">passed</span> <span class="n">to</span> <span class="n">the</span> <span class="n">handler</span>
+<span class="n">of</span> <span class="n">the</span> <span class="n">continuation</span> <span class="sb">`<em class="replaceable"><code>contp`</span> <span class="n">is</span> <span class="n">a</span>
+<span class="n">netvconnection</span> <span class="n">datatype</span> <span class="n">that</span> <span class="n">represents</span> <span class="n">the</span> <span class="n">connection</span><span class="o">.</span>
+
+<span class="n">If</span> <span class="n">the</span> <span class="n">event</span> <span class="n">is</span> <span class="sb">`INK_EVENT_NET_ACCEPT_FAILED`</span><span class="p">,</span> <span class="k">then</span> <span class="n">it</span> <span class="n">means</span> <span class="n">a</span>
+<span class="n">connection</span> <span class="n">attempt</span> <span class="n">was</span> <span class="n">aborted</span> <span class="ow">or</span> <span class="n">failed</span><span class="o">.</span> <span class="n">The</span> <span class="n">plugin</span> <span class="n">should</span> <span class="n">just</span>
+<span class="k">return</span> <span class="n">from</span> <span class="n">the</span> <span class="n">continuation</span><span class="err">'</span><span class="n">s</span> <span class="n">handler</span><span class="o">.</span>
+
+<span class="n">The</span> <span class="n">user</span> <span class="p">(</span><span class="sb">`<em class="replaceable"><code>contp`</span><span class="p">)</span> <span class="n">has</span> <span class="n">the</span> <span class="n">option</span> <span class="n">to</span>
+<span class="n">cancel</span> <span class="n">the</span> <span class="n">action</span> <span class="n">returned</span> <span class="n">by</span> <span class="sb">`INKNetAccept`</span> <span class="n">by</span> <span class="n">using</span>
+<span class="sb">`INKActionCancel`</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Returns</strong>
+ ~ An <code>INKAction</code> object if successful.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR_PTR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">argument</span> <span class="n">was</span> <span class="n">incorrect</span> <span class="ow">or</span> <span class="k">if</span> <span class="n">the</span> <span class="n">API</span>
+<span class="n">failed</span><span class="o">.</span>
+</pre></div>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/NewProtocolPlugins.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/NewProtocolPlugins.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/NewProtocolPlugins.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/NewProtocolPlugins.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,393 @@
<html>
<!-- This template is for the bulk of the site! -->
<head>
+ <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- 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. -->
</head>
<body>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
<div id="content">
-
+ <p><a href="SampleBufferedNullTransformPlugin">Prev</a> - The Sample
+Buffered Null Transform Plugin
+Chapter 7. Cache Plugin - <a href="ch07">Next</a></p>
+<h2 id="chapter_6_new_protocol_plugins">Chapter 6. New Protocol Plugins</h2>
+<p><strong>Table of Contents</strong></p>
+<ul>
+<li><a href="NewProtocolPlugins#ProtocolPluginStructure">Protocol Plugin Structure</a></li>
+<li><a href="NewProtocolPlugins#ContinuationsInProtocolPlugin">Continuations in the Protocol Plugin</a></li>
+<li><a href="NewProtocolPlugins#EventFlow">Event Flow</a></li>
+<li><a href="NewProtocolPlugins#ImplementTransStMachine">One Way to Implement a Transaction State Machine</a></li>
+<li><a href="NewProtocolPlugins#ProcTypicalTransaction">Processing a Typical Transaction</a></li>
+</ul>
+<p>The new protocol APIs enable you to extend Traffic Server to be a
+web proxy for any protocol. This chapter describes new protocol
+APIs and the plugins that support new protocols. It also provides a
+detailed review of code for a sample Protocol plugin that supports
+a very simple artificial HTTP-like protocol.</p>
+<h2 id="about_the_sample_protocol">About the Sample Protocol</h2>
+<p>The sample protocol enables a client to ask a server for a file.
+Clients send requests to a specific Traffic Server port (specified
+in <code>plugin.config</code>); each request has the following structure:</p>
+<p><strong><code>server_name file_namenn</code></strong></p>
+<p>Using the Protocol plugin, Traffic Server can accept these
+requests, parse them, and act as a proxy cache (i.e., request the
+file from the origin server on the client's behalf and store copies
+of response messages in cache). The Protocol plugin is a state
+machine that flows through the states illustrated in the
+<a href="NewProtocolPlugins#Fig_SampleProtocolStDiag" title="Figure 6.1. Sample Protocol State Diagram">Sample Protocol State Diagram</a>.
+This figure illustrates the steps that Traffic Server and the
+Protocol plugin go through in order to support the sample
+protocol.</p>
+<p>In more specific terms, Traffic Server and the Protocol plugin
+must:</p>
+<ul>
+<li>
+<p>Listen for and accept client connections (on the accept port
+ specified in <code>plugin.config</code>)</p>
+</li>
+<li>
+<p>Read incoming client requests</p>
+</li>
+<li>
+<p>Look up the requested content in the Traffic Server cache</p>
+</li>
+<li>
+<p>Serve content from cache if the request is a cache hit (this
+ simple example does not do freshness checking)</p>
+</li>
+<li>
+<p>Open a connection to the origin server if the request is a
+ cache miss (on the server port specified in <code>plugin.config</code>)</p>
+</li>
+<li>
+<p>Forward the request to the origin server</p>
+</li>
+<li>
+<p>Receive the origin server response</p>
+</li>
+<li>
+<p>Cache the response and send it on to the client</p>
+</li>
+</ul>
+<p><strong>Figure 6.1. Sample Protocol State Diagram</strong></p>
+<p><img alt="Sample Protocol State Diagram" src="images/Protocol_state_diagram.jpg" /></p>
+<h3 id="protocol_plugin_structure">Protocol Plugin Structure</h3>
+<p>To see how the Protocol plugin works, you need to understand some
+broader concepts. This section assumes you're familiar with the
+concepts of <strong>continuation</strong>, Traffic Server's
+<strong>asynchronous event model</strong>, and basic Traffic Server
+<strong>plugin structure</strong>. If you are not familiar with these concepts,
+then reference <a href="GetingStarted#GettingStarted">Getting Started</a>
+and
+<a href="CreatingTSPlugins" title="Chapter 2. How to Create Traffic Server Plugins">How to Create Traffic Server Plugins</a>.</p>
+<h3 id="continuations_in_the_protocol_plugin">Continuations in the Protocol Plugin</h3>
+<p>The Protocol plugin creates a static continuation that is an
+*"<strong>*accept" state machine</strong> - that is, a state machine whose job
+is to accept client connections on the appropriate port. When
+Traffic Server accepts a net connection from a client on that port,
+the accept state machine is activated. It then creates a new
+continuation: a transaction state machine. The accept state machine
+creates one transaction state machine for each transaction (where a
+<strong>transaction</strong> consists of a client request and Traffic Server's
+response). Each transaction state machine lives until the
+transaction completes; then it is destroyed. If the client's
+request for content is a cache miss, then a transaction state
+machine might need to open a connection to the origin server. This
+is illustrated in the
+<a href="NewProtocolPlugins#Fig_ProtocolPluginOverview" title="Figure 6.2. Protocol Plugin Overview">Protocol Plugin Overview</a>
+diagram below.</p>
+<p><strong>Figure 6.2. Protocol Plugin Overview</strong></p>
+<p><img alt="Protocol Plugin Overview" src="images/protocol_sm_big.jpg" />
+The first steps for writing the Protocol plugin are now clear: in
+<code>INKPluginInit</code>, you must create a continuation that listens for
+net connections on the client port specified in <code>plugin.config</code>
+(this continuation is the accept state machine).</p>
+<p>Below is a summary of the continuations implemented for the
+Protocol plugin:</p>
+<ul>
+<li>
+<p>An <strong>accept state machine</strong> that listens for client
+ connections, and then creates transaction state machines whenever
+ Traffic Server accepts a new client connection. The accept state
+ machine lives as long as Traffic Server is running.</p>
+</li>
+<li>
+<p><strong>Transaction state machines</strong> that read client requests,
+ process them, and are then destroyed when the transaction is
+ finished.</p>
+</li>
+</ul>
+<h3 id="event_flow">Event Flow</h3>
+<p>Implementing the rest of the Protocol plugin requires that you
+understand the flow of events during the course of a transaction.
+Unlike HTTP transaction plugins, this plugin must read data from
+network connections and then read/write data to the Traffic Server
+cache. This means that its continuations do not receive HTTP state
+machine events; they receive events from Traffic Server's processor
+subsystems. For example: the accept state machine is activated by
+an <code>INK_EVENT_NET_ACCEPT</code> event from Traffic Server's Net
+Processor; the handler function for the accept state machine must
+therefore be able to handle that event.</p>
+<p>The transaction state machines are activated when the client
+connection receives incoming request data. The <strong>Net Processor</strong>
+notifies the transaction state machine of incoming data. The
+transaction state machine reads the data; when finished, it
+initiates a cache lookup of the requested file. When the cache
+lookup completes, the transaction state machine is activated by the
+Traffic Server <strong>Cache Processor</strong>.</p>
+<p>If the transaction state machine needs to open a connection to the
+origin server to fetch content (in the case of a cache miss), then
+the transaction state machine initiates a DNS lookup of the server
+name. The transaction state machine is activated by a DNS lookup
+event from the Traffic Server <strong>Host Database Processor</strong>. If the
+transaction must connect to the origin server, then the transaction
+state machine initiates a net connection and waits for an event
+from the Net Processor.</p>
+<p><strong>Figure 6.3. Protocol Plugin Flow of Events</strong></p>
+<p><img alt="Protocol Plugin Flow of Events" src="images/protocol_evt.jpg" />
+The flow of events is illustrated in the
+<a href="NewProtocolPlugins#Fig_ProtocolPluginFlow" title="Figure 6.3. Protocol Plugin Flow of Events">Protocol Plugin Flow of Events</a>
+diagram above. The thin straight lines show Net Processor event
+flow, the thin dashed lines represent Host Database event flow, and
+the thick dashed lines show Cache event flow.</p>
+<p>Notice that this flow of events is independent of the Protocol
+plugin's design (i.e., whether you build <strong>accept</strong> or
+<strong>transaction</strong> state machines). Any plugin that supports network
+connections uses the net vconnection interfaces (<code>INKNetAccept</code>,
+<code>INKNetConnect</code>) and thus receives events from the Net Processor.
+Any plugin that performs cache lookups or cache writes uses
+<code>INKCacheRead</code>, <code>INKCacheWrite</code>, <code>INKVConnRead</code>, and
+<code>INKVConnWrite</code> and thus receives events from the Cache Processor
+and Traffic Server event system. Similarly, any plugin that does
+DNS lookups receives events from the Host Database Processor.</p>
+<h3 id="one_way_to_implement_a_transaction_state_machine">One Way to Implement a Transaction State Machine</h3>
+<p><strong>Transaction state machines</strong> (<strong>TSMs</strong>) in the Protocol plugin
+must do the following:</p>
+<ul>
+<li>
+<p>Keep track of the state of the transaction</p>
+</li>
+<li>
+<p>Handle events received (based on the state of the transaction
+ and the event received)</p>
+</li>
+<li>
+<p>Update the state of the transaction as it changes</p>
+</li>
+</ul>
+<p>Below is one way you can implement TSMs. Details about how the
+Protocol plugin does this are provided in the next section.</p>
+<ul>
+<li>
+<p>Create a data structure for transactions that contains all of
+ the state data you need to keep track of. In the Protocol plugin
+ this is a struct, <code>Txn_SM</code>.</p>
+</li>
+<li>
+<p>When you create the TSM's continuation, initialize data of type
+ <code>Txn_SM</code>. Initialize the data to the initial state of a transaction
+ (in this case, a net connection has just been accepted). Associate
+ this data to the TSM continuation using <code>INKContDataSet</code>.</p>
+</li>
+<li>
+<p>Write state handler functions that handle the expected events
+ for each state.</p>
+</li>
+<li>
+<p>Write the handler for the TSM. Its job is to receive events,
+ examine the current state, and execute the appropriate state
+ handler function. In the Protocol plugin, the handler is
+ <code>main_handler</code>. <code>main_handler</code> calls the state handler functions to
+ handle each state.</p>
+</li>
+</ul>
+<p>The steps below describe the flow of execution illustrated in
+<a href="NewProtocolPlugins#Fig_ImplementTransStMachine" title="Figure 6.4. How Transaction State Machines are Implemented in the
+ Protocol Plugin">"How Transaction State Machines are Implemented in the Protocol Plugin"</a>.</p>
+<ol>
+<li>
+<p>The handler for the TSM, (called <code><b>main_handler</b></code> in the
+ Protocol plugin) receives events from the TSM.</p>
+</li>
+<li>
+<p><code><b>main_handler</b></code> examines the state of the transaction-in
+ particular, it examines the current handler.</p>
+</li>
+<li>
+<p><code><b>main_handler</b></code> calls the <code><b>current_handler</b></code> (which
+ is one of the state handler functions), and then passes the current
+ event to <code><b>current_handler</b></code>. <br />
+ In
+ <a href="NewProtocolPlugins#Fig_ImplementTransStMachine" title="Figure 6.4. How Transaction State Machines are Implemented in the
+ Protocol Plugin">Figure 6.4</a>
+ below, the current handler is called <code><b>state2_handler</b></code>.</p>
+</li>
+<li>
+<p>The <code><b>current_handler</b></code> handles the event and updates the
+ data. <br />
+ In
+ <a href="NewProtocolPlugins#Fig_ImplementTransStMachine" title="Figure 6.4. How Transaction State Machines are Implemented in the
+ Protocol Plugin">Figure 6.4</a>
+ below, the state is changed from <code><b>state2</b></code> to <code><b>state3</b></code>
+ (and the current handler is changed from <code><b>state2_handler</b></code> to
+ <code><b>state3_handler</b></code>).<br />
+ The next time <code><b>main_handler</b></code> receives an event, it will be
+ processed by <code><b>state3_handler</b></code>.</p>
+</li>
+<li>
+<p><code><b>state2_handler</b></code> arranges the next callback of the TSM.
+ Typically, it gives Traffic Server additional work to do (such as
+ writing a file to cache)so that it can progress to the next
+ state.<br />
+ The TSM (<code><b>main_handler</b></code>) then waits for the next event to
+ arrive from Traffic Server.</p>
+</li>
+</ol>
+<p><strong>Figure 6.4. How Transaction State Machines are Implemented in the Protocol Plugin</strong></p>
+<p><img alt="How Transaction State Machines are Implemented in the Protocol Plugin" src="images/txn_sm.jpg" /></p>
+<h3 id="processing_a_typical_transaction">Processing a Typical Transaction</h3>
+<p>The code is contained in the following files:</p>
+<ul>
+<li>
+<p><code>Protocol.c</code> and <code>Protocol.h</code></p>
+</li>
+<li>
+<p><code>Accept.c</code> and <code>Accept.h</code></p>
+</li>
+<li>
+<p><code>TxnSM.c</code> and <code>TxnSM.h</code></p>
+</li>
+</ul>
+<p>Below is a step-by-step walk-through of the code that processes a
+typical transaction.</p>
+<ol>
+<li>
+<p>The <code>INKPluginInit</code> function is in the <code>Protocol.c</code> file. It
+ checks the validity of the <code>plugin.config</code> entries (there must be
+ two: a client accept port and a server port) and runs an
+ initialization routine, <code>init</code>.</p>
+</li>
+<li>
+<p>The <code><b>init</b></code> function (in <code>Protocol.c</code>) creates the
+ plugin's log file using <code><b>INKTextLogObjectCreate</b></code>.</p>
+</li>
+<li>
+<p>The <code><b>init</b></code> function creates the accept state machine
+ using <code><b>AcceptCreate</b></code>. The code for <code><b>AcceptCreate</b></code> is
+ in the <code>Accept.c</code> file.</p>
+</li>
+<li>
+<p>The accept state machine, like the transaction state machine,
+ keeps track of its state with a data structure. This data
+ structure, <code><b>Accept</b></code>, is defined in the <code>Accept.h</code> file.
+ State data in <code><b>AcceptCreate</b></code> is associated with the new
+ accept state machine via <code><b>INKContDataSet</b></code>.</p>
+</li>
+<li>
+<p>The <code><b>init</b></code> function arranges the callback of the accept
+ state machine when there is a network connection by using
+ <code><b>INKNetAccept</b></code>.</p>
+</li>
+<li>
+<p>The handler for the accept state machine is
+ <code><b>accept_event</b></code> in the <code>Accept.c</code> file. When Traffic Server's
+ Net Processor sends <code><b>INK_EVENT_NET_ACCEPT</b></code> to the accept
+ state machine, <code><b>accept_event</b></code> creates a transaction state
+ machine (<code><b>txn_sm</b></code>) by calling <code><b>TxnSMCreate</b></code>. <br />
+ Notice that <code><b>accept_event</b></code> creates a mutex for the
+ transaction state machine, since each transaction state machine has
+ its own mutex.</p>
+</li>
+<li>
+<p>The <code><b>TxnSMCreate</b></code> function is in the <code>TxnSM.c</code> file. The
+ first thing it does is initialize the transaction's data, which is
+ of type <code>TxnSM</code> (as defined in <code>TxnSM.h</code>). <br />
+ Notice that the current handler (<code><b>q_current_handler</b></code>) is set
+ to <code><b>state_start</b></code>.</p>
+</li>
+<li>
+<p><code><b>TxnSMCreate</b></code> then creates a transaction state machine
+ using <code><b>INKContCreate</b></code>. The handler for the transaction state
+ machine is <code><b>main_handler</b></code>, which is in the <code>TxnSM.c</code> file.</p>
+</li>
+<li>
+<p>When <code><b>accept_event</b></code> receives
+ <code><b>INK_EVENT_NET_ACCEPT</b></code>, it calls the transaction state
+ machine ( <code><b>INKContCall</b></code><strong>(<code>txn_sm, 0, NULL);</code></strong>
+ ). The event passed to <code><b>main_handler</b></code> is <code>0</code>
+ (<code><b>INK_EVENT_NONE</b></code>).</p>
+</li>
+<li>
+<p>The first thing <code><b>main_handler</b></code> does is examine the
+ current <code><b>txn_sm</b></code> state by calling <code><b>INKContDataGet</b></code>.
+ The state is <code><b>state_start</b></code>.</p>
+</li>
+<li>
+<p><code><b>main_handler</b></code> then invokes the handler for
+ <code><b>state_start</b></code> by using the function pointer
+ <code><b>TxnSMHandler</b></code> (as defined in <code>TxnSM.h</code>).</p>
+</li>
+<li>
+<p>The <code><b>state_start</b></code> handler function (in the <code>TxnSM.c</code>
+ file) is handed an event (at this stage, the event is
+ <code><b>INK_EVENT_NET_ACCEPT</b></code>) and a client vconnection. <br />
+<code><b>state_start</b></code> checks to see if this client vconnection is
+ closed; if it is not, then <code><b>state_start</b></code> attempts to read
+ data from the client vconnection into an <code><b>INKIOBuffer</b></code>
+ (<code><b>state_start</b></code> is handling the event it receives).</p>
+</li>
+<li>
+<p><code><b>state_start</b></code> changes the current handler to
+ <code><b>state_interface_with_client</b></code> (that is, it updates the state
+ of the transaction to the next state).</p>
+</li>
+<li>
+<p><code><b>state_start</b></code> initiates a read of the client vconnection
+ (arranges for Traffic Server to send
+ <code><b>INK_EVENT_VCONN_READ_READY</b></code> events to the TSM) by calling
+ <code><b>INKVConnRead</b></code>.</p>
+</li>
+<li>
+<p><code><b>state_interface_with_client</b></code> is activated by the next
+ event from Traffic Server. It checks for errors and examines the
+ read VIO for the read operation initiated by
+ <code><b>INKVConnRead</b></code>.</p>
+</li>
+<li>
+<p>If the read VIO is the <code><b>client_read_VIO</b></code> (which we are
+ expecting at this stage in the transaction), then
+ <code><b>state_interface_with_client</b></code> updates the state to
+ <code><b>state_read_request_from_client</b></code> .</p>
+</li>
+<li>
+<p><code><b>state_read_request_from_client</b></code> handles actual
+ <code><b>INK_EVENT_READ_READY</b></code> events and reads the client request.</p>
+</li>
+<li>
+<p><code><b>state_read_request_from_client</b></code> parses the client
+ request.</p>
+</li>
+<li>
+<p><code><b>state_read_request_from_client</b></code> updates the current
+ state to the next state, <code><b>state_handle_cache_lookup</b></code> .</p>
+</li>
+<li>
+<p><code><b>state_read_request_from_client</b></code> arranges for Traffic
+ Server to call back the TSM with the next set of events (initiating
+ the cache lookup) by calling <code><b>INKCacheRead</b></code>.</p>
+</li>
+<li>
+<p>When the <code><b>INKCacheRead</b></code> sends the TSM either
+ <code><b>INK_EVENT_OPEN_READ</b></code> (a cache hit) or
+ <code><b>INK_EVENT_OPEN_READ_FAILED</b></code> (a cache miss),
+ <code><b>main_handler</b></code> calls <code><b>state_handle_cache_lookup</b></code>.</p>
+</li>
+</ol>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/OtherDeprecatedFunctions.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/OtherDeprecatedFunctions.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/OtherDeprecatedFunctions.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/OtherDeprecatedFunctions.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,49 @@
<html>
<!-- This template is for the bulk of the site! -->
<head>
+ <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- 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. -->
</head>
<body>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
<div id="content">
-
+ <p><a href="App_DeprecatedFunctions">Prev</a> - Appendix B. Deprecated Fxns
+- MIME Header Fxns
+Deprecated IO Buffer Interface Fxns-
+<a href="Dep_IOBufferInterface">Next</a></p>
+<h2 id="other_deprecated_functions">Other Deprecated Functions</h2>
+<p><strong>Table Of Contents</strong></p>
+<hr />
+<p><a href="OtherDeprecatedFunctions#Dep_StatisticFunctions">Statistics Functions</a>
+- <a href="OtherDeprecatedFunctions#INKStatFloatRead">INKStatFloatRead</a>
+- <a href="OtherDeprecatedFunctions#INKStatIntRead">INKStatIntRead</a></p>
+<p><a href="Dep_IOBufferInterface">IO Buffer Interface Functions</a>
+- <a href="Dep_IOBufferInterface#INKIOBufferAppend">INKIOBufferAppend</a>
+- <a href="Dep_IOBufferInterface#INKIOBufferBlockCreate">INKIOBufferBlockCreate</a>
+- <a href="Dep_IOBufferInterface#INKIOBufferDataCreate">INKIOBufferDataCreate</a></p>
+<p><a href="Dep_MutexFunctions">Mutex Functions</a>
+- <a href="Dep_MutexFunctions#INKMutexTryLock">INKMutexTryLock</a></p>
+<h3 id="deprecated_statistics_functions">Deprecated Statistics Functions</h3>
+<hr />
+<p><a href="OtherDeprecatedFunctions#INKStatFloatRead">INKStatFloatRead</a>
+<a href="OtherDeprecatedFunctions#INKStatIntRead">INKStatIntRead</a></p>
+<h4 id="inkstatfloatread">INKStatFloatRead</h4>
+<p>Obtains the value of a float statistic. This API has been succeeded
+by <code>INKStatFloatGet</code>.</p>
+<p><strong>Prototype</strong>
+ ~ <code>float INKStatFloat(INKStat <em class="replaceable"><code>the_stat</code>
+ )</p>
+<h4 id="inkstatintread">INKStatIntRead</h4>
+<p>Obtains the value of an integer statistic. This API has been
+succeeded by <code>INKStatIntGet</code>.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INK64 INKStatIntRead(INKStat <em class="replaceable"><code>the_stat</code>
+ )</p>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/PluginConfigurationFunctions.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/PluginConfigurationFunctions.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/PluginConfigurationFunctions.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/PluginConfigurationFunctions.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,36 @@
<html>
<!-- This template is for the bulk of the site! -->
<head>
+ <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- 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. -->
</head>
<body>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
<div id="content">
-
+ <p><a href="INKContSchedule">Prev</a> - INKContSchedule
+INKConfigGet - <a href="INKConfigGet">Next</a></p>
+<h2 id="plugin_configuration_functions">Plugin Configuration Functions</h2>
+<hr />
+<p><a href="PluginConfigurationFunctions#INKConfigDataGet">INKConfigDataGet</a>
+<a href="INKConfigGet">INKConfigGet</a>
+<a href="INKConfigRelease">INKConfigRelease</a>
+<a href="INKConfigSet">INKConfigSet</a></p>
+<h3 id="inkconfigdataget">INKConfigDataGet</h3>
+<p>Gets configuration data.</p>
+<p><strong>Prototype</strong>
+ ~ <code>void* INKConfigDataGet (INKConfig <em class="replaceable"><code>configp</code>)</p>
+<p><strong>Description</strong>
+ ~ Retrieves the data pointer from within the configuration
+ pointer <code><em class="replaceable"><code>configp</code>. Before using
+ <code>INKConfigDataGet</code>, you must give the configuration data an
+ identifier with <code>INKConfigSet</code> and then retrieve the <code>INKConfig</code>
+ pointer <code><em class="replaceable"><code>configp</code> with a call to
+ <code>INKConfigGet</code> (see the code snippet in the previous section).</p>
</div>
<div id="footer">