diff --git a/doc/developer-guide/api/functions/TSHttpArgs.en.rst b/doc/developer-guide/api/functions/TSHttpArgs.en.rst deleted file mode 100644 index a564eb2d4f9..00000000000 --- a/doc/developer-guide/api/functions/TSHttpArgs.en.rst +++ /dev/null @@ -1,102 +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 -.. default-domain:: c - - -TSHttpArgs -********** - -Synopsis -======== - -.. note:: - - This set of API is obsoleted as of ATS v9.0.0, and will be removed with ATS v10.0.0! - For details of the new APIs, see :ref:`tsuserargs`. - - -.. code-block:: cpp - - #include - -.. function:: TSReturnCode TSHttpTxnArgIndexReserve(const char * name, const char * description, int * arg_idx) -.. function:: TSReturnCode TSHttpTxnArgIndexNameLookup(const char * name, int * arg__idx, const char ** description) -.. function:: TSReturnCode TSHttpTxnArgIndexLookup(int arg_idx, const char ** name, const char ** description) -.. function:: TSReturnCode TSHttpSsnArgIndexReserve(const char * name, const char * description, int * arg_idx) -.. function:: TSReturnCode TSHttpSsnArgIndexNameLookup(const char * name, int * arg__idx, const char ** description) -.. function:: TSReturnCode TSHttpSsnArgIndexLookup(int arg_idx, const char ** name, const char ** description) -.. function:: void TSHttpTxnArgSet(TSHttpTxn txnp, int arg_idx, void * arg) -.. function:: void * TSHttpTxnArgGet(TSHttpTxn txnp, int arg_idx) -.. function:: void TSHttpSsnArgSet(TSHttpSsn ssnp, int arg_idx, void * arg) -.. function:: void * TSHttpSsnArgGet(TSHttpSsn ssnp, int arg_idx) - -Description -=========== - -|TS| sessions and transactions provide a fixed array of void pointers that can be used by plugins to -store information. This can be used to avoid creating a per session or transaction continuations to -hold data, or to communicate between plugins as the values in the array are visible to any plugin -which can access the session or transaction. The array values are opaque to |TS| and it will not -dereference nor release them. Plugins are responsible for cleaning up any resources pointed to by the -values or, if the values are simply values, there is no need for the plugin to remove them after the -session or transaction has completed. - -To avoid collisions between plugins a plugin should first *reserve* an index in the array. A -transaction based plugin argument is reserved by calling :func:`TSHttpTxnArgIndexReserve`. A session -base plugin argument is reserved by calling :func:`TSHttpSsnArgIndexReserve`. Both functions have the arguments - -:arg:`name` - An identifying name for the plugin that reserved the index. Required. - -:arg:`description` - An optional description of the use of the arg. This can be :code:`nullptr`. - -:arg:`arg_idx` - A pointer to an :code:`int`. If an index is successfully reserved, the :code:`int` pointed at by this is - set to the reserved index. It is not modified if the call is unsuccessful. - -The functions return :code:`TS_SUCCESS` if an index was reserved, -:code:`TS_ERROR` if not (most likely because all of the indices have already been reserved). -Generally this will be a file or library scope global which is set at plugin initialization. This -function is used in the example remap plugin :ts:git:`example/plugins/c-api/remap/remap.cc`. The index is stored -in the plugin global :code:`arg_index`. Transaction and session plugin argument indices are reserved -independently. - -To look up the owner of a reserved index use :func:`TSHttpTxnArgIndexNameLookup` or -:func:`TSHttpSsnArgIndexNameLookup` for transaction and session plugin argument respectively. If -:arg:`name` is found as an owner, the function returns :code:`TS_SUCCESS` and :arg:`arg_index` is -updated with the index reserved under that name. If :arg:`description` is not :code:`NULL` then -the character pointer to which it points will be updated to point at the description for that -reserved index. This enables communication between plugins where plugin "A" reserves an index under -a well known name and plugin "B" locates the index by looking it up under that name. - -The owner of a reserved index can be found with :func:`TSHttpTxnArgIndexLookup` or -:func:`TSHttpSsnArgIndexLookup` for transaction and session plugin arguments respectively. If -:arg:`arg_index` is reserved then the function returns :code:`TS_SUCCESS` and the pointers referred -to by :arg:`name` and :arg:`description` are updated. :arg:`name` must point at a valid character -pointer but :arg:`description` can be :code:`NULL` in which case it is ignored. - -Manipulating the array is simple. :func:`TSHttpTxnArgSet` sets the array slot at :arg:`arg_idx` for -the transaction :arg:`txnp` to the value :arg:`arg`. Note this sets the value only for the specific -transaction. Similarly :func:`TSHttpSsnArgSet` sets the value for a session argument. The values can -be retrieved with :func:`TSHttpTxnArgGet` for transactions and :func:`TSHttpSsnArgGet` for sessions, -which return the specified value. Values that have not been set are :code:`NULL`. - -.. note:: Session arguments persist for the entire session, which means potentially across all transactions in that session. - -.. note:: Following arg index reservations is conventional, it is not enforced. diff --git a/doc/developer-guide/api/functions/TSVConnArgs.en.rst b/doc/developer-guide/api/functions/TSVConnArgs.en.rst deleted file mode 100644 index be575296b9d..00000000000 --- a/doc/developer-guide/api/functions/TSVConnArgs.en.rst +++ /dev/null @@ -1,88 +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 -.. default-domain:: c - -TSVConnArgs -************ - -Synopsis -======== - -.. note:: - - This set of API is obsoleted as of ATS v9.0.0, and will be removed with ATS v10.0.0! - For details of the new APIs, see :ref:`tsuserargs`. - - -.. code-block:: cpp - - #include - -.. function:: TSReturnCode TSVConnArgIndexReserve(const char * name, const char * description, int * arg_idx) -.. function:: TSReturnCode TSVConnArgIndexNameLookup(const char * name, int * arg_idx, const char ** description) -.. function:: TSReturnCode TSVConnArgIndexLookup(int arg_idx, const char ** name, const char ** description) -.. function:: void TSVConnArgSet(TSVConn vc, int arg_idx, void * arg) -.. function:: void * TSVConnArgGet(TSVConn vc, int arg_idx) - -Description -=========== - -Virtual connection objects (API type :c:type:`TSVConn`) support an array of :code:`void *` values that -are controlled entirely by plugins. These are not used in any way by the core. This allows plugins -to store data associated with a specific virtual connection for later retrieval by the same plugin -in a different hook or by another plugin. Because the core does not interact with these values any -cleanup is the responsibility of the plugin. - -To avoid collisions between plugins a plugin should first *reserve* an index in the array by calling -:func:`TSVConnArgIndexReserve` passing it an identifying name, a description, and a pointer to an -integer which will get the reserved index. The function returns :code:`TS_SUCCESS` if an index was -reserved, :code:`TS_ERROR` if not (most likely because all of the indices have already been -reserved). Generally this will be a file or library scope global which is set at plugin -initialization. Note the reservation is by convention - nothing stops a plugin from interacting with -a :code:`TSVConn` arg it has not reserved. - -To look up the owner of a reserved index use :func:`TSVConnArgIndexNameLookup`. If the :arg:`name` is -found as an owner, the function returns :code:`TS_SUCCESS` and :arg:`arg_index` is updated with the -index reserved under that name. If :arg:`description` is not :code:`nullptr` then it will be updated -with the description for that reserved index. This enables communication between plugins where -plugin "A" reserves an index under a well known name and plugin "B" locates the index by looking it -up under that name. - -The owner of a reserved index can be found with :func:`TSVConnArgIndexLookup`. If :arg:`arg_index` is -reserved then the function returns :code:`TS_SUCCESS` and :arg:`name` and :arg:`description` are -updated. :arg:`name` must point at a valid character pointer but :arg:`description` can be -:code:`nullptr`. - -Manipulating the array is simple. :func:`TSVConnArgSet` sets the array slot at :arg:`arg_idx` for -the :arg:`vc` to the value :arg:`arg`. Note this sets the value only for the specific -:c:type:`TSVConn`. The values can be retrieved with :func:`TSVConnArgGet` which returns the -specified value. Values that have not been set are :code:`nullptr`. - -Hooks -===== - -Although these can be used from any hook that has access to a :c:type:`TSVConn` it will generally be -the case that :func:`TSVConnArgSet` will be used in early intervention hooks and -:func:`TSVConnArgGet` in session / transaction hooks. Cleanup should be done on the -:code:`TS_VCONN_CLOSE_HOOK`. - -.. rubric:: Appendix - -.. note:: - This is originally from `Issue 2388 `__. It - has been extended based on discussions with Kees and Leif Hedstrom at the ATS summit. diff --git a/doc/release-notes/upgrading.en.rst b/doc/release-notes/upgrading.en.rst index 5692087f4b0..edaab81de16 100644 --- a/doc/release-notes/upgrading.en.rst +++ b/doc/release-notes/upgrading.en.rst @@ -31,6 +31,24 @@ The following features, configurations and plugins are either removed or depreca version of ATS. Deprecated features should be avoided, with the expectation that they will be removed in the next major release of ATS. +* Removed TS API + + * TSHttpTxnArgSet + * TSHttpTxnArgGet + * TSHttpSsnArgSet + * TSHttpSsnArgGet + * TSVConnArgSet + * TSVConnArgGet + * TSHttpTxnArgIndexReserve + * TSHttpTxnArgIndexNameLookup + * TSHttpTxnArgIndexLookup + * TSHttpSsnArgIndexReserve + * TSHttpSsnArgIndexNameLookup + * TSHttpSsnArgIndexLookup + * TSVConnArgIndexReserve + * TSVConnArgIndexNameLookup + * TSVConnArgIndexLookup + API Changes ----------- diff --git a/include/ts/ts.h b/include/ts/ts.h index bb3551100e8..b6fed2eeb01 100644 --- a/include/ts/ts.h +++ b/include/ts/ts.h @@ -1638,24 +1638,6 @@ tsapi TSReturnCode TSUserArgIndexLookup(TSUserArgType type, int arg_idx, const c tsapi void TSUserArgSet(void *data, int arg_idx, void *arg); tsapi void *TSUserArgGet(void *data, int arg_idx); -/* These are deprecated as of v9.0.0, and will be removed in v10.0.0 */ -tsapi TS_DEPRECATED void TSHttpTxnArgSet(TSHttpTxn txnp, int arg_idx, void *arg); -tsapi TS_DEPRECATED void *TSHttpTxnArgGet(TSHttpTxn txnp, int arg_idx); -tsapi TS_DEPRECATED void TSHttpSsnArgSet(TSHttpSsn ssnp, int arg_idx, void *arg); -tsapi TS_DEPRECATED void *TSHttpSsnArgGet(TSHttpSsn ssnp, int arg_idx); -tsapi TS_DEPRECATED void TSVConnArgSet(TSVConn connp, int arg_idx, void *arg); -tsapi TS_DEPRECATED void *TSVConnArgGet(TSVConn connp, int arg_idx); - -tsapi TS_DEPRECATED TSReturnCode TSHttpTxnArgIndexReserve(const char *name, const char *description, int *arg_idx); -tsapi TS_DEPRECATED TSReturnCode TSHttpTxnArgIndexNameLookup(const char *name, int *arg_idx, const char **description); -tsapi TS_DEPRECATED TSReturnCode TSHttpTxnArgIndexLookup(int arg_idx, const char **name, const char **description); -tsapi TS_DEPRECATED TSReturnCode TSHttpSsnArgIndexReserve(const char *name, const char *description, int *arg_idx); -tsapi TS_DEPRECATED TSReturnCode TSHttpSsnArgIndexNameLookup(const char *name, int *arg_idx, const char **description); -tsapi TS_DEPRECATED TSReturnCode TSHttpSsnArgIndexLookup(int arg_idx, const char **name, const char **description); -tsapi TS_DEPRECATED TSReturnCode TSVConnArgIndexReserve(const char *name, const char *description, int *arg_idx); -tsapi TS_DEPRECATED TSReturnCode TSVConnArgIndexNameLookup(const char *name, int *arg_idx, const char **description); -tsapi TS_DEPRECATED TSReturnCode TSVConnArgIndexLookup(int arg_idx, const char **name, const char **description); - tsapi void TSHttpTxnStatusSet(TSHttpTxn txnp, TSHttpStatus status); tsapi TSHttpStatus TSHttpTxnStatusGet(TSHttpTxn txnp); diff --git a/src/traffic_server/InkAPI.cc b/src/traffic_server/InkAPI.cc index 9738fbe2ccf..7fdf4275770 100644 --- a/src/traffic_server/InkAPI.cc +++ b/src/traffic_server/InkAPI.cc @@ -6356,122 +6356,6 @@ TSUserArgGet(void *data, int arg_idx) } } -// ------------- -/* These are deprecated as of v9.0.0, and will be removed in v10.0.0 */ -TSReturnCode -TSHttpTxnArgIndexReserve(const char *name, const char *description, int *arg_idx) -{ - return TSUserArgIndexReserve(TS_USER_ARGS_TXN, name, description, arg_idx); -} - -TSReturnCode -TSHttpTxnArgIndexLookup(int arg_idx, const char **name, const char **description) -{ - return TSUserArgIndexLookup(TS_USER_ARGS_TXN, arg_idx, name, description); -} - -TSReturnCode -TSHttpTxnArgIndexNameLookup(const char *name, int *arg_idx, const char **description) -{ - return TSUserArgIndexNameLookup(TS_USER_ARGS_TXN, name, arg_idx, description); -} - -TSReturnCode -TSHttpSsnArgIndexReserve(const char *name, const char *description, int *arg_idx) -{ - return TSUserArgIndexReserve(TS_USER_ARGS_SSN, name, description, arg_idx); -} - -TSReturnCode -TSHttpSsnArgIndexLookup(int arg_idx, const char **name, const char **description) -{ - return TSUserArgIndexLookup(TS_USER_ARGS_SSN, arg_idx, name, description); -} - -TSReturnCode -TSHttpSsnArgIndexNameLookup(const char *name, int *arg_idx, const char **description) -{ - return TSUserArgIndexNameLookup(TS_USER_ARGS_SSN, name, arg_idx, description); -} - -TSReturnCode -TSVConnArgIndexReserve(const char *name, const char *description, int *arg_idx) -{ - return TSUserArgIndexReserve(TS_USER_ARGS_VCONN, name, description, arg_idx); -} - -TSReturnCode -TSVConnArgIndexLookup(int arg_idx, const char **name, const char **description) -{ - return TSUserArgIndexLookup(TS_USER_ARGS_VCONN, arg_idx, name, description); -} - -TSReturnCode -TSVConnArgIndexNameLookup(const char *name, int *arg_idx, const char **description) -{ - return TSUserArgIndexNameLookup(TS_USER_ARGS_VCONN, name, arg_idx, description); -} - -void -TSHttpTxnArgSet(TSHttpTxn txnp, int arg_idx, void *arg) -{ - sdk_assert(sdk_sanity_check_txn(txnp) == TS_SUCCESS); - - HttpSM *sm = reinterpret_cast(txnp); - - sm->set_user_arg(arg_idx, arg); -} - -void * -TSHttpTxnArgGet(TSHttpTxn txnp, int arg_idx) -{ - sdk_assert(sdk_sanity_check_txn(txnp) == TS_SUCCESS); - - HttpSM *sm = reinterpret_cast(txnp); - return sm->get_user_arg(arg_idx); -} - -void -TSHttpSsnArgSet(TSHttpSsn ssnp, int arg_idx, void *arg) -{ - sdk_assert(sdk_sanity_check_http_ssn(ssnp) == TS_SUCCESS); - - ProxySession *cs = reinterpret_cast(ssnp); - - cs->set_user_arg(arg_idx, arg); -} - -void * -TSHttpSsnArgGet(TSHttpSsn ssnp, int arg_idx) -{ - sdk_assert(sdk_sanity_check_http_ssn(ssnp) == TS_SUCCESS); - - ProxySession *cs = reinterpret_cast(ssnp); - return cs->get_user_arg(arg_idx); -} - -void -TSVConnArgSet(TSVConn connp, int arg_idx, void *arg) -{ - sdk_assert(sdk_sanity_check_iocore_structure(connp) == TS_SUCCESS); - PluginUserArgsMixin *user_args = dynamic_cast(reinterpret_cast(connp)); - sdk_assert(user_args); - - user_args->set_user_arg(arg_idx, arg); -} - -void * -TSVConnArgGet(TSVConn connp, int arg_idx) -{ - sdk_assert(sdk_sanity_check_iocore_structure(connp) == TS_SUCCESS); - PluginUserArgsMixin *user_args = dynamic_cast(reinterpret_cast(connp)); - sdk_assert(user_args); - - return user_args->get_user_arg(arg_idx); -} - -/* End deprecated Arg functions. */ - void TSHttpTxnStatusSet(TSHttpTxn txnp, TSHttpStatus status) { diff --git a/tests/tools/plugins/user_args.cc b/tests/tools/plugins/user_args.cc index 71f1956aa6a..ca414306046 100644 --- a/tests/tools/plugins/user_args.cc +++ b/tests/tools/plugins/user_args.cc @@ -26,8 +26,6 @@ #include #include -#define NEW_APIS 1 - typedef struct { int TXN, SSN, VCONN, GLB; TSCont contp; @@ -65,15 +63,9 @@ cont_global(TSCont contp, TSEvent event, void *edata) TSHttpSsn ssnp = TSHttpTxnSsnGet(txnp); TSVConn vconnp = TSHttpSsnClientVConnGet(ssnp); -#if NEW_APIS TSUserArgSet(txnp, gIX.TXN, (void *)"Transaction Data"); TSUserArgSet(ssnp, gIX.SSN, (void *)"Session Data"); TSUserArgSet(vconnp, gIX.VCONN, (void *)"VConn Data"); -#else - TSHttpTxnArgSet(txnp, gIX.TXN, (void *)"Transaction Data"); - TSHttpSsnArgSet(ssnp, gIX.SSN, (void *)"Session Data"); - TSVConnArgSet(vconnp, gIX.VCONN, (void *)"VConn Data"); -#endif TSHttpTxnReenable(txnp, TS_EVENT_HTTP_CONTINUE); @@ -91,16 +83,10 @@ cont_remap(TSCont contp, TSEvent event, void *edata) TSVConn vconnp = TSHttpSsnClientVConnGet(ssnp); if (TS_SUCCESS == TSHttpTxnClientRespGet(txnp, &bufp, &hdrs)) { -#if NEW_APIS set_header(bufp, hdrs, "X-Arg-GLB", static_cast(TSUserArgGet(nullptr, ix->GLB))); set_header(bufp, hdrs, "X-Arg-TXN", static_cast(TSUserArgGet(txnp, ix->TXN))); set_header(bufp, hdrs, "X-Arg-SSN", static_cast(TSUserArgGet(ssnp, ix->SSN))); set_header(bufp, hdrs, "X-Arg-VCONN", static_cast(TSUserArgGet(vconnp, ix->VCONN))); -#else - set_header(bufp, hdrs, "X-Arg-TXN", static_cast(TSHttpTxnArgGet(txnp, ix->TXN))); - set_header(bufp, hdrs, "X-Arg-SSN", static_cast(TSHttpSsnArgGet(ssnp, ix->SSN))); - set_header(bufp, hdrs, "X-Arg-VCONN", static_cast(TSVConnArgGet(vconnp, ix->VCONN))); -#endif } TSHttpTxnReenable(txnp, TS_EVENT_HTTP_CONTINUE); @@ -120,7 +106,6 @@ TSPluginInit(int argc, const char *argv[]) TSError("[%s] Plugin registration failed", PLUGIN_NAME); } -#if NEW_APIS if (TS_SUCCESS != TSUserArgIndexReserve(TS_USER_ARGS_TXN, PLUGIN_NAME, "User args tests TXN", &gIX.TXN)) { TSError("[%s] Unable to initialize plugin (disabled). Failed to reserve TXN arg.", PLUGIN_NAME); return; @@ -134,18 +119,6 @@ TSPluginInit(int argc, const char *argv[]) TSError("[%s] Unable to initialize plugin (disabled). Failed to reserve GLB arg.", PLUGIN_NAME); return; } -#else - if (TS_SUCCESS != TSHttpTxnArgIndexReserve(PLUGIN_NAME, "User args tests TXN", &gIX.TXN)) { - TSError("[%s] Unable to initialize plugin (disabled). Failed to reserve TXN arg.", PLUGIN_NAME); - return; - } else if (TS_SUCCESS != TSHttpSsnArgIndexReserve(PLUGIN_NAME, "User args tests SSN", &gIX.SSN)) { - TSError("[%s] Unable to initialize plugin (disabled). Failed to reserve SSN arg.", PLUGIN_NAME); - return; - } else if (TS_SUCCESS != TSVConnArgIndexReserve(PLUGIN_NAME, "User args tests VCONN", &gIX.VCONN)) { - TSError("[%s] Unable to initialize plugin (disabled). Failed to reserve VCONN arg.", PLUGIN_NAME); - return; - } -#endif // Setup the global slot value TSUserArgSet(nullptr, gIX.GLB, (void *)"Global Data"); @@ -184,7 +157,6 @@ TSRemapNewInstance(int argc, char *argv[], void **ih, char * /* errbuf ATS_UNUSE ix->contp = TSContCreate(cont_remap, nullptr); TSContDataSet(ix->contp, static_cast(ix)); -#if NEW_APIS if (TS_SUCCESS != TSUserArgIndexNameLookup(TS_USER_ARGS_TXN, PLUGIN_NAME, &ix->TXN, nullptr)) { TSError("[%s] Failed to lookup TXN arg.", PLUGIN_NAME); return TS_ERROR; @@ -198,18 +170,6 @@ TSRemapNewInstance(int argc, char *argv[], void **ih, char * /* errbuf ATS_UNUSE TSError("[%s] Failed to lookup GLB arg.", PLUGIN_NAME); return TS_ERROR; } -#else - if (TS_SUCCESS != TSHttpTxnArgIndexNameLookup(PLUGIN_NAME, &ix->TXN, nullptr)) { - TSError("[%s] Failed to lookup TXN arg.", PLUGIN_NAME); - return TS_ERROR; - } else if (TS_SUCCESS != TSHttpSsnArgIndexNameLookup(PLUGIN_NAME, &ix->SSN, nullptr)) { - TSError("[%s] Failed to lookup SSN arg.", PLUGIN_NAME); - return TS_ERROR; - } else if (TS_SUCCESS != TSVConnArgIndexNameLookup(PLUGIN_NAME, &ix->VCONN, nullptr)) { - TSError("[%s] Failed to lookup VCONN arg.", PLUGIN_NAME); - return TS_ERROR; - } -#endif *ih = static_cast(ix); return TS_SUCCESS;