#
# 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.
#
msgid ""
msgstr ""
"Project-Id-Version: Apache Traffic Server 4.1\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2013-11-08 17:57+0900\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"

#: ../../sdk/mutex-guide.en.rst:2
msgid "Mutex Guide"
msgstr ""

#: ../../sdk/mutex-guide.en.rst:21
msgid ""
"Mutexes are used to lock shared data. This chapter explains how to use the "
"mutex interface."
msgstr ""

#: ../../sdk/mutex-guide.en.rst:28
msgid "Mutexes"
msgstr ""

#: ../../sdk/mutex-guide.en.rst:30
msgid ""
"A **mutex** 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."
msgstr ""

#: ../../sdk/mutex-guide.en.rst:35
msgid ""
"The Traffic Server API provides two functions that attempt to access and "
"lock the data: ``InkMutexLockTry`` and ``TSMutexLock``. **``TSMutexLock``** "
"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 "
"``TSContThreadCreate``. 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 ``TSMutexLock`` is used in any case other than "
"the one recommended above, then the result will be a serious performance "
"impact."
msgstr ""

#: ../../sdk/mutex-guide.en.rst:47
msgid ""
"**``TSMutexLockTry``**, 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 ``TSMutexLock`` case. If "
"the ``TSMutexLockTry`` attempt fails, then you can schedule a future "
"attempt (which must be at least 10 milliseconds later)."
msgstr ""

#: ../../sdk/mutex-guide.en.rst:54
msgid ""
"In general, you should use ``TSMutexLockTry`` instead of ``TSMutexLock``."
msgstr ""

#: ../../sdk/mutex-guide.en.rst:57
msgid ""
"``InkMutexLockTry`` 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)."
msgstr ""

#: ../../sdk/mutex-guide.en.rst:61
msgid ""
"``InkMutexLockTry`` is required if you are making any blocking calls (such "
"as network, cache, or file IO calls)."
msgstr ""

#: ../../sdk/mutex-guide.en.rst:64
msgid ""
"``TSMutexLock`` might *not* be necessary if you are not making blocking "
"calls and if you are only accessing local resources."
msgstr ""

#: ../../sdk/mutex-guide.en.rst:67
msgid ""
"The Traffic Server API uses the ``TSMutex`` 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)."
msgstr ""

#: ../../sdk/mutex-guide.en.rst:74
msgid "Locking Global Data"
msgstr ""

#: ../../sdk/mutex-guide.en.rst:76
msgid ""
"The ``blacklist-1.c`` 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 "
"``TSPluginInit``. The ``blacklist-1.c`` code uses ``TSMutexLockTry`` "
"instead of ``InkMutexLock``. For more detailed information, see the "
"```blacklist-1.c`` <../sample-source-code#Sample_blacklist-1.c>`__ code; "
"start by looking at the ```TSPluginInit`` <http://people.apache.org/~amc/"
"ats/doc/html/ts_8h.html#a9a0b0ac9cbce9d6644f66bbe93098313>`__ function."
msgstr ""

#: ../../sdk/mutex-guide.en.rst:87
msgid "General guidelines for locking shared data are as follows:"
msgstr ""

#: ../../sdk/mutex-guide.en.rst:89
msgid ""
"Create a mutex for the shared data with ```TSMutexCreate`` <http://people."
"apache.org/~amc/ats/doc/html/ts_8h."
"html#aa4300d8888c6962a44c9e827d633e433>`__."
msgstr ""

#: ../../sdk/mutex-guide.en.rst:92
msgid ""
"Whenever you need to read or modify this data, first lock it by calling "
"```TSMutexLockTry`` <http://people.apache.org/~amc/ats/doc/html/ts_8h."
"html#ac9c08451aa529851b9474e3c035f44bb>`__; then read or modify the data."
msgstr ""

#: ../../sdk/mutex-guide.en.rst:97
msgid ""
"When you are done with the data, unlock it with ```TSMutexUnlock`` <http://"
"people.apache.org/~amc/ats/doc/html/ts_8h."
"html#afbb474c217fd5b927f1f8487c45646dd>`__. If you are unlocking data "
"accessed during the processing of an HTTP transaction, then you must unlock "
"it before calling ```TSHttpTxnReenable`` <http://people.apache.org/~amc/ats/"
"doc/html/ts_8h.html#ac367347e02709ac809994dfb21d3288a>`__."
msgstr ""

#: ../../sdk/mutex-guide.en.rst:104
msgid "Protecting a Continuation's Data"
msgstr ""

#: ../../sdk/mutex-guide.en.rst:106
msgid ""
"You must create a mutex to protect a continuation's data if it might be "
"accessed by other continuations or processes. Here's how:"
msgstr ""

#: ../../sdk/mutex-guide.en.rst:128
msgid ""
"If any other functions want to access ``contp``'s data, then it is up to "
"them to get ``contp``'s mutex (using, for example, ``TSContMutexGet``) to "
"lock it. For usage, ssee the sample Protocol plugin."
msgstr ""

#: ../../sdk/mutex-guide.en.rst:133
msgid "How to Associate a Continuation With Every HTTP Transaction"
msgstr ""

