This is an automated email from the ASF dual-hosted git repository.
amc pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver.git
The following commit(s) were added to refs/heads/master by this push:
new 529f943 Doc: Update TSConfig... functions.
529f943 is described below
commit 529f943583eb520fb9d4fbdd1b3a64c8b5c27536
Author: Alan M. Carroll <[email protected]>
AuthorDate: Mon May 6 16:31:46 2019 -0500
Doc: Update TSConfig... functions.
---
doc/developer-guide/api/functions/TSConfig.en.rst | 86 ++++++++++++++++++++++
.../api/functions/TSConfigDataGet.en.rst | 32 --------
.../api/functions/TSConfigGet.en.rst | 32 --------
.../api/functions/TSConfigRelease.en.rst | 32 --------
.../api/functions/TSConfigSet.en.rst | 32 --------
src/traffic_server/InkAPITest.cc | 18 ++---
6 files changed, 91 insertions(+), 141 deletions(-)
diff --git a/doc/developer-guide/api/functions/TSConfig.en.rst
b/doc/developer-guide/api/functions/TSConfig.en.rst
new file mode 100644
index 0000000..d01dd20
--- /dev/null
+++ b/doc/developer-guide/api/functions/TSConfig.en.rst
@@ -0,0 +1,86 @@
+.. 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
+
+TSConfig Functions
+******************
+
+Synopsis
+========
+
+`#include <ts/ts.h>`
+
+.. type:: void (*TSConfigDestroyFunc)(void*)
+.. function:: unsigned int TSConfigSet(unsigned int id, void * data,
TSConfigDestroyFunc funcp)
+.. function:: TSConfig TSConfigGet(unsigned int id)
+.. function:: void TSConfigRelease(unsigned int id, TSConfig configp)
+.. function:: void* TSConfigDataGet(TSConfig configp)
+
+Description
+===========
+
+These functions provide a mechanism to safely update configurations for a
plugin.
+
+If a plugin stores its configuration in a data structure, updating that
structure due to changes in
+the configuration file can be dangerous due to the asynchonous nature of
plugin callbacks. To avoid
+that problem these functions allow a plugin to register a configuration and
then later replace it
+with another instance without changing the instance in use by plugin
callbacks. This works in the
+same manner as `shared pointer
<https://en.wikipedia.org/wiki/Smart_pointer>`__. When a plugin needs
+to access the configuration data, it calls :func:`TSConfigGet` which returns a
pointer that will
+remain valid until the plugin calls :func:`TSConfigRelease`. The configuration
instance is updated
+with :func:`TSConfigSet` which will update an internal pointer but will not
change any instance in
+use via :func:`TSConfigGet`. When the last in use pointer is released, the old
configuration is
+destructed using the function passed to func:`TSConfigSet`. This handles the
overlapping
+configuration update case correctly.
+
+Initialization is done with :func:`TSConfigSet`. The :arg:`id` should be zero
on the first call.
+This will allocate a slot for the configuration, which is returned. Subsequent
calls must use this
+value. If the :arg:`id` is not zero, that value is returned. In general, the
code will look
+something like ::
+
+ class Config { ... }; // Configuration data.
+ int Config_Id = 0;
+ //...
+ void ConfigUpdate() {
+ Config* cfg = new Config;
+ cfg.load(); // load config...
+ Config_Id = TSConfigSet(Config_Id, cfg,
+ [](void* cfg){delete static_cast<Config*>(config);});
+ }
+ //...
+ PluginInit() {
+ // ...
+ ConfigUpdate();
+ // ...
+ }
+
+:code:`Config_Id` is a global variable holding the configuration id, which is
updated by the
+return value of :func:`TSConfigSet`.
+
+The configuration instance is retrieved with :func:`TSConfigGet`. This returns
a wrapper class from
+which the configuration can be extracted with :func:`TSConfigDataGet`. The
wrapper is used to
+release the configuration instance when it is no longer in use. The code in a
callback tends to look
+like ::
+
+ int callback() {
+ auto cfg_ref = TSConfigGet(Config_Id);
+ Config* cfg = static_cast<Config*>(TSConfigDataGet(cfg_ref));
+ // ... use cfg
+ TSConfigRelease(Config_Id, cfg_ref);
+ }
diff --git a/doc/developer-guide/api/functions/TSConfigDataGet.en.rst
b/doc/developer-guide/api/functions/TSConfigDataGet.en.rst
deleted file mode 100644
index 3cff51f..0000000
--- a/doc/developer-guide/api/functions/TSConfigDataGet.en.rst
+++ /dev/null
@@ -1,32 +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
-
-TSConfigDataGet
-***************
-
-Synopsis
-========
-
-`#include <ts/ts.h>`
-
-.. function:: void* TSConfigDataGet(TSConfig configp)
-
-Description
-===========
diff --git a/doc/developer-guide/api/functions/TSConfigGet.en.rst
b/doc/developer-guide/api/functions/TSConfigGet.en.rst
deleted file mode 100644
index 8388bb8..0000000
--- a/doc/developer-guide/api/functions/TSConfigGet.en.rst
+++ /dev/null
@@ -1,32 +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
-
-TSConfigGet
-***********
-
-Synopsis
-========
-
-`#include <ts/ts.h>`
-
-.. function:: TSConfig TSConfigGet(unsigned int id)
-
-Description
-===========
diff --git a/doc/developer-guide/api/functions/TSConfigRelease.en.rst
b/doc/developer-guide/api/functions/TSConfigRelease.en.rst
deleted file mode 100644
index b4b49db..0000000
--- a/doc/developer-guide/api/functions/TSConfigRelease.en.rst
+++ /dev/null
@@ -1,32 +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
-
-TSConfigRelease
-***************
-
-Synopsis
-========
-
-`#include <ts/ts.h>`
-
-.. function:: void TSConfigRelease(unsigned int id, TSConfig configp)
-
-Description
-===========
diff --git a/doc/developer-guide/api/functions/TSConfigSet.en.rst
b/doc/developer-guide/api/functions/TSConfigSet.en.rst
deleted file mode 100644
index c0383b6..0000000
--- a/doc/developer-guide/api/functions/TSConfigSet.en.rst
+++ /dev/null
@@ -1,32 +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
-
-TSConfigSet
-***********
-
-Synopsis
-========
-
-`#include <ts/ts.h>`
-
-.. function:: unsigned int TSConfigSet(unsigned int id, void * data,
TSConfigDestroyFunc funcp)
-
-Description
-===========
diff --git a/src/traffic_server/InkAPITest.cc b/src/traffic_server/InkAPITest.cc
index 00daa08..6b0bfb0 100644
--- a/src/traffic_server/InkAPITest.cc
+++ b/src/traffic_server/InkAPITest.cc
@@ -1313,28 +1313,20 @@ REGRESSION_TEST(SDK_API_TSPluginDirGet)(RegressionTest
*test, int /* atype ATS_U
// TSConfigRelease
// TSConfigDataGet
////////////////////////////////////////////////
-static int my_config_id = -1;
-typedef struct {
+static int my_config_id = 0;
+struct ConfigData {
const char *a;
const char *b;
-} ConfigData;
-
-static void
-config_destroy_func(void *data)
-{
- ConfigData *config = (ConfigData *)data;
- TSfree(config);
- return;
-}
+};
REGRESSION_TEST(SDK_API_TSConfig)(RegressionTest *test, int /* atype
ATS_UNUSED */, int *pstatus)
{
*pstatus = REGRESSION_TEST_INPROGRESS;
- ConfigData *config = (ConfigData *)TSmalloc(sizeof(ConfigData));
+ ConfigData *config = new ConfigData;
config->a = "unit";
config->b = "test";
- my_config_id = TSConfigSet(0, config, config_destroy_func);
+ my_config_id = TSConfigSet(my_config_id, config, [](void *cfg) { delete
static_cast<ConfigData *>(cfg); });
TSConfig test_config = nullptr;
test_config = TSConfigGet(my_config_id);
