Repository: trafficserver Updated Branches: refs/heads/master a7d3f164d -> 548ee57f9
Clean up / clarify the cache key APIs Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/548ee57f Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/548ee57f Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/548ee57f Branch: refs/heads/master Commit: 548ee57f9703b83f4c353504ca8c381c0bf9551f Parents: a7d3f16 Author: Leif Hedstrom <[email protected]> Authored: Sun Oct 4 12:19:04 2015 +0800 Committer: Leif Hedstrom <[email protected]> Committed: Sun Oct 4 12:19:09 2015 +0800 ---------------------------------------------------------------------- doc/arch/cache/cache-api.en.rst | 21 ++++++++++++++++++++ doc/arch/cache/cache-appendix.en.rst | 10 +++++----- .../api/TSHttpTxnCacheLookupUrlGet.en.rst | 6 +++++- 3 files changed, 31 insertions(+), 6 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/trafficserver/blob/548ee57f/doc/arch/cache/cache-api.en.rst ---------------------------------------------------------------------- diff --git a/doc/arch/cache/cache-api.en.rst b/doc/arch/cache/cache-api.en.rst index 2cdd615..2f551e1 100644 --- a/doc/arch/cache/cache-api.en.rst +++ b/doc/arch/cache/cache-api.en.rst @@ -34,6 +34,27 @@ Cache Related API functions be called from ``TS_HTTP_READ_REQUEST_HDR_HOOK`` which is before cache lookup but late enough that the HTTP request header is available. +.. c:function:: TSReturnCode TSHttpTxnCacheLookupUrlGet(TSHttpTxn txnp, TSMBuffer bufp, TSMLoc offset) + + + Get the current cache key URL, also referred to as the lookup URL. This must + be stored in a properly allocated URL object, typically created with a + :c:func:`TSUrlCreate()`. + +.. c:function:: TSReturnCode TSHttpTxnCacheLookupUrlSet(TSHttpTxn txnp, TSMBuffer bufp, TSMLoc offset) + + Set the current cache key URL, also referred to as the lookup URL. This must + be stored in a properly allocated URL object, typically created with a + :c:func:`TSUrlCreate()` or :c:func:`TSUrlClone()`. + + +The APIs that modify the cache key can be called as early as +``TS_HTTP_READ_REQUEST_HDR_HOOK`` but no later than +``TS_HTTP_POST_REMAP_HOOK``. The cache key is not only used for a cache lookup +before going to origin, but also to mark the intent to write to cache on an +origin response (if possible). + + =============== Cache Internals =============== http://git-wip-us.apache.org/repos/asf/trafficserver/blob/548ee57f/doc/arch/cache/cache-appendix.en.rst ---------------------------------------------------------------------- diff --git a/doc/arch/cache/cache-appendix.en.rst b/doc/arch/cache/cache-appendix.en.rst index 8181114..7e063c7 100644 --- a/doc/arch/cache/cache-appendix.en.rst +++ b/doc/arch/cache/cache-appendix.en.rst @@ -113,11 +113,11 @@ These collisions are not by themselves good or bad. An administrator needs to decide which is appropriate for their situation and set the value correspondingly. If a greater degree of control is desired, a plugin must be used to invoke the -API call :c:func:`TSCacheUrlSet()` to provide a specific :term:`cache key`. The -:c:func:`TSCacheUrlSet()` API can be called as early as -``TS_HTTP_READ_REQUEST_HDR_HOOK`` but no later than ``TS_HTTP_POST_REMAP_HOOK``. -It can be called only once per transaction; calling it multiple times has no -additional effect. +API calls :c:func:`TSHttpTxnCacheLookupUrlSet()` or :c:func:`TSCacheUrlSet()` +to provide a specific :term:`cache key`. The :c:func:`TSCacheUrlSet()` API can +be called as early as ``TS_HTTP_READ_REQUEST_HDR_HOOK`` but no later than +``TS_HTTP_POST_REMAP_HOOK``. It can be called only once per transaction; +calling it multiple times has no additional effect. A plugin that changes the cache key must do so consistently for both cache hit and cache miss requests because two different requests that map to the same http://git-wip-us.apache.org/repos/asf/trafficserver/blob/548ee57f/doc/reference/api/TSHttpTxnCacheLookupUrlGet.en.rst ---------------------------------------------------------------------- diff --git a/doc/reference/api/TSHttpTxnCacheLookupUrlGet.en.rst b/doc/reference/api/TSHttpTxnCacheLookupUrlGet.en.rst index 6e0c121..85b0cdd 100644 --- a/doc/reference/api/TSHttpTxnCacheLookupUrlGet.en.rst +++ b/doc/reference/api/TSHttpTxnCacheLookupUrlGet.en.rst @@ -44,10 +44,14 @@ Synopsis .. c:function:: TSReturnCode TSHttpTxnCacheLookupUrlSet(TSHttpTxn txnp, TSMBuffer bufp, TSMLoc offset) - Description ----------- Set the current cache key URL, also referred to as the lookup URL. This must be stored in a properly allocated URL object, typically created with a :c:func:`TSUrlCreate()` or :c:func:`TSUrlClone()`. + +This API can be called as early as ``TS_HTTP_READ_REQUEST_HDR_HOOK`` but no later than +``TS_HTTP_POST_REMAP_HOOK``. This is the preferred and most efficient way to +modify the cache key, but an alternative is to use the old +:c:func:`TSCacheUrlSet()`, which takes a simple string as argument.
