Repository: qpid-dispatch Updated Branches: refs/heads/tross-DISPATCH-179-1 fe3157c51 -> e490a7b36
DISPATCH-179 - Added DESIGN file with design notes for the router-core. Project: http://git-wip-us.apache.org/repos/asf/qpid-dispatch/repo Commit: http://git-wip-us.apache.org/repos/asf/qpid-dispatch/commit/e490a7b3 Tree: http://git-wip-us.apache.org/repos/asf/qpid-dispatch/tree/e490a7b3 Diff: http://git-wip-us.apache.org/repos/asf/qpid-dispatch/diff/e490a7b3 Branch: refs/heads/tross-DISPATCH-179-1 Commit: e490a7b3694eb18e25f2ead1d7cd613475f322f9 Parents: fe3157c Author: Ted Ross <[email protected]> Authored: Tue Jan 5 13:42:51 2016 -0500 Committer: Ted Ross <[email protected]> Committed: Tue Jan 5 13:42:51 2016 -0500 ---------------------------------------------------------------------- src/router_core/DESIGN | 165 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 165 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/e490a7b3/src/router_core/DESIGN ---------------------------------------------------------------------- diff --git a/src/router_core/DESIGN b/src/router_core/DESIGN new file mode 100644 index 0000000..8e1ac10 --- /dev/null +++ b/src/router_core/DESIGN @@ -0,0 +1,165 @@ + ============================================================ + 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. + ============================================================ + + + +================= +General Structure +================= + + +--------------------------------+ + | Router Core Thread (CT) | + | ----------- + | ||||| ---> General Callbacks + action queue ----------- + Async ------------ | + Action ---> ||||||| -> | + Functions ------------ ----------- + | |||||-- + | -----------||-- ---> Connection Callbacks + | Forwarding Tables -----------|| + | ----------- + | | + +--------------------------------+ + + The above APIs are declared in include/qpid/dispatch/router_core.h + + The asynchronous action functions place an action on the action queue. The core + thread processes the actions serially. + + General callbacks are invoked on one of the IO threads using a zero-duration + timer. General callbacks are not specific to a connection context. + + Connection callbacks are invoked on a thread that is exclusively dedicated to a + connection. The body of a connection callback may safely access any object or data + structure that is associated with the connection, including Proton data. Multiple + connections may be processed concurrently on separate threads. + + +=================== +Router Core Objects +=================== + + qdr_core_t + + Core object containing one core thread and offering the core API. + + qdr_subscription_t + + Local subscription for receiving messages in-process. This is used by the + router-control module and the management agent. + + qdr_connection_t + qdr_link_t + qdr_delivery_t + + Tracking objects for connections, links, and deliveries. These must be linked with + their corresponding external object: + + qdr_connection_t <---> qd_connection_t + qdr_link_t <---> qd_link_t + qdr_delivery_t <---> pn_delivery_t + + Linkage is accomplished using the TYPE_set_context() methods. + + qdr_terminus_t + qdr_error_t + + The terminus and error objects are used to hold all of the content of a Proton + terminus and error state. These are needed to ensure that these Proton state + objects are not ever held within the core thread where thread safety with Proton + may be a problem. + + +=========== +Action APIs +=========== + + Router Control + + Interface to the router-control module which tracks remote routers, neighbor + routers, computes the best next-hops for each remote router, and maintains the + mapping of mobile addresses to remote routers. + + In-process Subscription and Send + + Used by in-process components that need to communicate using AMQP message + transfers. This API provides a best-effort messaging capability. It does not + provide acknowledgement, settlement, or flow control. + + Connection Actions + + Tracks the lifecycle of a connection: Opened, Closed, Process (writable) + + Link Actions + + Tracks the lifecycle of a link: First-Attach, Second-Attach, Detach, Deliver + + Delivery Actions + + Tracks the lifecycle of a delivery: Update-Disposition, Flow + + Management Actions + + Provides asynchronous access to manageable entities inside the core thread's data + structures. + + Create, Delete, Read, Update, Query + + This management API is used to manage addresses, waypoints, and link-route + destinations. + + +==================== +Forwarding Semantics +==================== + + Transition from fanout/bias to a one-dimensional list of semantics: + + MULTICAST_FLOOD + + Messages are delivered to all subscribers via all unique paths. If there is + redundancy in the router topology, multiple copies of each message will be + delivered to some destinations. + + This semantic behavior should be avoided (not exposed?). It is needed for a + subset of the protocol messages used for router control. + + MULTICAST_ONCE + + Messages are delivered to all subscribers once. This uses the valid-origins in + concert with the ingress-router message annotation to prevent deliveries from + being delivered multiply. + + ANYCAST_CLOSEST + + Messages are delivered to one subscriber. The chosen subscriber is the one + that has the lowest hop-cost from the producer. If there are multiple + consumers with the same lowest cost, deliveries are spread across all of those + subscribers in a round-robin manner. + + ANYCAST_BALANCED + + Messages are delivered to one subscriber. The chosen subscriber is the one + with the lowest number of unsettled deliveries regardless of its location in + the network topology. + + LINK_BALANCED + + For link-routes. --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
