trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From a..@apache.org
Subject [trafficserver] branch master updated: Doc: Update TSConfig... functions.
Date Mon, 06 May 2019 22:26:51 GMT
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 <amc@apache.org>
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);


Mime
View raw message