You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by di...@apache.org on 2010/03/09 01:20:27 UTC
svn commit: r920583 -
/incubator/trafficserver/site/trunk/docs/v2/sdk/NewProtocolPlugins.html
Author: dianes
Date: Tue Mar 9 00:20:26 2010
New Revision: 920583
URL: http://svn.apache.org/viewvc?rev=920583&view=rev
Log:
Edits & formatting previously overlooked
Modified:
incubator/trafficserver/site/trunk/docs/v2/sdk/NewProtocolPlugins.html
Modified: incubator/trafficserver/site/trunk/docs/v2/sdk/NewProtocolPlugins.html
URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/v2/sdk/NewProtocolPlugins.html?rev=920583&r1=920582&r2=920583&view=diff
==============================================================================
--- incubator/trafficserver/site/trunk/docs/v2/sdk/NewProtocolPlugins.html (original)
+++ incubator/trafficserver/site/trunk/docs/v2/sdk/NewProtocolPlugins.html Tue Mar 9 00:20:26 2010
@@ -55,7 +55,7 @@
cache</p></li>
<li>
<p>Serve content from cache if the request is a cache hit
- (this simple example does <i>not</i> do freshness checking)</p></li>
+ (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>
@@ -81,17 +81,17 @@
<div class="titlepage"><div><div><h3 class="title">
<a name="ContinuationsInProtocolPlugin"></a>Continuations in the Protocol Plugin</h3></div></div></div>
<p>The Protocol plugin creates a static continuation that is an
- <i>âacceptâ state machine</i> - that is, a state machine whose job is to accept client
+ <i>â</i><b>acceptâ state machine</b> - 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 <i>transaction</i> consists of a client
+ machine for each transaction (where a <b>transaction</b> 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.html#Fig_ProtocolPluginOverview" title="Figure 6.2. Protocol Plugin Overview">Protocol Plugin Overview</a> diagram.</p>
+ illustrated in the <a href="NewProtocolPlugins.html#Fig_ProtocolPluginOverview" title="Figure 6.2. Protocol Plugin Overview">Protocol Plugin Overview</a> diagram below.</p>
<div class="figure">
<a name="Fig_ProtocolPluginOverview"></a><p class="title"><b>Figure 6.2. Protocol Plugin Overview</b></p>
<div class="mediaobject"><img src="images/protocol_sm_big.jpg" alt="Protocol Plugin Overview" /></div>
@@ -104,14 +104,14 @@
Protocol plugin:</p>
<div class="itemizedlist"><ul type="disc">
<li>
- <p>An accept state machine that listens for client connections,
+ <p>An <b>accept state machine</b> 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>Transaction state machines that read client requests,
- process them, and are subsequently destroyed when the transaction is
- finished.</p></li>
+ <p><b>Transaction state machines</b> that read client requests,
+ process them, and are then destroyed when the transaction is
+ finished.</p></li>
</ul></div>
</div>
<div class="section" lang="en">
@@ -125,55 +125,54 @@
HTTP state machine events; they receive events from Traffic Serverâs
processor subsystems. For example: the accept state machine is activated by an
<code class="code">INK_EVENT_NET_ACCEPT</code> event from Traffic Serverâs Net
- Processor; the handler function for the accept state machine must be
+ 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 Net Processor notifies
+ connection receives incoming request data. The <b>Net Processor</b> 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 Cache
- Processor.</p>
+ transaction state machine is activated by the Traffic Server <b>Cache
+ Processor</b>.</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 Host Database Processor.</p>
-<p>If the transaction has to connect to the origin server, then the
+ the Traffic Server <b>Host Database Processor</b>. If the transaction must connect to the origin server, then the
transaction state machine initiates a net connection and waits for an
- event from Net Processor.</p>
+ event from the Net Processor.</p>
<div class="figure">
-<a name="Fig_ProtocolPluginFlow"></a><p class="title"><b>Figure 6.3. Protocol Plugin Flow of Events</b></p>
+ <a name="Fig_ProtocolPluginFlow"></a><p class="title"><b>Figure 6.3. Protocol Plugin Flow of Events</b></p>
<div class="mediaobject"><img src="images/protocol_evt.jpg" alt="Protocol Plugin Flow of Events" /></div>
</div>
<p>The flow of events is illustrated in the <a href="NewProtocolPlugins.html#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 are Host DB event flow,
- and the thick dashed lines are Cache event flow.</p>
+ 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 <b>accept</b> or <b>transaction</b>
state machines). Any plugin that supports network connections
uses the net vconnection interfaces (<code class="code">INKNetAccept</code>,
- <code class="code">INKNetConnect</code>) and thus receives events from Net
+ <code class="code">INKNetConnect</code>) and thus receives events from the Net
Processor. Any plugin that performs cache lookups or cache writes uses
<code class="code">INKCacheRead</code>, <code class="code">INKCacheWrite</code>,
<code class="code">INKVConnRead</code>, and <code class="code">INKVConnWrite</code> and thus
- receives events from Cache Processor and the Traffic Server event
- system; similarly, any plugin that does DNS lookups receives events
- from the Host DB Processor.</p>
+ 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>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="ImplementTransStMachine"></a>One Way to Implement a Transaction State Machine</h3></div></div></div>
-<p>The <b>transaction state machines</b> (<b>TSM</b>s) in the Protocol plugin
+<p><b>Transaction state machines</b> (<b>TSMs</b>) in the Protocol plugin
must do the following: </p>
<div class="itemizedlist"><ul type="disc">
<li><p>Keep track of the state of the transaction</p></li>
<li>
- <p>Handle the events received (based on the state of the
+ <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></div>
-<p>Below is one way you can implement TSMs (details on how the
- Protocol plugin does this appear in the next section):</p>
+<p>Below is one way you can implement TSMs. Details about how the
+ Protocol plugin does this are provided in the next section.</p>
<div class="itemizedlist"><ul type="disc">
<li><p>Create a data structure for transactions that contains all
of the state data you need to keep track of. In the Protocol
@@ -191,9 +190,9 @@
<code class="code">main_handler</code>. <code class="code">main_handler</code> calls the
state handler functions to handle each state.</p></li>
</ul></div>
-<p>The flow of execution is illustrated in <a href="NewProtocolPlugins.html#Fig_ImplementTransStMachine" title="Figure 6.4. How Transaction State Machines are Implemented in the
- Protocol Plugin">Figure 6.4, âHow Transaction State Machines are Implemented in the
- Protocol Pluginâ</a>.</p>
+<p>The steps below describe the flow of execution illustrated in <a href="NewProtocolPlugins.html#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>
<div class="orderedlist"><ol type="1">
<li>
<p>The handler for the TSM, (called <code class="code"><b>main_handler</b></code>
@@ -224,11 +223,7 @@
The TSM (<code class="code"><b>main_handler</b></code>) then waits for the
next event to arrive from Traffic Server.</p></li>
</ol></div>
-<p>The implementation above is diagrammed below in <a href="NewProtocolPlugins.html#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>. Additional details are provided in
- the next section, which provides a walk through the processing of a typical
- transaction.</p>
+
<div class="figure">
<a name="Fig_ImplementTransStMachine"></a><p class="title"><b>Figure 6.4. How Transaction State Machines are Implemented in the
Protocol Plugin</b></p>
@@ -247,118 +242,119 @@
<li><p><code class="filename">TxnSM.c</code> and
<code class="filename">TxnSM.h</code></p></li>
</ul></div>
-<p>Below is a step-by-step walk-through of the code.</p>
+<p>Below is a step-by-step walk-through of the code that processes a typical transaction.</p>
<div class="orderedlist"><ol type="1">
<li>
- <p>The <code class="function">INKPluginInit</code> function is in
- <code class="filename">Protocol.c</code>. It checks the validity of the
- <code>plugin.confi</code>g entries (there must be two: a client accept port and
+ <p>The <code class="function">INKPluginInit</code> function is in the
+ <code class="filename">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 class="function">init</code>.</p></li>
-<li><p>The <code class="function">init</code> function (in
+<li><p>The <code class="function"><b>init</b></code> function (in
<code class="filename">Protocol.c</code>) creates the pluginâs log file
- using <code class="code">INKTextLogObjectCreate</code>.</p></li>
-<li><p>The <code class="function">init</code> function creates the accept
- state machine using <code class="code">AcceptCreate</code>. The code for
- <code class="code">AcceptCreate</code> is in
- <code class="filename">Accept.c</code>.</p></li>
+ using <code class="code"><b>INKTextLogObjectCreate</b></code>.</p></li>
+<li>
+ <p>The <code class="function"><b>init</b></code> function creates the accept
+ state machine using <code class="code"><b>AcceptCreate</b></code>. The code for
+ <code class="code"><b>AcceptCreate</b></code> is in the
+ <code class="filename">Accept.c</code> file.</p></li>
<li>
<p>The accept state machine, like the transaction state
- machine, keeps track of its state via a data structure. This data
- structure, Accept, is defined in <code class="filename">Accept.h</code>. In
- <code class="code">AcceptCreate</code>, state data is associated with the new
- accept state machine using <code class="code">INKContDataSet</code>.</p></li>
+ machine, keeps track of its state with a data structure. This data
+ structure, <code><b>Accept</b></code>, is defined in the <code class="filename">Accept.h</code> file. State data in <code><b>AcceptCreate</b></code> is associated with the new
+ accept state machine via <code class="code"><b>INKContDataSet</b></code>.</p></li>
<li>
- <p>The <code class="function">init</code> function arranges the callback
+ <p>The <code class="function"><b>init</b></code> function arranges the callback
of the accept state machine when there is a network connection
- by using <code class="code">INKNetAccept</code>.</p></li>
+ by using <code class="code"><b>INKNetAccept</b></code>.</p></li>
<li>
<p>The handler for the accept state machine is
- <code class="function">accept_event</code> in
- <code class="filename">Accept.c</code>. When Traffic Serverâs Net Processor
- sends <code class="code">INK_EVENT_NET_ACCEPT</code> to the accept state
- machine, <code class="function">accept_event</code> creates a transaction
- state machine (<code class="code">txn_sm</code>) by calling
- <code class="code">TxnSMCreate</code>. <br />
+ <code class="function"><b>accept_event</b></code> in the
+ <code class="filename">Accept.c</code> file. When Traffic Serverâs Net Processor
+ sends <code class="code"><b>INK_EVENT_NET_ACCEPT</b></code> to the accept state
+ machine, <code class="function"><b>accept_event</b></code> creates a transaction
+ state machine (<code class="code"><b>txn_sm</b></code>) by calling
+ <code class="code"><b>TxnSMCreate</b></code>. <br />
Notice that
- <code class="function">accept_event</code> creates a mutex for the
- transaction state machine, as each transaction state machine has its
+ <code class="function"><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 class="function">TxnSMCreate</code> function is in
- <code class="filename">TxnSM.c</code>. The first thing it does is
+ <p>The <code class="function"><b>TxnSMCreate</b></code> function is in the
+ <code class="filename">TxnSM.c</code> file. The first thing it does is
initialize the transactionâs data, which is of type
- <code class="code">TxnSM</code> (defined in <code class="filename">TxnSM.h</code>).
- <br />Notice that the current handler (<code class="code">q_current_handler</code>)
- is set to <code class="code">state_start</code>.</p></li>
-<li>
- <p><code class="function">TxnSMCreate</code> then creates a transaction
- state machine using <code class="code">INKContCreate</code>. The handler for
- the transaction state machine is <code class="code">main_handler</code>, which is in <code class="filename">TxnSM.c</code></p>
+ <code class="code">TxnSM</code> (as defined in <code class="filename">TxnSM.h</code>).
+ <br />Notice that the current handler (<code class="code"><b>q_current_handler</b></code>)
+ is set to <code class="code"><b>state_start</b></code>.</p></li>
+<li>
+ <p><code class="function"><b>TxnSMCreate</b></code> then creates a transaction
+ state machine using <code class="code"><b>INKContCreate</b></code>. The handler for
+ the transaction state machine is <code class="code"><b>main_handler</b></code>, which is in the <code class="filename">TxnSM.c</code> file.</p>
</li>
-<li><p>When <code class="function">accept_event</code> receives
- <code class="code">INK_EVENT_NET_ACCEPT</code>, it calls the transaction state
- machine (<code class="code">INKContCall</code> (<code class="code">txn_sm, 0,
- NULL);</code>). The event passed to
- <code class="function">main_handler</code> is 0
- (<code class="code">INK_EVENT_NONE</code>).</p></li>
-<li><p>The first thing <code class="function">main_handler</code> does is
- examine the current <code class="code">txn_sm</code> state by calling
- <code class="code">INKContDataGet</code>. The state is
- <code class="code">state_start</code>.</p></li>
-<li>
- <p><code class="code">main_handler</code> then invokes the handler for
- <code>state_start</code> by using the function pointer <code class="function">TxnSMHandler</code> (defined in
- <code class="filename">TxnSM.h</code>).</p></li>
-<li>
- <p>The <code class="function">state_start</code> handler function (in
- <code class="filename">TxnSM.c</code>) is handed an event (at this stage,
- the event is <code class="code">INK_EVENT_NET_ACCEPT</code>) and a client
+<li>
+ <p>When <code class="function"><b>accept_event</b></code> receives
+ <code class="code"><b>INK_EVENT_NET_ACCEPT</b></code>, it calls the transaction state
+ machine ( <code class="code"><b>INKContCall</b></code><b> (<code class="code">txn_sm, 0,
+ NULL);</code></b> ). The event passed to
+ <code class="function"><b>main_handler</b></code> is <code>0</code> (<code class="code"><b>INK_EVENT_NONE</b></code>).</p></li>
+<li><p>The first thing <code class="function"><b>main_handler</b></code> does is
+ examine the current <code class="code"><b>txn_sm</b></code> state by calling
+ <code class="code"><b>INKContDataGet</b></code>. The state is
+ <code class="code"><b>state_start</b></code>.</p></li>
+<li>
+ <p><code class="code"><b>main_handler</b></code> then invokes the handler for
+ <code><b>state_start</b></code> by using the function pointer <code class="function"><b>TxnSMHandler</b></code> (as defined in
+ <code class="filename">TxnSM.h</code>).</p></li>
+<li>
+ <p>The <code class="function"><b>state_start</b></code> handler function (in the
+ <code class="filename">TxnSM.c</code> file) is handed an event (at this stage,
+ the event is <code class="code"><b>INK_EVENT_NET_ACCEPT</b></code>) and a client
vconnection. <br />
- <code class="function">state_start</code> checks to see if
+ <code class="function"><b>state_start</b></code> checks to see if
this client vconnection is closed; if it is not, then
- <code class="function">state_start</code> attempts to read data from the
- client vconnection into an <code class="code">INKIOBuffer</code> (<code class="function">state_start</code> is handling the event it
+ <code class="function"><b>state_start</b></code> attempts to read data from the
+ client vconnection into an <code class="code"><b>INKIOBuffer</b></code> (<code class="function"><b>state_start</b></code> is handling the event it
receives).</p></li>
<li>
- <p><code class="function">state_start</code> changes the current handler
- to <code class="function">state_interface_with_client</code> (i.e., it updates the
- state of the transaction to the next state).</p></li>
+ <p><code class="function"><b>state_start</b></code> changes the current handler
+ to <code class="function"><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 class="function">state_start</code> initiates a read of the
+ <p><code class="function"><b>state_start</b></code> initiates a read of the
client vconnection (arranges for Traffic Server to send
- <code class="code">INK_EVENT_VCONN_READ_READY</code> events to the TSM) by
- calling <code class="code">INKVConnRead</code>.</p></li>
+ <code class="code"><b>INK_EVENT_VCONN_READ_READY</b></code> events to the TSM) by
+ calling <code class="code"><b>INKVConnRead</b></code>.</p></li>
<li>
- <p><code class="function">state_interface_with_client</code> is
+ <p><code class="function"><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 class="code">INKVConnRead</code>.</p></li>
+ by <code class="code"><b>INKVConnRead</b></code>.</p></li>
<li>
- <p>If the read VIO is the <code class="code">client_read_VIO</code> (which
+ <p>If the read VIO is the <code class="code"><b>client_read_VIO</b></code> (which
we are expecting at this stage in the transaction), then
- <code class="function">state_interface_with_client</code> updates the state
- to <code class="function">state_read_request_from_client</code></p></li>
+ <code class="function"><b>state_interface_with_client</b></code> updates the state
+ to <code class="function"><b>state_read_request_from_client</b></code> .</p></li>
+<li>
+ <p><code class="function"><b>state_read_request_from_client</b></code> handles
+ actual <code class="code"><b>INK_EVENT_READ_READY</b></code> events and reads the
+ client request.</p></li>
+<li>
+ <p><code class="function"><b>state_read_request_from_client</b></code> parses
+ the client request.</p></li>
<li>
- <p><code class="function">state_read_request_from_client</code> handles
- actual <code class="code">INK_EVENT_READ_READY</code> events and reads the
- client request.</p></li>
-<li>
- <p><code class="function">state_read_request_from_client</code> parses
- the client request.</p></li>
-<li><p><code class="function">state_read_request_from_client</code> updates
- the state to the next state,
- <code class="function">state_handle_cache_lookup</code>.</p></li>
+ <p><code class="function"><b>state_read_request_from_client</b></code> updates
+ the current state to the next state,
+ <code class="function"><b>state_handle_cache_lookup</b></code> .</p></li>
<li>
- <p><code class="function">state_read_request_from_client</code> arranges
+ <p><code class="function"><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 class="code">INKCacheRead</code>.</p></li>
+ <code class="code"><b>INKCacheRead</b></code>.</p></li>
<li>
- <p>When the <code class="code">INKCacheRead</code> sends the TSM either
- <code class="code">INK_EVENT_OPEN_READ</code> (a cache hit) or
- <code class="code">INK_EVENT_OPEN_READ_FAILED</code> (a cache miss),
- <code class="function">main_handler</code> calls
- <code class="function">state_handle_cache_lookup</code>.</p></li>
+ <p>When the <code class="code"><b>INKCacheRead</b></code> sends the TSM either
+ <code class="code"><b>INK_EVENT_OPEN_READ</b></code> (a cache hit) or
+ <code class="code"><b>INK_EVENT_OPEN_READ_FAILED</b></code> (a cache miss),
+ <code class="function"><b>main_handler</b></code> calls
+ <code class="function"><b>state_handle_cache_lookup</b></code>.</p></li>
</ol></div>
</div>
</div>