You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by js...@apache.org on 2016/11/01 15:22:41 UTC
[trafficserver] 02/03: More tweaks.
This is an automated email from the ASF dual-hosted git repository.
jsime pushed a commit to branch master
in repository https://git-dual.apache.org/repos/asf/trafficserver.git
commit 85253ffdfa91f5b7e6806a90e659e9db5366a7f6
Author: Alan M. Carroll <so...@yahoo-inc.com>
AuthorDate: Thu Oct 20 12:57:50 2016 -0500
More tweaks.
---
.../api/functions/TSHttpTxnIntercept.en.rst | 2 +-
.../api/functions/TSIOBufferCreate.en.rst | 10 +-
.../api/functions/TSIOBufferReader.en.rst | 117 +++++++++++++++++++++
.../api/functions/TSLifecycleHookAdd.en.rst | 86 ++++++++-------
doc/developer-guide/api/functions/TSTypes.en.rst | 18 +++-
.../api/functions/TSUuidCreate.en.rst | 16 +--
doc/developer-guide/api/types/TSEvent.en.rst | 2 +
.../api/types/TSLifecycleHookID.en.rst | 51 ---------
doc/ext/traffic-server.py | 2 +-
9 files changed, 201 insertions(+), 103 deletions(-)
diff --git a/doc/developer-guide/api/functions/TSHttpTxnIntercept.en.rst b/doc/developer-guide/api/functions/TSHttpTxnIntercept.en.rst
index e221049..5825dd7 100644
--- a/doc/developer-guide/api/functions/TSHttpTxnIntercept.en.rst
+++ b/doc/developer-guide/api/functions/TSHttpTxnIntercept.en.rst
@@ -41,7 +41,7 @@ server and read the HTTP request and body off the :c:type:`TSVConn`
and send an HTTP response header and body.
:func:`TSHttpTxnIntercept` must be called be called from only
-:data:`TS_HTTP_READ_REQUEST_HOOK`. Using
+:data:`TS_HTTP_READ_REQUEST_HDR_HOOK`. Using
:type:`TSHttpTxnIntercept` will bypass the Traffic Server cache. If
response sent by the plugin should be cached, use
:func:`TSHttpTxnServerIntercept` instead.
diff --git a/doc/developer-guide/api/functions/TSIOBufferCreate.en.rst b/doc/developer-guide/api/functions/TSIOBufferCreate.en.rst
index 9de8e5b..ee70863 100644
--- a/doc/developer-guide/api/functions/TSIOBufferCreate.en.rst
+++ b/doc/developer-guide/api/functions/TSIOBufferCreate.en.rst
@@ -54,7 +54,7 @@ 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
+corresponding `TSIOBufferWriter` data structure. The writer
simply modifies the IO buffer directly.
:func:`TSIOBufferCreate` creates an empty :type:`TSIOBuffer`.
@@ -75,9 +75,11 @@ buffer :arg:`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.
-.. XXX The above references an old API function: INKIOBufferProduce and needs to
- be fixed. I don't see a TSIOBufferProduce function that would be its
- obvious replacement from the Ink->TS rename.
+.. note::
+
+ The above references an old API function: INKIOBufferProduce and needs to
+ be fixed. I don't see a TSIOBufferProduce function that would be its
+ obvious replacement from the Ink->TS rename.
The watermark of an :type:`TSIOBuffer` is the minimum number of bytes of data
that have to be in the buffer before calling back any continuation that
diff --git a/doc/developer-guide/api/functions/TSIOBufferReader.en.rst b/doc/developer-guide/api/functions/TSIOBufferReader.en.rst
new file mode 100644
index 0000000..ad97bbc
--- /dev/null
+++ b/doc/developer-guide/api/functions/TSIOBufferReader.en.rst
@@ -0,0 +1,117 @@
+.. 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
+
+==================
+TSIOBufferReader
+==================
+
+Traffic Server IO buffer reader API.
+
+Synopsis
+========
+`#include <ts/ts.h>`
+
+.. function:: TSIOBufferReader TSIOBufferReaderAlloc(TSIOBuffer bufp)
+.. function:: TSIOBufferReader TSIOBufferReaderClone(TSIOBufferReader readerp)
+.. function:: void TSIOBufferReaderFree(TSIOBufferReader readerp)
+.. function:: void TSIOBufferReaderConsume(TSIOBufferReader readerp, int64_t nbytes)
+.. function:: TSIOBufferBlock TSIOBufferReaderStart(TSIOBufferReader readerp)
+.. function:: int64_t TSIOBufferReaderAvail(TSIOBufferReader readerp)
+.. function:: bool TSIOBufferReaderIsAvailAtLeast(TSIOBufferReader, int64_t nbytes)
+.. function:: int64_t TSIOBufferReaderRead(TSIOBufferReader reader, const void * buf, int64_t length)
+.. function:: bool TSIOBufferReaderIterate(TSIOBufferReader reader, TSIOBufferBlockFunc* func, void* context)
+
+.. :type:: TSIOBufferBlockFunc
+
+ ``bool (*TSIOBufferBlockFunc)(void const* data, int64_t nbytes, void* context)``
+
+ :arg:`data` is the data in the :type:`TSIOBufferBlock` and is :arg:`nbytes` long. :arg:`context` is
+ opaque data provided to the API call along with this function and passed on to the function. This
+ function should return ``true`` to continue iteration or ``false`` to terminate iteration.
+
+Description
+===========
+
+:type:`TSIOBufferReader` is an read accessor for :type:`TSIOBuffer`. It represents a location in
+the contents of the buffer. A buffer can have multiple readers and each reader consumes data in the
+buffer independently. Data which for which there are no readers is discarded from the buffer. This
+has two very important consequences --
+
+* Data for which there are no readers and no writer will be discarded. In effect this means without
+ any readers only the current write buffer block will be maintained, older buffer blocks will
+ disappear.
+* Conversely keeping a reader around unused will pin the buffer data in memory. This can be useful or harmful.
+
+A buffer has a fixed amount of possible readers (currently 5) which is determined at compile
+time. Reader allocation is fast and cheap until this maxium is reached at which point it fails.
+
+:func:`TSIOBufferReaderAlloc` allocates a reader for the IO buffer :arg:`bufp`. This should only be
+ called on a newly allocated buffer. If not the location of the reader in the buffer will be
+ indeterminate. Use :func:`TSIOBufferReaderClone` to get another reader if the buffer is
+ already in use.
+
+:func:`TSIOBufferReaderClone` allocates a reader and sets its position in the buffer to be the same as :arg:`reader`.
+
+:func:`TSIOBufferReaderFree` de-allocates the reader. Any data referenced only by this reader is
+ discarded from the buffer.
+
+:func:`TSIOBufferReaderConsume` advances the position of :arg:`reader` in its IO buffer by the
+ the smaller of :arg:`nbytes` and the maximum available in the buffer.
+
+:func:`TSIOBufferReaderStart` returns the IO buffer block containing the position of
+:arg:`reader`.
+
+ .. note:: The byte at the position of :arg:`reader` is in the block but is not necessarily the first byte of the block.
+
+:func:`TSIOBufferReaderAvail` returns the number of bytes which :arg:`reader` could consume. That is
+ the number of bytes in the IO buffer starting at the current position of :arg:`reader`.
+
+:func:`TSIOBufferReaderIsAvailAtLeast` return ``true`` if the available number of bytes for
+ :arg:`reader` is at least :arg:`nbytes`, ``false`` if not. This can be more efficient than
+ :func:`TSIOBufferReadAvail` because the latter must walk all the IO buffer blocks in the IO
+ buffer. This function returns as soon as the return value can be determined. In particular a
+ value of ``1`` for :arg:`nbytes` means only the first buffer block will be checked.
+
+:func:`TSIOBufferReaderRead` reads data from :arg:`reader`. This first copies data from the IO
+ buffer for :arg:`reader` to the target buffer :arg:`bufp`, starting at :arg:`reader`s
+ position, and then advances (as with :func:`TSIOBufferReaderConsume`) :arg:`reader`s
+ position past the copied data. The amount of data read in this fashion is the smaller of the
+ amount of data available in the IO buffer for :arg:`reader` and the size of the target buffer
+ (:arg:`length`).
+
+:func:`TSIOBufferReaderIterate` iterates over the blocks for :arg:`reader`. For each block
+:arg:`func` is called with with the data for the block and :arg:`context`. The :arg:`context` is an
+opaque type to this function and is passed unchanged to :arg:`func`. It is intended to be used as
+context for :arg:`func`. If :arg:`func` returns ``false`` the iteration terminates. If :arg:`func`
+returns true the block is consumed. The return value for :func:`TSIOBufferReaderIterate` is the
+return value from the last call to :arg:`func`.
+
+ .. note:: If it would be a problem for the iteration to consume the data (especially in cases where
+ ``false`` might be returned) the reader can be cloned via :func:`TSIOBufferReaderClone` to
+ keep the data in the IO buffer and available. If not needed the reader can be destroyed or
+ if needed the original reader can be destroyed and replaced by the clone.
+
+.. note:: Destroying a :type:`TSIOBuffer` will de-allocate and destroy all readers for that buffer.
+
+
+
+See also
+========
+
+:manpage:`TSIOBufferCreate(3ts)`
diff --git a/doc/developer-guide/api/functions/TSLifecycleHookAdd.en.rst b/doc/developer-guide/api/functions/TSLifecycleHookAdd.en.rst
index 5499bc0..a15f21f 100644
--- a/doc/developer-guide/api/functions/TSLifecycleHookAdd.en.rst
+++ b/doc/developer-guide/api/functions/TSLifecycleHookAdd.en.rst
@@ -43,50 +43,62 @@ considered a lifecyle hook). Unlike other hooks, lifecycle hooks may not have a
well defined ordering and use of them should not assume that one of the hooks
is always called before another unless specifically mentioned.
-.. c:var:: TS_LIFECYCLE_PORTS_INITIALIZED_HOOK
+Types
+=====
- Called after the :ts:cv:`proxy server port <proxy.config.http.server_ports>`
- data structures have been initialized but before connections are accepted on
- those ports. The sockets corresponding to the ports may or may not be open
- depending on how the :program:`traffic_server` process was invoked. Other
- API functions that depend on server ports should be called from this hook
- and not :func:`TSPluginInit`.
+.. :c:type:: TSLifecycleHookID
- Invoked with the event :c:data:`TS_EVENT_LIFECYCLE_PORTS_INITIALIZED` and
- ``NULL`` data.
-
-.. c:var:: TS_LIFECYCLE_PORTS_READY_HOOK
-
- Called after enabling connections on the proxy server ports. Because |TS| is
- threaded this may or may not be called before any connections are accepted.
- The hook code may assume that any connection to |TS| started after this hook
- is called will be accepted by |TS|, making this a convenient place to signal
- external processes of that.
-
- Invoked with the event :c:data:`TS_EVENT_LIFECYCLE_PORTS_READY` and ``NULL``
- data.
-
-.. c:var:: TS_LIFECYCLE_CACHE_READY_HOOK
-
- Called after |TS| cache initialization has finished.
-
- Invoked with the event :c:data:`TS_EVENT_LIFECYCLE_CACHE_READY` and ``NULL``
- data.
-
-.. c:var:: TS_LIFECYCLE_MSG_HOOK
-
- Called when triggered by an external process, such as :program:`traffic_ctl`.
-
- Invoked with the event :c:data:`TS_EVENT_LIFECYCLE_MSG`. The data is an instance of the
- :c:type:`TSPluginMsg`. This contains a *tag* which is a null terminated string and a data payload.
- The payload cannot be assumed to be null terminated and is created by the external agent.
+ .. c:member:: TS_LIFECYCLE_PORTS_INITIALIZED_HOOK
+
+ Called after the :ts:cv:`proxy server port <proxy.config.http.server_ports>`
+ data structures have been initialized but before connections are accepted on
+ those ports. The sockets corresponding to the ports may or may not be open
+ depending on how the :program:`traffic_server` process was invoked. Other
+ API functions that depend on server ports should be called from this hook
+ and not :func:`TSPluginInit`.
+
+ Invoked with the event :c:data:`TS_EVENT_LIFECYCLE_PORTS_INITIALIZED` and
+ ``NULL`` data.
+
+ .. c:member:: TS_LIFECYCLE_PORTS_READY_HOOK
+
+ Called after enabling connections on the proxy server ports. Because |TS| is
+ threaded this may or may not be called before any connections are accepted.
+ The hook code may assume that any connection to |TS| started after this hook
+ is called will be accepted by |TS|, making this a convenient place to signal
+ external processes of that.
+
+ Invoked with the event :c:data:`TS_EVENT_LIFECYCLE_PORTS_READY` and ``NULL``
+ data.
+
+ .. c:member:: TS_LIFECYCLE_CACHE_READY_HOOK
+
+ Called after |TS| cache initialization has finished.
+
+ Invoked with the event :c:data:`TS_EVENT_LIFECYCLE_CACHE_READY` and ``NULL``
+ data.
+
+ .. c:member:: TS_LIFECYCLE_MSG_HOOK
+
+ Called when triggered by an external process, such as :program:`traffic_ctl`.
+
+ Invoked with the event :c:data:`TS_EVENT_LIFECYCLE_MSG`. The data is an instance of the
+ :c:type:`TSPluginMsg`. This contains a *tag* which is a null terminated string and a data payload.
+ The payload cannot be assumed to be null terminated and is created by the external agent.
+
+ .. c:member:: TS_LIFECYCLE_CLIENT_SSL_CTX_INITIALIZED_HOOK
+
+ Called after the initialization of the SSL context used by |TS| for outbound connections (|TS| as client).
+
+ .. c:member:: TS_LIFECYCLE_SERVER_SSL_CTX_INITIALIZED_HOOK
+ Called after every SSL context initialization used by |TS| for inbound connections (|TS| as the server).
Ordering
========
-:c:data:`TS_LIFECYCLE_PORTS_INITIALIZED_HOOK` will always be called before
-:c:data:`TS_LIFECYCLE_PORTS_READY_HOOK`.
+:c:member:`TS_LIFECYCLE_PORTS_INITIALIZED_HOOK` will always be called before
+:c:member:`TS_LIFECYCLE_PORTS_READY_HOOK`.
Examples
========
diff --git a/doc/developer-guide/api/functions/TSTypes.en.rst b/doc/developer-guide/api/functions/TSTypes.en.rst
index c3c069f..60e6aff 100644
--- a/doc/developer-guide/api/functions/TSTypes.en.rst
+++ b/doc/developer-guide/api/functions/TSTypes.en.rst
@@ -64,7 +64,7 @@ more widely. Those are described on this page.
.. type:: TSHttpSsn
- An opaque type that represents a Traffic Server :term:`session`.
+ An opaque type that represents a Traffic SeUuirver :term:`session`.
.. type:: TSHttpStatus
@@ -176,6 +176,22 @@ more widely. Those are described on this page.
.. type:: TSThreadPool
+.. type:: TSUuid
+
+ Opaque type that refers to an allocated UUID.
+
+.. type:: TSUuidVersion
+
+ A version value for at :type:`TSUuid`.
+
+ .. member:: TS_UUID_V4
+
+ A version 4 UUID. Currently only this value is used.
+
+.. var:: size_t TS_UUID_STRING_LEN
+
+ Length of a UUID string.
+
.. type:: TSVConn
.. type:: TSVIO
diff --git a/doc/developer-guide/api/functions/TSUuidCreate.en.rst b/doc/developer-guide/api/functions/TSUuidCreate.en.rst
index d0f9429..1ae9c61 100644
--- a/doc/developer-guide/api/functions/TSUuidCreate.en.rst
+++ b/doc/developer-guide/api/functions/TSUuidCreate.en.rst
@@ -28,14 +28,14 @@ Synopsis
`#include <ts/ts.h>`
-.. function:: TSUuid TSUuidCreate(void);
-.. function:: TSReturnCode TSUuidInitialize(TSUuid uuid, TSUuidVersion v);
-.. function:: void TSUuidDestroy(TSUuid uuid);
-.. function:: TSReturnCode TSUuidCopy(TSUuid dest, const TSUuid src);
-.. function:: const char *TSUuidStringGet(const TSUuid uuid);
-.. function:: TSUuidVersion TSUuidVersionGet(const TSUuid uuid);
-.. function:: TSReturnCode TSUuidStringParse(TSUuid uuid, const char *uuid_str);
-.. function:: const TSUuid TSProcessUuidGet(void);
+.. function:: TSUuid TSUuidCreate(void)
+.. function:: TSReturnCode TSUuidInitialize(TSUuid uuid, TSUuidVersion v)
+.. function:: void TSUuidDestroy(TSUuid uuid)
+.. function:: TSReturnCode TSUuidCopy(TSUuid dest, const TSUuid src)
+.. function:: const char * TSUuidStringGet(const TSUuid uuid)
+.. function:: TSUuidVersion TSUuidVersionGet(const TSUuid uuid)
+.. function:: TSReturnCode TSUuidStringParse(TSUuid uuid, const char * uuid_str)
+.. function:: const TSUuid TSProcessUuidGet(void)
Description
===========
diff --git a/doc/developer-guide/api/types/TSEvent.en.rst b/doc/developer-guide/api/types/TSEvent.en.rst
index baabda8..239cd45 100644
--- a/doc/developer-guide/api/types/TSEvent.en.rst
+++ b/doc/developer-guide/api/types/TSEvent.en.rst
@@ -170,6 +170,8 @@ Enumeration Members
.. c:member:: TSEvent TS_EVENT_LIFECYCLE_CACHE_READY
+.. c:member:: TSEvent TS_EVENT_LIFECYCLE_MSG
+
.. c:member:: TSEvent TS_EVENT_LIFECYCLE_SERVER_SSL_CTX_INITIALIZED
.. c:member:: TSEvent TS_EVENT_LIFECYCLE_CLIENT_SSL_CTX_INITIALIZED
diff --git a/doc/developer-guide/api/types/TSLifecycleHookID.en.rst b/doc/developer-guide/api/types/TSLifecycleHookID.en.rst
deleted file mode 100644
index e9b5546..0000000
--- a/doc/developer-guide/api/types/TSLifecycleHookID.en.rst
+++ /dev/null
@@ -1,51 +0,0 @@
-.. 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.
-
-.. include:: ../../../common.defs
-
-TSLifecycleHookID
-*****************
-
-Synopsis
-========
-
-`#include <ts/apidefs.h>`
-
-.. c:type:: TSLifeCycleHookID
-
-Enum typedef used to indicate the event hook being called during a continuation
-invocation.
-
-Enumeration Members
-===================
-
-.. c:member:: TSLifecycleHookID TS_LIFECYCLE_PORTS_INITIALIZED_HOOK
-
-.. c:member:: TSLifecycleHookID TS_LIFECYCLE_PORTS_READY_HOOK
-
-.. c:member:: TSLifecycleHookID TS_LIFECYCLE_CACHE_READY_HOOK
-
-.. c:member:: TSLifecycleHookID TS_LIFECYCLE_SERVER_SSL_CTX_INITIALIZED_HOOK
-
-.. c:member:: TSLifecycleHookID TS_LIFECYCLE_CLIENT_SSL_CTX_INITIALIZED_HOOK
-
-.. c:member:: TSLifecycleHookID MSG_HOOK
-
-.. c:member:: TSLifecycleHookID TS_LIFECYCLE_LAST_HOOK
-
-Description
-===========
-
diff --git a/doc/ext/traffic-server.py b/doc/ext/traffic-server.py
index 0711f0e..a875f47 100644
--- a/doc/ext/traffic-server.py
+++ b/doc/ext/traffic-server.py
@@ -347,7 +347,7 @@ class TrafficServerDomain(Domain):
# We really need to do better with this. Editing this file for each of
# these is already getting silly.
EXTERNAL_TYPES = set((
- 'int', 'uint',
+ 'bool', 'int', 'uint',
'uint8_t', 'uint16_t', 'uint24_t', 'uint32_t', 'uint64_t',
'int8_t', 'int16_t', 'int24_t', 'int32_t', 'int64_t',
'unsigned', 'unsigned int',
--
To stop receiving notification emails like this one, please contact
"commits@trafficserver.apache.org" <co...@trafficserver.apache.org>.