1# Licensed to the Apache Software Foundation (ASF) under one 2# or more contributor license agreements. See the NOTICE file 3# distributed with this work for additional information 4# regarding copyright ownership. The ASF licenses this file 5# to you under the Apache License, Version 2.0 (the 6# "License"); you may not use this file except in compliance 7# with the License. You may obtain a copy of the License at 8# 9# http://www.apache.org/licenses/LICENSE-2.0 10# 11# Unless required by applicable law or agreed to in writing, software 12# distributed under the License is distributed on an "AS IS" BASIS, 13# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14# See the License for the specific language governing permissions and 15# limitations under the License. 16# 17#, fuzzy 18msgid "" 19msgstr "" 20"Project-Id-Version: Apache Traffic Server 6.2\n" 21"Report-Msgid-Bugs-To: \n" 22"POT-Creation-Date: 2016-01-02 21:32+0000\n" 23"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" 24"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" 25"Language-Team: LANGUAGE <LL@li.org>\n" 26"MIME-Version: 1.0\n" 27"Content-Type: text/plain; charset=utf-8\n" 28"Content-Transfer-Encoding: 8bit\n" 29"Generated-By: Babel 2.1.1\n" 30 31#: ../../developer-guide/plugins/io/transformations.en.rst:23 32msgid "Transformations" 33msgstr "" 34 35#: ../../developer-guide/plugins/io/transformations.en.rst:26 36msgid "Vconnection Implementor's View" 37msgstr "" 38 39#: ../../developer-guide/plugins/io/transformations.en.rst:28 40msgid "" 41"A VConnection implementor writes only transformations. All other " 42"VConnections (net VConnections and cache VConnections) are implemented in " 43"iocore. As mentioned earlier, a given vconnection can have a maximum of one " 44"read operation and one write operation being performed on it. The " 45"vconnection user gets information about the operation being performed by " 46"examining the VIO returned by a call to ``TSVConnRead`` or " 47"``TSVConnWrite``. The implementor, in turn, gets a handle on the VIO " 48"operation by examining the VIO returned by ``TSVConnReadVIOGet`` or " 49"``TSVConnWriteVIOGet`` (recall that every vconnection created through the " 50"Traffic Server API has an associated read VIO and write VIO, even if it " 51"only supports reading or writing)." 52msgstr "" 53 54#: ../../developer-guide/plugins/io/transformations.en.rst:40 55msgid "" 56"For example, the null transform plugin's transformation examines the input " 57"VIO by calling:" 58msgstr "" 59 60#: ../../developer-guide/plugins/io/transformations.en.rst:47 61msgid "where ``contp`` is the transformation." 62msgstr "" 63 64#: ../../developer-guide/plugins/io/transformations.en.rst:49 65msgid "" 66"A vconnection is a continuation. This means it has a handler function that " 67"is run when an event is sent to it, or more accurately, when an event that " 68"was sent to it is received. It is the handler function's job to examine the " 69"event, the current state of its read VIO and write VIO, and any other " 70"internal state the vconnection might have and potentially make some " 71"progress on the IO operations." 72msgstr "" 73 74#: ../../developer-guide/plugins/io/transformations.en.rst:56 75msgid "" 76"It is common for the handler function for all vconnections to look similar. " 77"Their basic form looks something like the code fragment below:" 78msgstr "" 79 80#: ../../developer-guide/plugins/io/transformations.en.rst:73 81msgid "" 82"This code fragment basically shows that many vconnections simply want to " 83"destroy themselves when they are closed. However, the situation might also " 84"require the vconnection to do some cleanup processing - which is why " 85"``TSVConnClose`` does not simply just destroy the vconnection." 86msgstr "" 87 88#: ../../developer-guide/plugins/io/transformations.en.rst:78 89msgid "" 90"Vconnections are state machines that are animated by the events they " 91"receive. An event is sent to the vconnection whenever an ``TSVConnRead``, " 92"``TSVConnWrite``, ``TSVConnClose``, ``TSVConnShutdown``, or " 93"``TSVIOReenable`` call is performed. ``TSVIOReenable`` indirectly " 94"references the vconnection through a back-pointer in the VIO structure to " 95"the vconnection. The vconnection itself only knows which call was performed " 96"by examining its state and the state of its VIOs. For example, when " 97"``TSVConnClose`` is called, the vconnection is sent an immediate event " 98"(``TS_EVENT_IMMEDIATE``). For every event the vconnection receives, it " 99"needs to check its closed flag to see if it has been closed. Similarly, " 100"when ``TSVIOReenable`` is called, the vconnection is sent an immediate " 101"event. For every event the vconnection receives, it must check its VIOs to " 102"see if the buffers have been modified to a state in which it can continue " 103"processing one of its operations." 104msgstr "" 105 106#: ../../developer-guide/plugins/io/transformations.en.rst:94 107msgid "" 108"Finally, a vconnection is likely the user of other vconnections. It also " 109"receives events as the user of these other vconnections. When it receives " 110"such an event, like ``TS_EVENT_VCONN_WRITE_READY``, it might just enable " 111"another vconnection that's writing into the buffer used by the vconnection " 112"reading from it. The above description is merely intended to give the " 113"overall idea for what a vconnection needs to do." 114msgstr "" 115 116#: ../../developer-guide/plugins/io/transformations.en.rst:102 117msgid "Transformation VConnection" 118msgstr "" 119 120#: ../../developer-guide/plugins/io/transformations.en.rst:104 121msgid "" 122"A :ref:`transformation <transformations>` is a specific type of " 123"vconnection. It supports a subset of the vconnection functionality that " 124"enables one or more transformations to be chained together. A " 125"transformation sits as a bottleneck between an input data source and an " 126"output data sink, which enables it to view and modify all the data passing " 127"through it. Alternatively, some transformations simply scan the data and " 128"pass it on. A common transformation is one that compresses data in some " 129"manner." 130msgstr "" 131 132#: ../../developer-guide/plugins/io/transformations.en.rst:113 133msgid "" 134"A transformation can modify either the data stream being sent *to* an HTTP " 135"client (e.g. the document) or the data stream being sent *from* an HTTP " 136"client (e.g. post data). To do this, the transformation should hook on to " 137"one of the following hooks:" 138msgstr "" 139 140#: ../../developer-guide/plugins/io/transformations.en.rst:118 141msgid "``TS_HTTP_REQUEST_TRANSFORM_HOOK``" 142msgstr "" 143 144#: ../../developer-guide/plugins/io/transformations.en.rst:120 145msgid "``TS_HTTP_RESPONSE_TRANSFORM_HOOK``" 146msgstr "" 147 148#: ../../developer-guide/plugins/io/transformations.en.rst:122 149msgid "" 150"Note that because a transformation is intimately associated with a given " 151"transaction, it is only possible to add the hook to the transaction hooks - " 152"not to the global or session hooks. Transformations reside in a chain, so " 153"their ordering is quite easily determined: transformations that add " 154"themselves to the chain are simply appended to it." 155msgstr "" 156 157#: ../../developer-guide/plugins/io/transformations.en.rst:128 158msgid "" 159"Data is passed in to the transformation by initiating a vconnection write " 160"operation on the transformation. As a consequence of this design, a " 161"transformation must support the vconnection write operation. In other " 162"words, your transformation must expect an upstream vconnection to write " 163"data to it. The transformation has to read the data, consume it, and tell " 164"the upstream vconnection it is finished by sending it an " 165"``TS_EVENT_WRITE_COMPLETE`` event. Transformations cannot send the " 166"``TS_EVENT_VCONN_WRITE_COMPLETE`` event to the upstream vconnection unless " 167"they are finished consuming all incoming data. If " 168"``TS_EVENT_VCONN_WRITE_COMPLETE`` is sent prematurely, then certain " 169"internal Traffic Server data structures will not be deallocated, thereby " 170"causing a memory leak." 171msgstr "" 172 173#: ../../developer-guide/plugins/io/transformations.en.rst:141 174msgid "Here's how to make sure that all incoming data is consumed:" 175msgstr "" 176 177#: ../../developer-guide/plugins/io/transformations.en.rst:143 178msgid "" 179"After reading or copying data, make sure that you consume the data and " 180"increase the value of ndone for the input VIO, as in the following example " 181"taken from ``null-transform.c``:" 182msgstr "" 183 184#: ../../developer-guide/plugins/io/transformations.en.rst:156 185msgid "" 186"Before sending ``TS_EVENT_VCONN_WRITE_COMPLETE``, your transformation " 187"should check the number of bytes remaining in the upstream vconnection's " 188"write VIO (input VIO) using the function ``TSVIONTodoGet`` (``input_vio``). " 189"This value should go to zero when all of the upstream data is consumed " 190"(``TSVIONTodoGet = nbytes - ndone``). Do not send " 191"``TS_EVENT_VCONN_WRITE_COMPLETE`` events if ``TSVIONTodoGet`` is greater " 192"than zero." 193msgstr "" 194 195#: ../../developer-guide/plugins/io/transformations.en.rst:164 196msgid "" 197"The transformation passes data out of itself by using the output " 198"vconnection retrieved by ``TSTransformOutputVConnGet``. Immediately before " 199"Traffic Server initiates the write operation (which inputs data into the " 200"transformation), it sets the output vconnection either to the next " 201"transformation in the chain of transformations or to a special terminating " 202"transformation (if it's the last transformation in the chain). Since the " 203"transformation is handed ownership of the output vconnection, it must close " 204"it at some point in order for it to be deallocated." 205msgstr "" 206 207#: ../../developer-guide/plugins/io/transformations.en.rst:173 208msgid "" 209"All of the transformations in a transformation chain share the " 210"transaction's mutex. This small restriction (enforced by " 211"``TSTransformCreate``) removes many of the locking complications of " 212"implementing general vconnections. For example, a transformation does not " 213"have to grab its write VIO mutex before accessing its write VIO because it " 214"knows it already holds the mutex." 215msgstr "" 216 217#: ../../developer-guide/plugins/io/transformations.en.rst:180 218msgid "" 219"The transformation functions are: \\* :c:func:`TSTransformCreate` \\* :c:" 220"func:`TSTransformOutputVConnGet`" 221msgstr "" 222