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/3.3.x Commit: fbe22e49fea0d13f34eb10d3245376d7e33bdfe3 Parents: 229a209 Author: James Peach <[email protected]> Authored: Thu Aug 1 10:12:03 2013 -0700 Committer: James Peach <[email protected]> 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)`
