trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From js...@apache.org
Subject [trafficserver] 02/03: More tweaks.
Date Tue, 01 Nov 2016 15:22:41 GMT
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 <solidwallofcode@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" <commits@trafficserver.apache.org>.

Mime
View raw message