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 1c42919 TS-4976: Regularize plugins - hello
1c42919 is described below
commit 1c4291970a58ff285fc82450a5c3467a00d50d7b
Author: Alan M. Carroll <[email protected]>
AuthorDate: Fri Mar 17 10:33:24 2017 -0500
TS-4976: Regularize plugins - hello
---
.../api/functions/TSPluginInit.en.rst | 29 +++++----
.../api/functions/TSTrafficServerVersionGet.en.rst | 11 ++--
.../plugins/getting-started/a-simple-plugin.en.rst | 74 ++++++++++------------
doc/developer-guide/plugins/introduction.en.rst | 3 +-
example/hello/hello.c | 15 +++--
5 files changed, 65 insertions(+), 67 deletions(-)
diff --git a/doc/developer-guide/api/functions/TSPluginInit.en.rst
b/doc/developer-guide/api/functions/TSPluginInit.en.rst
index 79ce8fd..94ac644 100644
--- a/doc/developer-guide/api/functions/TSPluginInit.en.rst
+++ b/doc/developer-guide/api/functions/TSPluginInit.en.rst
@@ -59,20 +59,21 @@ Examples
::
- #include <ts/ts.h>
-
- void
- TSPluginInit (int argc, const char *argv[])
- {
- TSPluginRegistrationInfo info;
- info.plugin_name = "hello-world";
- info.vendor_name = "MyCompany";
- info.support_email = "[email protected]";
-
- if (TSPluginRegister(&info) != TS_SUCCESS) {
- TSError("Plugin registration failed. 0);
- }
- }
+ #include <ts/ts.h>
+ #define PLUGIN_NAME "hello_world"
+
+ void
+ TSPluginInit (int argc, const char * argv[])
+ {
+ TSPluginRegistrationInfo info;
+ info.plugin_name = PLUGIN_NAME;
+ info.vendor_name = "MyCompany";
+ info.support_email = "[email protected]";
+
+ if (TSPluginRegister(&info) != TS_SUCCESS) {
+ TSError("[%s] Plugin registration failed.", PLUGIN_NAME);
+ }
+ }
See Also
========
diff --git a/doc/developer-guide/api/functions/TSTrafficServerVersionGet.en.rst
b/doc/developer-guide/api/functions/TSTrafficServerVersionGet.en.rst
index ec332dc..a0d20a6 100644
--- a/doc/developer-guide/api/functions/TSTrafficServerVersionGet.en.rst
+++ b/doc/developer-guide/api/functions/TSTrafficServerVersionGet.en.rst
@@ -51,6 +51,8 @@ Example
#include <stdio.h>
#include <ts/ts.h>
+ #define PLUGIN_NAME "hello_world"
+
int
check_ts_version()
{
@@ -80,20 +82,21 @@ Example
TSPluginInit (int argc, const char *argv[])
{
TSPluginRegistrationInfo info;
- info.plugin_name = "hello-world";
+
+ info.plugin_name = PLUGIN_NAME;
info.vendor_name = "MyCompany";
info.support_email = "[email protected]";
if (TSPluginRegister(&info) != TS_SUCCESS) {
- TSError("Plugin registration failed. 0);
+ TSError("[%s] Plugin registration failed.", PLUGIN_NAME);
}
if (!check_ts_version()) {
- TSError("Plugin requires Traffic Server 3.0 or later0);
+ TSError("[%s] Plugin requires Traffic Server 3.0 or later",
PLUGIN_NAME);
return;
}
- TSDebug("debug-hello", "Hello World!0);
+ TSDebug(PLUGIN_NAME, "Hello World!");
}
See Also
diff --git a/doc/developer-guide/plugins/getting-started/a-simple-plugin.en.rst
b/doc/developer-guide/plugins/getting-started/a-simple-plugin.en.rst
index 64bed89..04f6a32 100644
--- a/doc/developer-guide/plugins/getting-started/a-simple-plugin.en.rst
+++ b/doc/developer-guide/plugins/getting-started/a-simple-plugin.en.rst
@@ -25,20 +25,19 @@ A Simple Plugin
This section describes how to write, compile, configure, and run a
simple Traffic Server plugin. You'll follow the steps below:
-1. Make sure that your plugin source code contains an ``TSPluginInit``
+1. Make sure that your plugin source code contains an :c:func:`TSPluginInit`
initialization function.
2. Compile your plugin source code, creating a shared library.
-3. Add an entry to your plugin's ``plugin.config`` file.
+3. Add an entry to :file:`plugin.config`.
-4. Add the path to your plugin shared library into the
- :file:`records.config` file.
+4. Add the path to your plugin shared library into :file:`records.config`.
5. Restart Traffic Server.
Compile Your Plugin
-~~~~~~~~~~~~~~~~~~~
+===================
The process for compiling a shared library varies with the platform
used, so the Traffic Server API provides the tsxs tool which you can use
@@ -46,47 +45,40 @@ to create shared libraries on all the supported Traffic
Server
platforms.
Example
-^^^^^^^
+-------
-Assuming the sample program is stored in the file ``hello-world.c``, you
-could use the following commands to build a shared library
+Assuming the sample program is stored in the file ``hello_world.c``, you
+could use the following commands to build a shared library::
-::
-
- tsxs -o hello-world.so -c hello-world.c
+ tsxs -o hello_world.so -c hello_world.c
-tsxs can be found in ``trafficserver-dev`` package.
+``tsxs`` is installed in the ``bin`` directory of |TS|.
-This shared library will be your plugin. In order to install it, run
-
-::
+This shared library will be your plugin. In order to install it, run::
- sudo tsxs -o hello-world.so -i
+ sudo tsxs -o hello_world.so -i
or the equivalent to ``sudo`` on your platform.
-Update the ``plugin.config`` File
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Update the plugin configuration file
+====================================
Your next step is to tell Traffic Server about the plugin by adding the
-following line to the ``plugin.config`` file. Since our simple plugin
-does not require any arguments, the following ``plugin.config`` will
-work:
+following line to :file:`plugin.config` file. Since our simple plugin
+does not require any arguments, the following :file:`plugin.config` will
+work::
-::
-
- # a simple plugin.config for hello-world
- hello-world.so
+ # a simple plugin.config for hello_world
+ hello_world.so
-Traffic Server can accommodate multiple plugins. If several plugin
+|TS| can accommodate multiple plugins. If several plugin
functions are triggered by the same event, then Traffic Server invokes
-each plugin's function in the order each was defined in the
-``plugin.config`` file.
+each plugin's function in the order each was defined in :file:`plugin.config`.
.. _specify-the-plugins-location:
Specify the Plugin's Location
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=============================
All plugins must be located in the directory specified by the
configuration variable ``proxy.config.plugin.plugin_dir``, which is
@@ -95,32 +87,34 @@ as an absolute or relative path.
If a relative path is used, then the starting directory will be the
Traffic Server installation directory as specified in
-``/etc/traffic_server``. The default value is ``libexec/trafficserver``,
+``etc/traffic_server``. The default value is ``libexec/trafficserver``,
but this can vary based on how the software was configured and built. It
is common to use the default directory. Be sure to place the shared
-library ``hello-world.so`` inside the directory you've configured.
+library ``hello_world.so`` inside the directory you've configured.
Restart Traffic Server
-~~~~~~~~~~~~~~~~~~~~~~
+======================
The last step is to start/restart Traffic Server. Shown below is the
-output displayed after you've created and loaded your ``hello-world``
+output displayed after you've created and loaded your ``hello_world``
plugin.
::
# ls libexec/trafficserver
- hello-world.so*
+ hello_world.so*
# bin/traffic_server
[Mar 27 19:06:31.669] NOTE: updated diags config
- [Mar 27 19:06:31.680] NOTE: loading plugin
'libexec/trafficserver/hello-world.so'
+ [Mar 27 19:06:31.680] NOTE: loading plugin
'libexec/trafficserver/hello_world.so'
hello world
[Mar 27 19:06:32.046] NOTE: cache disabled (initializing)
[Mar 27 19:06:32.053] NOTE: cache enabled
[Mar 27 19:06:32.526] NOTE: Traffic Server running
-**Note:** in the example above, Traffic Server notes are directed to the
-console by specifying ``E`` for ``proxy.config.diags.output.note`` in
-:file:`records.config`. The second note shows Traffic Server attempting to
-load the ``hello-world`` plugin. The third line of Traffic Server output
-is from your plugin.
+.. note::
+
+ In the example above, Traffic Server notes are directed to the
+ console by specifying ``E`` for :ts:cv:`proxy.config.diags.output.note` in
+ :file:`records.config`. The second note shows Traffic Server attempting to
+ load the ``hello_world`` plugin. The third line of Traffic Server output
+ is from your plugin.
diff --git a/doc/developer-guide/plugins/introduction.en.rst
b/doc/developer-guide/plugins/introduction.en.rst
index d051b68..31a61da 100644
--- a/doc/developer-guide/plugins/introduction.en.rst
+++ b/doc/developer-guide/plugins/introduction.en.rst
@@ -158,7 +158,7 @@ back to sleep & waits for the next event.
Traffic Server Internals
Plugins are typically implemented as continuations. All of the sample
-code plugins (except ``hello-world``) are continuations that are created
+code plugins (except ``hello_world``) are continuations that are created
when Traffic Server starts up; they then wait for events that trigger
them into activity.
@@ -305,4 +305,3 @@ transaction further on, then the plugin adds itself to a
transaction
hook. *Transformation plugins* require a global hook to check
all transactions for transformability followed by a *transform hook*,
which is a type of transaction hook used specifically for transforms.
-
diff --git a/example/hello/hello.c b/example/hello/hello.c
index 6ae076d..34df0f7 100644
--- a/example/hello/hello.c
+++ b/example/hello/hello.c
@@ -24,20 +24,21 @@
#include <stdio.h>
#include "ts/ts.h"
-#include "ts/ink_defs.h"
+
+#define PLUGIN_NAME "hello"
void
-TSPluginInit(int argc ATS_UNUSED, const char *argv[] ATS_UNUSED)
+TSPluginInit(int argc, const char *argv[])
{
TSPluginRegistrationInfo info;
- info.plugin_name = "hello-world";
- info.vendor_name = "MyCompany";
- info.support_email = "[email protected]";
+ info.plugin_name = PLUGIN_NAME;
+ info.vendor_name = "Apache Software Foundation";
+ info.support_email = "[email protected]";
if (TSPluginRegister(&info) != TS_SUCCESS) {
- TSError("[hello-world] Plugin registration failed.");
+ TSError("[%s] Plugin registration failed.", PLUGIN_NAME);
}
- TSDebug("debug-hello", "Hello World!");
+ TSDebug(PLUGIN_NAME, "Hello World!");
}
--
To stop receiving notification emails like this one, please contact
['"[email protected]" <[email protected]>'].
