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 <[email protected]> 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 "[email protected]" <[email protected]>.
