trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
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


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

 doc/                               |  1 +
 doc/reference/api/TSIOBufferCreate.en.rst | 91 ++++++++++++++++++++++++++
 2 files changed, 92 insertions(+)
diff --git a/doc/ b/doc/
index d9eb3a1..cc449e0 100644
--- a/doc/
+++ b/doc/
@@ -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,
    ('reference/commands/traffic_line.en', 'traffic_line', u'Traffic Server command line',
None, '8'),
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
+   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
+Apache Traffic Server plugin API
+`#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)
+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
+:func:`TSIOBufferWaterMarkSet` gets the current watermark for the IO buffer
+bufp to water_mark bytes.
+See also
+:manpage:`TSAPI(3ts)`, :manpage:`TSIOBufferReaderAlloc(3ts)`

View raw message