trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jpe...@apache.org
Subject [01/11] git commit: doc: convert TSIOBufferCreate(3) to sphinx
Date Thu, 01 Aug 2013 18:58:15 GMT
Updated Branches:
  refs/heads/master 229a20956 -> cecc082d4


doc: convert TSIOBufferCreate(3) to sphinx


Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/fbe22e49
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/fbe22e49
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/fbe22e49

Branch: refs/heads/master
Commit: fbe22e49fea0d13f34eb10d3245376d7e33bdfe3
Parents: 229a209
Author: James Peach <jpeach@apache.org>
Authored: Thu Aug 1 10:12:03 2013 -0700
Committer: James Peach <jpeach@apache.org>
Committed: Thu Aug 1 10:12:03 2013 -0700

----------------------------------------------------------------------
 doc/conf.py                               |  1 +
 doc/reference/api/TSIOBufferCreate.en.rst | 91 ++++++++++++++++++++++++++
 2 files changed, 92 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/trafficserver/blob/fbe22e49/doc/conf.py
----------------------------------------------------------------------
diff --git a/doc/conf.py b/doc/conf.py
index d9eb3a1..cc449e0 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -217,6 +217,7 @@ man_pages = [
    ('reference/api/TSHttpHookAdd.en', 'TSHttpHookAdd', u'Intercept Traffic Server events',
None, u'3ts'),
    ('reference/api/TSHttpParserCreate.en', 'TSHttpParserCreate', u'Parse HTTP headers from
memory buffers', None, u'3ts'),
    ('reference/api/TSHttpTxnMilestoneGet.en', 'TSHttpTxnMilestoneGet', u'Get a specified
milestone timer value for the current transaction', None, u'3ts'),
+   ('reference/api/TSIOBufferCreate.en', 'TSIOBufferCreate', u'Traffic Server IO buffer API',
None, u'3ts'),
 
    ('reference/commands/traffic_cop.en', 'traffic_cop', u'Traffic Server watchdog', None,
'8'),
    ('reference/commands/traffic_line.en', 'traffic_line', u'Traffic Server command line',
None, '8'),

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/fbe22e49/doc/reference/api/TSIOBufferCreate.en.rst
----------------------------------------------------------------------
diff --git a/doc/reference/api/TSIOBufferCreate.en.rst b/doc/reference/api/TSIOBufferCreate.en.rst
new file mode 100644
index 0000000..5e6ad80
--- /dev/null
+++ b/doc/reference/api/TSIOBufferCreate.en.rst
@@ -0,0 +1,91 @@
+.. 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.
+
+.. default-domain:: c
+
+================
+TSIOBufferCreate
+================
+
+Library
+=======
+Apache Traffic Server plugin API
+
+Synopsis
+========
+`#include <ts/ts.h>`
+
+.. function:: TSIOBuffer TSIOBufferCreate(void)
+.. function:: TSIOBuffer TSIOBufferSizedCreate(TSIOBufferSizeIndex index)
+.. function:: void TSIOBufferDestroy(TSIOBuffer bufp)
+.. function:: int64_t TSIOBufferWrite(TSIOBuffer bufp, const void * buf, int64_t length)
+.. function:: void TSIOBufferProduce(TSIOBuffer bufp, int64_t nbytes)
+.. function:: int64_t TSIOBufferWaterMarkGet(TSIOBuffer bufp)
+.. function:: void TSIOBufferWaterMarkSet(TSIOBuffer bufp, int64_t water_mark)
+
+Description
+===========
+
+The :type:`TSIOBuffer` data structure is the building block of the TSVConn
+abstraction. An IO buffer is composed of a list of buffer blocks which
+are reference counted so that they can reside in multiple buffers at the
+same time. This makes it extremely efficient to copy data from one IO
+buffer to another using :func:`TSIOBufferCopy` since Traffic Server only needs to
+copy pointers and adjust reference counts appropriately and not actually
+copy any data; however applications should still strive to ensure data
+blocks are a reasonable size.
+
+The IO buffer abstraction provides for a single writer and multiple
+readers. In order for the readers to have no knowledge of each
+other, they manipulate IO buffers through the :type:`TSIOBufferReader`
+data structure. Since only a single writer is allowed, there is no
+corresponding :type:`TSIOBufferWriter` data structure. The writer
+simply modifies the IO buffer directly.
+
+:func:`TSIOBufferCreate` creates an empty :type:`TSIOBuffer`.
+
+:func:`TSIOBufferSizedCreate` creates an empty :type:`TSIOBuffer`
+with an initial capacity of index bytes.
+
+:func:`TSIOBufferDestroy` destroys the IO buffer bufp. Since multiple IO
+buffers can share data, this does not necessarily free all of the data
+associated with the IO buffer but simply decrements the appropriate reference counts.
+
+:func:`TSIOBufferWrite` appends length bytes from the buffer buf to the IO
+buffer bufp and returns the number of bytes successfully written into the
+IO buffer.
+
+:func:`TSIOBufferProduce` makes nbytes of data available for reading in the IO
+buffer bufp. A common pattern for writing to an IO buffer is to copy
+data into a buffer block and then call INKIOBufferProduce to make the new
+data visible to any readers.
+
+The watermark of an TSIOBuffer is the minimum number of bytes of data
+that have to be in the buffer before calling back any continuation that
+has initiated a read operation on this buffer. As a writer feeds data
+into the TSIOBuffer, no readers are called back until the amount of data
+reaches the watermark. Setting a watermark can improve performance
+because it avoids frequent callbacks to read small amounts of data.
+:func:`TSIOBufferWaterMarkGet` gets the current watermark for the IO buffer
+bufp.
+
+:func:`TSIOBufferWaterMarkSet` gets the current watermark for the IO buffer
+bufp to water_mark bytes.
+
+See also
+========
+
+:manpage:`TSAPI(3ts)`, :manpage:`TSIOBufferReaderAlloc(3ts)`


Mime
View raw message