#: ../../sdk/mutex-guide.en.rst:135
msgid ""
"There could be several reasons why you'd want to create a continuation for "
"each HTTP transaction that calls back your plugin."
msgstr ""

#: ../../sdk/mutex-guide.en.rst:138
msgid "Some potential scenarios are listed below."
msgstr ""

#: ../../sdk/mutex-guide.en.rst:140
msgid ""
"You want to register hooks locally with the new continuation instead of "
"registering them globally to the continuation plugin."
msgstr ""

#: ../../sdk/mutex-guide.en.rst:143
msgid ""
"You want to store data specific to each HTTP transaction that you might "
"need to reuse across various hooks."
msgstr ""

#: ../../sdk/mutex-guide.en.rst:146
msgid ""
"You're using APIs (like ``TSHostLookup``) that will call back the "
"continuation with a certain event."
msgstr ""

#: ../../sdk/mutex-guide.en.rst:150
msgid "How to Add the New Continuation"
msgstr ""

#: ../../sdk/mutex-guide.en.rst:152
msgid ""
"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 ``TS_HTTP_TXN_START_HOOK``. Refer to the example below, which uses a "
"transaction-specific continuation called ``txn_contp``."
msgstr ""

#: ../../sdk/mutex-guide.en.rst:173
msgid ""
"In the plugin continuation handler, create the new continuation "
"``txn_contp`` and then register it to be called back at "
"``TS_HTTP_TXN_CLOSE_HOOK``:"
msgstr ""

#: ../../sdk/mutex-guide.en.rst:209
msgid ""
"Remember that the ``txn_contp`` handler must destory itself when the HTTP "
"transaction is closed. If you forget to do this, then your plugin will have "
"a memory leak."
msgstr ""

#: ../../sdk/mutex-guide.en.rst:238
msgid "How to Store Data Specific to Each HTTP Transaction"
msgstr ""

#: ../../sdk/mutex-guide.en.rst:240
msgid ""
"For the example above, store the data in the ``txn_contp`` data structure - "
"this means that you'll create your own data structure. Now suppose you want "
"to store the state of the HTTP transaction:"
msgstr ""

#: ../../sdk/mutex-guide.en.rst:251
msgid ""
"You need to allocate the memory and initialize this structure for each HTTP "
"``txnp``. You can do that in the plugin continuation handler when it is "
"called back with ``TS_EVENT_HTTP_TXN_START``"
msgstr ""

#: ../../sdk/mutex-guide.en.rst:295
msgid "For accessing this data from anywhere, use TSContDataGet:"
msgstr ""

#: ../../sdk/mutex-guide.en.rst:309
msgid "Remember to free this memory before destroying the continuation:"
msgstr ""

#: ../../sdk/mutex-guide.en.rst:343
msgid "Using Locks"
msgstr ""

#: ../../sdk/mutex-guide.en.rst:345
msgid ""
"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 ``txn_contp`` 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 ``txnp`` and ``txn_contp`` without "
"grabbing a lock. In the example above, ``txn_contp`` is created with a "
"``NULL`` mutex. This works because the HTTP transaction ``txnp`` is the "
"only one that will call back ``txn_contp``, and you are guaranteed that "
"``txn_contp`` will be called back only one hook at a time. After processing "
"is finished, ``txn_contp`` will reenable ``txnp``."
msgstr ""

#: ../../sdk/mutex-guide.en.rst:357
msgid ""
"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 ``txn_contp`` is scheduled to be called back by a processor (such as "
"the cache processor, the DNS processor, etc.). This ensures that "
"``txn_contp`` is called back sequentially and not simultaneously. In other "
"words, you need to ensure that ``txn_contp`` will not be called back by "
"both ``txnp`` 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."
msgstr ""

#: ../../sdk/mutex-guide.en.rst:368
msgid "Special Case: Continuations Created for HTTP Transactions"
msgstr ""

#: ../../sdk/mutex-guide.en.rst:370
msgid ""
"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 (``TSHttpTxn`` object) already has its own mutex."
msgstr ""

#: ../../sdk/mutex-guide.en.rst:374
msgid ""
"In the example below, it's not necessary to specify a mutex for the "
"continuation created in ``txn_handler``:"
msgstr ""

#: ../../sdk/mutex-guide.en.rst:406
msgid "The mutex functions are listed below:"
msgstr ""

#: ../../sdk/mutex-guide.en.rst:408
msgid ""
"```TSMutexCreate`` <http://people.apache.org/~amc/ats/doc/html/ts_8h."
"html#aa4300d8888c6962a44c9e827d633e433>`__"
msgstr ""

#: ../../sdk/mutex-guide.en.rst:409
msgid ""
"```TSMutexLock`` <http://people.apache.org/~amc/ats/doc/html/"
"InkIOCoreAPI_8cc.html#a306f9923bc9d3c0f417c185919531934>`__"
msgstr ""

#: ../../sdk/mutex-guide.en.rst:410
msgid ""
"```TSMutexLockTry`` <http://people.apache.org/~amc/ats/doc/html/ts_8h."
"html#ac9c08451aa529851b9474e3c035f44bb>`__"
msgstr ""
