You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by am...@apache.org on 2018/03/22 15:40:19 UTC
[trafficserver] branch master updated: rpc doc
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 4a1d70d rpc doc
4a1d70d is described below
commit 4a1d70dede464b390ec3060b4c7bd96971a97a96
Author: Alan Wang <xf...@gmail.com>
AuthorDate: Wed Feb 28 09:43:48 2018 -0800
rpc doc
---
doc/developer-guide/api/types/SystemTypes.en.rst | 15 +-
doc/developer-guide/api/types/TSMgmtTypes.en.rst | 189 ++++++++++++++
doc/developer-guide/core-architecture/index.en.rst | 28 +++
doc/developer-guide/core-architecture/rpc.en.rst | 280 +++++++++++++++++++++
doc/developer-guide/index.en.rst | 1 +
doc/uml/RPC-sequence-diagram.uml | 45 ++++
doc/uml/RPC-states.uml | 73 ++++++
7 files changed, 628 insertions(+), 3 deletions(-)
diff --git a/doc/developer-guide/api/types/SystemTypes.en.rst b/doc/developer-guide/api/types/SystemTypes.en.rst
index aed6390..477288d 100644
--- a/doc/developer-guide/api/types/SystemTypes.en.rst
+++ b/doc/developer-guide/api/types/SystemTypes.en.rst
@@ -56,17 +56,22 @@ These types are provided by the compiler ("built-in") or from a required operati
.. cpp:type:: uint16_t
`Reference <https://linux.die.net/include/stdint.h>`__.
+
.. cpp:type:: uint8_t
`Reference <https://linux.die.net/include/stdint.h>`__.
+.. cpp:type:: intmax_t
+
+ The largest native signed integer type.
+
.. cpp:type:: size_t
- `Reference <https://linux.die.net/include/stdint.h>`__.
+ Unsigned integral type.
-.. cpp:type:: intmax_t
+.. cpp:type:: ssize_t
- The largest native signed integer type.
+ Signed integral type.
.. cpp:type:: unspecified_type
@@ -75,3 +80,7 @@ These types are provided by the compiler ("built-in") or from a required operati
.. cpp:type:: time_t
Epoch time, in seconds.
+
+.. cpp:type:: va_list
+
+ Variable Argument List.
diff --git a/doc/developer-guide/api/types/TSMgmtTypes.en.rst b/doc/developer-guide/api/types/TSMgmtTypes.en.rst
new file mode 100644
index 0000000..9985319
--- /dev/null
+++ b/doc/developer-guide/api/types/TSMgmtTypes.en.rst
@@ -0,0 +1,189 @@
+
+.. 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
+
+TSMgmt
+******
+
+Synopsis
+========
+
+Macros used for RPC communications.
+
+Management Signals
+==================
+
+.. c:macro:: MGMT_SIGNAL_PID
+
+.. c:macro:: MGMT_SIGNAL_MACHINE_UP
+
+.. c:macro:: MGMT_SIGNAL_MACHINE_DOWN
+
+.. c:macro:: MGMT_SIGNAL_CONFIG_ERROR
+
+.. c:macro:: MGMT_SIGNAL_SYSTEM_ERROR
+
+.. c:macro:: MGMT_SIGNAL_LOG_SPACE_CRISIS
+
+.. c:macro:: MGMT_SIGNAL_CONFIG_FILE_READ
+
+.. c:macro:: MGMT_SIGNAL_CACHE_ERROR
+
+.. c:macro:: MGMT_SIGNAL_CACHE_WARNING
+
+.. c:macro:: MGMT_SIGNAL_LOGGING_ERROR
+
+.. c:macro:: MGMT_SIGNAL_LOGGING_WARNING
+
+.. c:macro:: MGMT_SIGNAL_PLUGIN_SET_CONFIG
+
+.. c:macro:: MGMT_SIGNAL_LOG_FILES_ROLLED
+
+.. c:macro:: MGMT_SIGNAL_LIBRECORDS
+
+.. c:macro:: MGMT_SIGNAL_HTTP_CONGESTED_SERVER
+
+.. c:macro:: MGMT_SIGNAL_HTTP_ALLEVIATED_SERVER
+
+.. c:macro:: MGMT_SIGNAL_CONFIG_FILE_CHILD
+
+.. c:macro:: MGMT_SIGNAL_SAC_SERVER_DOWN
+
+
+Management Events
+==================
+
+.. c:macro:: MGMT_EVENT_SYNC_KEY
+
+.. c:macro:: MGMT_EVENT_SHUTDOWN
+
+.. c:macro:: MGMT_EVENT_RESTART
+
+.. c:macro:: MGMT_EVENT_BOUNCE
+
+.. c:macro:: MGMT_EVENT_CLEAR_STATS
+
+.. c:macro:: MGMT_EVENT_CONFIG_FILE_UPDATE
+
+.. c:macro:: MGMT_EVENT_PLUGIN_CONFIG_UPDATE
+
+.. c:macro:: MGMT_EVENT_ROLL_LOG_FILES
+
+.. c:macro:: MGMT_EVENT_LIBRECORDS
+
+.. c:macro:: MGMT_EVENT_CONFIG_FILE_UPDATE_NO_INC_VERSION
+
+.. c:macro:: MGMT_EVENT_STORAGE_DEVICE_CMD_OFFLINE
+
+.. c:macro:: MGMT_EVENT_LIFECYCLE_MESSAGE
+
+
+OpTypes (Possible operations or msgs that can be sent between TM and remote clients)
+====================================================================================
+
+.. cpp:type:: OpType
+
+.. c:macro:: RECORD_SET
+
+.. c:macro:: RECORD_GET
+
+.. c:macro:: PROXY_STATE_GET
+
+.. c:macro:: PROXY_STATE_SET
+
+.. c:macro:: RECONFIGURE
+
+.. c:macro:: RESTART
+
+.. c:macro:: BOUNCE
+
+.. c:macro:: EVENT_RESOLVE
+
+.. c:macro:: EVENT_GET_MLT
+
+.. c:macro:: EVENT_ACTIVE
+
+.. c:macro:: EVENT_REG_CALLBACK,
+
+.. c:macro:: EVENT_UNREG_CALLBACK
+
+.. c:macro:: EVENT_NOTIFY
+
+.. c:macro:: STATS_RESET_NODE
+
+.. c:macro:: STORAGE_DEVICE_CMD_OFFLINE
+
+.. c:macro:: RECORD_MATCH_GET
+
+.. c:macro:: API_PING
+
+.. c:macro:: SERVER_BACKTRACE
+
+.. c:macro:: RECORD_DESCRIBE_CONFIG
+
+.. c:macro:: LIFECYCLE_MESSAGE
+
+.. c:macro:: UNDEFINED_OP
+
+
+TSMgmtError
+===========
+.. cpp:type:: TSMgmtError
+
+.. c:macro:: TS_ERR_OKAY
+
+.. c:macro:: TS_ERR_READ_FILE
+
+.. c:macro:: TS_ERR_WRITE_FILE
+
+.. c:macro:: TS_ERR_PARSE_CONFIG_RULE
+
+.. c:macro:: TS_ERR_INVALID_CONFIG_RULE
+
+.. c:macro:: TS_ERR_NET_ESTABLISH
+
+.. c:macro:: TS_ERR_NET_READ
+
+.. c:macro:: TS_ERR_NET_WRITE
+
+.. c:macro:: TS_ERR_NET_EOF
+
+.. c:macro:: TS_ERR_NET_TIMEOUT
+
+.. c:macro:: TS_ERR_SYS_CALL
+
+.. c:macro:: TS_ERR_PARAMS
+
+.. c:macro:: TS_ERR_NOT_SUPPORTED
+
+.. c:macro:: TS_ERR_PERMISSION_DENIED
+
+.. c:macro:: TS_ERR_FAIL
+
+
+MgmtMarshallType
+================
+.. cpp:type:: MgmtMarshallType
+
+.. c:macro:: MGMT_MARSHALL_INT
+
+.. c:macro:: MGMT_MARSHALL_LONG
+
+.. c:macro:: MGMT_MARSHALL_STRING
+
+.. c:macro:: MGMT_MARSHALL_DATA
\ No newline at end of file
diff --git a/doc/developer-guide/core-architecture/index.en.rst b/doc/developer-guide/core-architecture/index.en.rst
new file mode 100644
index 0000000..9b85375
--- /dev/null
+++ b/doc/developer-guide/core-architecture/index.en.rst
@@ -0,0 +1,28 @@
+.. 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
+
+.. _developer-core-architecture:
+
+Core Architecture
+*****************
+
+.. toctree::
+ :maxdepth: 1
+
+ rpc.en
\ No newline at end of file
diff --git a/doc/developer-guide/core-architecture/rpc.en.rst b/doc/developer-guide/core-architecture/rpc.en.rst
new file mode 100644
index 0000000..6d76349
--- /dev/null
+++ b/doc/developer-guide/core-architecture/rpc.en.rst
@@ -0,0 +1,280 @@
+.. 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
+
+.. highlight:: cpp
+.. default-domain:: cpp
+
+.. _developer-doc-rpc:
+
+.. |TServer| replace:: :program:`traffic_server`
+.. |TManager| replace:: :program:`traffic_manager`
+.. |TCtl| replace:: :program:`traffic_ctl`
+.. |LM| replace:: :class:`LocalManager`
+.. |PM| replace:: :class:`ProcessManager`
+
+RPC
+***
+
+========
+Overview
+========
+
+In order for programs in different address spaces (remote clients and |TManager|) to communicate with |TServer|, there is a RPC mechanism in :ts:git:`mgmt/`.
+
+This is a simple serialization style RPC which runs over unix domain sockets. The following sections will detail the runtime structure, serialization mechanisms and how messages are passed from remote clients to |TServer|.
+
+
+=================
+Runtime Structure
+=================
+
+.. uml::
+ :align: center
+
+ hide empty members
+
+ node "traffic_manager"
+ node "traffic_server"
+
+ [traffic_ctl] <-d-> [traffic_manager] : Remote RPC
+ [traffic_cop] <-r-> [traffic_manager] : Remote RPC
+ [other remote clients] <-u-> [traffic_manager] : Remote RPC
+ [traffic_manager] <-r-> [traffic_server] : Local RPC
+ [traffic_server] <-r-> [plugin] : Hook
+
+|TManager| opens a unix domain socket to recieve commands from remote clients. |TManager| also has a unix domain socket connection with |TServer| to communicate.
+
+===============
+Message Passing
+===============
+
+Sequence diagram for a command sent from |TCtl| to when it is recieved by a plugin.
+
+.. image:: ../../uml/images/RPC-sequence-diagram.svg
+
+.. note::
+
+ Currently a fire and forget model. traffic_manager sends out an asynchoronous signal without any acknowledgement. It then proceeds to send a response itself.
+
+=======================
+Remote RPC vs Local RPC
+=======================
+
+The RPC API for remote clients, such as |TCtl|, :program:`traffic_cop`, etc, is different from the RPC API used between |TManager| and |TServer|.
+
+|TManager| acts like a bridge for remote clients to interact with |TServer|. Thus, it is currently impossible to do things like have |TCtl| directly send messages to |TServer|. Classes suffixed with "Remote", ie. :ts:git:`CoreAPIRemote.cc`, and classes suffixed with "Local", ie. :ts:git:`NetworkUtilsLocal.cc` are for remote and local clients, respectively. The following sections will note which set of RPC's are relevant.
+
+=======================
+Serialization Mechanism
+=======================
+
+.. class:: MgmtMarshall
+
+ This is the class used to marshall data objects. It provides functions to marshall and unmarshall data. Each data object is associated with a field. Fields are of :type:`MgmtMarshallType`:
+
+ - **MGMT_MARSHALL_INT** : 4 bytes.
+ - **MGMT_MARSHALL_LONG** : 8 bytes.
+ - **MGMT_MARSHALL_STRING** : 4 bytes to indicate the string size in bytes, followed by the entire string and NULL terminator.
+ - **MGMT_MARSHALL_DATA** : 4 byt es to indicate data size in bytes, followed by the entire data object.
+
+When data is actually sent over a connection it must first be seralized. This is the general serialization mechanism for RPC communcation.
+
+Generally, for remote clients sending messages to |TServer|, the message is serialized using remote RPC APIs. The serialized message is sent to |TManager| and |TManager| then simply relays the message to |TServer|. |TServer| eventually unserializes the message.
+
+Details for how |TManager| and |TServer| communicate are documented in the next section.
+
+Marshalling:
+============
+
+ .. function:: ssize_t mgmt_message_marshall(void *buf, size_t remain, const MgmtMarshallType *fields, unsigned count, ...)
+
+ Variable argument wrapper for ``mgmt_message_marshall_v``. Allows for different datatypes to be marshalled together as long as a field is specified for each data object. Arguments should be references to objects to be marshalled.
+
+ .. function:: ssize_t mgmt_message_marshall_v(void *buf, size_t remain, const MgmtMarshallType *fields, unsigned count, va_list ap)
+
+ This function goes through all the data objects and serializes them together into a buffer. Based on the field, the number of bytes is determined and if there is enough space, it is written into the buffer.
+
+Unmarshalling:
+==============
+
+ .. function:: ssize_t mgmt_message_parse(const void *buf, size_t len, const MgmtMarshallType *fields, unsigned count, ...)
+
+ Variable argument wrapper for ``mgmt_message_parse_v``. Reference to data object to store unmarshalled message needed for variable arguements.
+
+ .. function:: ssize_t mgmt_message_parse_v(const void *buf, size_t len, const MgmtMarshallType *fields, unsigned count, va_list ap)
+
+ This function parses all the serialized. Based on the field, the number of bytes to be read is determined and copied into a ``MgmtMarshallAnyPtr``.
+
+===================
+Local Serialization
+===================
+
+A RPC message is sent as a :class:`MgmtMessageHdr` followed by the serialized data in bytes. Serialization is very simple as the inteface for communication between |TManager| and |TServer| only allows for :class:`MgmtMessageHdr`, which is a fixed size, and raw data in the form of :code:`char*` to be sent. A header specifies a :arg:`msg_id` and the :arg:`data_len`. On a read, the header is *always* first read. Based on the length of the data payload, the correct number of bytes is then re [...]
+
+.. class:: MgmtMessageHdr
+
+ .. member:: int msg_id
+
+ ID for the event or signal to be sent.
+
+ .. member:: int data_len
+
+ Length in bytes of the message.
+
+.. uml::
+
+ |Write|
+ start
+ :populate msg_id;
+ :populate data_len;
+ |#LightGreen|Socket|
+ :send MgmtMessageHdr;
+ |Write|
+ :get the raw data;
+ note left : casts from\nchar* to void*
+ |Socket|
+ :send raw data;
+ |Read|
+ :different address space;
+ : ...\nsome time later;
+ |Socket|
+ :read MgmtMessageHdr;
+ |Read|
+ :get data_len;
+ |Socket|
+ :read data_len bytes;
+ |Read|
+ :choose callback based on msg_id\nand send raw data;
+ stop
+
+==========================
+RPC API for remote clients
+==========================
+
+:ts:git:`NetworkMessage.cc` provides a set of APIs for remote clients to communicate with |TManager|.
+
+|TManager| will then send a response with the return value. The return value only indicates if the request was successfully propogated to |TServer|. Thus, there is no way currently for |TServer| to send information back to remote clients.
+
+.. function:: TSMgmtError send_mgmt_request(const mgmt_message_sender &snd, OpType optype, ...)
+.. function:: TSMgmtError send_mgmt_request(int fd, OpType optype, ...)
+
+ Send a request from a remote client to |TManager|.
+
+.. function:: TSMgmtError send_mgmt_response(int fd, OpType optype, ...)
+
+ Send a response from |TManager| to remote client.
+
+.. function:: TSMgmtError send_mgmt_error(int fd, OpType optype, TSMgmtError error)
+
+ Send err from |TManager| to remote client.
+
+.. function:: TSMgmtError recv_mgmt_request(void *buf, size_t buflen, OpType optype, ...)
+
+ Read request from remote client. Used by |TManager|.
+
+.. function:: TSMgmtError recv_mgmt_response(void *buf, size_t buflen, OpType optype, ...)
+
+ Read response from |TManager|. Used by remote clients.
+
+Using Remote RPC API Example
+============================
+
+This details how a remote client may use the :ts:git:`NetworkMessage.cc` interface to send messages to |TManager|. Leveraging :func:`send_mgmt_request` with a :class:`mgmt_message_sender` which specifies how *send* a message, a remote client can implement its own way to send messages to |TManager| to allow for things such as preprocessing messages.
+
+.. class:: mgmt_message_sender
+
+.. class:: mgmtapi_sender : public mgmt_message_sender
+
+ .. function:: TSMgmtError send(void *msg, size_t msglen) const override
+
+ Specifies how the message is to be sent. Can do things such as serialization or preprocessing based on parameters.
+
+.. code-block:: cpp
+
+ #define MGMTAPI_SEND_MESSAGE(fd, optype, ...) send_mgmt_request(mgmtapi_sender(fd), (optype), __VA_ARGS__)
+
+Now, using this macro, messages can easily be sent. For example:
+
+.. code-block:: cpp
+
+ TSMgmtError ret;
+ MgmtMarshallData reply = {nullptr, 0};
+
+ // create and send request
+ ret = MGMTAPI_SEND_MESSAGE(main_socket_fd, op, &optype);
+ if (ret != TS_ERR_OKAY) {
+ goto done;
+ }
+
+ // get a response
+ ret = recv_mgmt_message(main_socket_fd, reply);
+ if (ret != TS_ERR_OKAY) {
+ goto done;
+ }
+
+====================================
+RPC API for |TServer| and |TManager|
+====================================
+
+.. image:: ../../uml/images/RPC-states.svg
+ :align: center
+
+|LM| and |PM| follow similar workflows. A manager will poll the socket for any messages. If it is able to read a message, it will handle it based on the :arg:`msg_id` from the :class:`MgmtMessageHdr` and select a callback to run asynchoronously. The async callback will add a response, if any, to an outgoing event queue within the class. A manager will continue to poll and read on the socket as long as there are messages avaliable. Two things can stop a manager from polling.
+
+1. there are no longer any messages on the socket for a *timeout* time period.
+
+#. an external event, for example, a |TCtl| command, triggers an ``eventfd`` to tell the manager to stop polling. In the case of an external event, the manager will finish reading anything on the socket, but it will not wait for any timeout period. So, if there are three pending events on the socket, all three will be processed and then immediately after, the manager will stop polling.
+
+Once a manager is done polling, it will begin to send out messages from it's outgoing event queue. It continues to do this until there are no more messages left. Note that as a manager is polling, it is unable to write anything on the socket itself so the number of messages read will always be exhaustive.
+
+.. class:: BaseManager
+
+LocalManager
+============
+
+.. class:: LocalManager : public BaseManager
+
+ This class is used by |TManager| to communicate with |TServer|
+
+ .. function:: void pollMgmtProcessServer()
+
+ This function watches the socket and handles incoming messages from processes. Used in the main event loop of |TManager|.
+
+ .. function:: void sendMgmtMsgToProcesses(MgmtMessageHdr *mh)
+
+ This function is used by |TManager| to process the messages based on :arg:`msg_id`. It then sends the message to |TServer| over sockets.
+
+ProcessManager
+==============
+
+.. class:: ProcessManager : public BaseManager
+
+ This class is used by |TServer| to communicate with |TManager|
+
+ .. function:: int pollLMConnection()
+
+ This function periodically polls the socket to see if there are any messages from the |LM|.
+
+ .. function:: void signalManager (int msg_id, const char *data_raw, int data_len)
+
+ This function sends messages to the |LM| using sockets.
+
+.. note::
+
+ 1. Both :func:`LocalManager::pollMgmtProcessServer` and :func:`ProcessManager::pollLMConnection` actually use ``select``, not ``poll`` or ``epoll``, underneath.
diff --git a/doc/developer-guide/index.en.rst b/doc/developer-guide/index.en.rst
index b1399c6..688203c 100644
--- a/doc/developer-guide/index.en.rst
+++ b/doc/developer-guide/index.en.rst
@@ -54,3 +54,4 @@ duplicate bugs is encouraged, but not required.
documentation/index.en
host-resolution-proposal.en
client-session-architecture.en
+ core-architecture/index.en
\ No newline at end of file
diff --git a/doc/uml/RPC-sequence-diagram.uml b/doc/uml/RPC-sequence-diagram.uml
new file mode 100644
index 0000000..08baf39
--- /dev/null
+++ b/doc/uml/RPC-sequence-diagram.uml
@@ -0,0 +1,45 @@
+' Licensed 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.
+
+@startuml
+
+actor user
+box "traffic_ctl address space" #DDFFDD
+entity traffic_ctl
+end box
+collections "Remote RPC API" as remote_rpc
+box "traffic_manager address space" #DDDDFF
+entity traffic_manager
+end box
+collections "Local RPC API" as local_rpc
+box "traffic_server address space" #FFDB99
+entity traffic_server
+end box
+entity plugin
+
+traffic_manager -> traffic_server : traffic_server registers\ncallback for ""MGMT_EVENT_LIFECYCLE_EVENT""
+traffic_server -> plugin : register to ""TS_LIFECYCLE_MSG_HOOK""
+user -> traffic_ctl : "traffic_ctl plugin msg TAG hello"
+traffic_ctl -> remote_rpc : lifecycle message
+note left : msd id ""MGMT_EVENT_LIFECYCLE_MESSAGE""
+remote_rpc -[#blue]-> remote_rpc : <font color="blue">//serialize message//</font>
+remote_rpc -> traffic_manager : sent over sockets
+note over traffic_ctl, traffic_manager : Using remote RPC functions\n""CoreAPIRemote, NetworkUtilsRemote""
+
+traffic_manager -[#blue]-> local_rpc: <font color="blue">//serialized message//</font>
+local_rpc -> traffic_server : resent over sockets
+note over traffic_manager, traffic_server : Local RPC functions\n""CoreAPI, NetworkUtilsLocal""
+traffic_server -> traffic_server : callback function selected based on msg id\n""MGMT_EVENT_LIFECYCLE_MESSAGE""
+traffic_server -[#blue]-> local_rpc : <font color="blue">//unserialize message//</font>
+traffic_server -> plugin : invoke hook and attach ""TSPluginMsg""
+plugin -> plugin : hooks ""TS_LIFECYCLE_MSG_HOOK""\nand reads ""TSPluginMsg""
+traffic_manager -[#green]-> remote_rpc : <font color="green">TS_ERR_OK</font>
+note right : traffic_manager has no idea if\nplugin actually recieved message
+remote_rpc -> traffic_ctl : parse response
+
+
+@enduml
\ No newline at end of file
diff --git a/doc/uml/RPC-states.uml b/doc/uml/RPC-states.uml
new file mode 100644
index 0000000..10ca6ad
--- /dev/null
+++ b/doc/uml/RPC-states.uml
@@ -0,0 +1,73 @@
+' Licensed 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.
+
+@startuml
+
+state "LocalManager\nruns in traffic_manager main event loop" as traffic_manager {
+ state "processEventQueue" as tm_process_events {
+ state "dequeue msg" as tm_dequeue : from ""mgmt_event_queue""
+ state "send msg to processes" as tm_send_events : ""sendMgmtMsgToProcesses""
+ tm_dequeue -d-> [*] : empty
+ tm_dequeue -d-> tm_send_events : based on msg_id
+ tm_send_events -u-> tm_dequeue
+ }
+
+ state "pollMgmtProcessServer" as tm_poll_ts {
+ state "poll socket" as tm_poll_sock : ""mgmt_select""
+ state "new connection" as tm_new_process : register new client socket fd\nto start getting msgs from\nclient
+ state "new message" as tm_new_message : new message from process
+ state "handle msg" as tm_handle_msg : ""handleMgmtMsgFromProcesses"" will\noften ""signalAlarm"" with recieved\nmsg_id
+
+ tm_poll_sock -d-> tm_new_process : new process trying to connect
+ tm_poll_sock -d-> tm_new_message : msg from ""traffic_server""
+ tm_poll_sock -d-> [*] : timed out
+ tm_new_message -d-> tm_handle_msg : based on msg_id
+ tm_handle_msg -u-> tm_poll_sock
+ tm_new_process -u-> tm_poll_sock
+
+ state "External Event" as tm_ext_event : mechanism to stop polling
+ tm_ext_event -u-> [*] : ""eventfd"" trigger
+ }
+
+ [*] -d-> tm_process_events
+ tm_process_events -d-> tm_poll_ts
+ tm_poll_ts -d-> [*] : other tasks ""traffic_manager"" is\nresponsible for including ""rotateLogs"",\nmanaging metrics and monitoring\n""traffic_server""
+}
+
+state "ProcessManager\nruns in processManagerThread from traffic_server" as traffic_server {
+ state "pollLMConnection" as ts_poll_tm {
+ state "poll socket" as ts_poll_sock : ""mgmt_read_timeout""
+ state "handle event" as ts_handle_event : ""executeMgmtCallback""
+ state "send response" as ts_response : enqueue response to ""mgmt_signal_queue""
+ ts_poll_sock -down-> ts_handle_event : handle based on ""msg_id""
+ ts_handle_event -d-> ts_response : callback enqueues response
+ ts_response -u-> ts_handle_event
+ ts_handle_event -u-> ts_poll_sock
+
+ ts_poll_sock -down-> [*] : timed out
+ state "External Event" as ts_ext_event : mechanism to stop polling
+ ts_ext_event -u-> [*] : ""eventfd"" trigger
+ }
+
+ state "processSignalQueue" as ts_send_signals {
+ state "dequeue signal" as ts_dequeue_signal : dequeue from ""mgmt_signal_queue""
+ state "send out msg" as ts_outgoing_msg : ""mgmt_write_pipe""
+ ts_dequeue_signal -d-> [*] : empty
+ ts_dequeue_signal -d-> ts_outgoing_msg : send out msg
+ ts_outgoing_msg -u-> ts_dequeue_signal
+
+ }
+ ts_send_signals : send outgoing messages via processSignalQueue
+ ts_poll_tm -down-> ts_send_signals
+ ts_send_signals -up-> ts_poll_tm
+}
+
+ts_send_signals -r-> tm_poll_ts : msg from ""traffic_server"" to ""traffic_manager""
+tm_process_events -l-> ts_poll_tm : msg from ""traffic_manager"" to ""traffic_server""
+
+
+@enduml
--
To stop receiving notification emails like this one, please contact
amc@apache.org.