3 ==================================================================================
4 Copyright (c) 2019-2020 Nokia
5 Copyright (c) 2018-2020 AT&T Intellectual Property.
7 Licensed under the Apache License, Version 2.0 (the "License");
8 you may not use this file except in compliance with the License.
9 You may obtain a copy of the License at
11 http://www.apache.org/licenses/LICENSE-2.0
13 Unless required by applicable law or agreed to in writing, software
14 distributed under the License is distributed on an "AS IS" BASIS,
15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 See the License for the specific language governing permissions and
17 limitations under the License.
18 ==================================================================================
24 &h1(Appendix &gloss_appendix -- Glossary)
26 Many terms in networking can be interpreted with multiple meanings,
27 and several terms used in various RMR documentation are RMR specific.
28 The following definitions are the meanings of terms used within RMR
29 documentation and should help the reader to understand the intent of
32 &beg_dlist( &1.0i Helvetica-bold : : 25,70 )
33 &ditem(application) A programme which uses RMR to send and/or receive
34 messages to/from another RMR based application.
36 &ditem(Critical error) An error that RMR has encountered which will
37 prevent further successful processing by
38 RMR. Critical errors usually indicate that the
39 application should abort.
41 &ditem(Endpoint) An RMR based application that is defined as being
42 capable of receiving one or more types of
43 messages (as defined by a &ital(routing key.)
46 &ditem(Environment variable) A key/value pair which is set externally
47 to the application, but which is available to
48 the application (and referenced libraries)
49 through the &cw(getenv) system
50 call. Environment variables are the main
51 method of communicating information such as
54 &ditem(Error) An abnormal condition that RMR has encountered, but will
55 not affect the overall processing by RMR, but
56 may impact certain aspects such as the ability
57 to communicate with a specific endpoint.
58 Errors generally indicate that something,
59 usually external to RMR, must be addressed.
61 &ditem(Host name) The name of the host as returned by the
62 &cw(gethostbyname) system call. In a
63 containerised environment this might be the
64 container or service name depending on how the
65 container is started. From RMR's point of
66 view, a host name can be used to resolve an
67 &ital(endpoint) definition in a &ital(route
70 &ditem(IP) Internet protocol. A low level transmission protocol
71 which governs the transmission of datagrams
72 across network boundaries.
74 &ditem(Listen socket) A &ital(TCP) socket used to await incoming
75 connection requests. Listen sockets are
76 defined by an interface and port number
77 combination where the port number is unique
80 &ditem(Message) A series of bytes transmitted from the application to
81 another RMR based application. A message is
82 comprised of RMR specific data (a header), and
83 application data (a payload).
85 &ditem(Message buffer) A data structure used to describe a message
86 which is to be sent or has been received. The
87 message buffer includes the payload length,
88 message type, message source, and other
91 &ditem(Message type) A signed integer (0-32000) which identifies the
92 type of message being transmitted, and is one
93 of the two components of a &ital(routing key.)
94 See &ital(Subscription ID.)
96 &ditem(Payload) The portion of a message which holds the user data to
97 be transmitted to the remote &ital(endpoint.)
98 The payload contents are completely
101 &ditem(RMR context) A set of information which defines the current
102 state of the underlying transport connections
103 that RMR is managing. The application will be
104 give a context reference (pointer) that is
105 supplied to most RMR functions as the first
108 &ditem(Round robin) The method of selecting an &ital(endpoint) from a
109 list such that all &ital(endpoints) are
110 selected before starting at the head of the list.
112 &ditem(Route table) A series of "rules" which define the possible
113 &ital(endpoints) for each &ital(routing key.)
115 &ditem(Route table manager) An application responsible for building a
116 &ital(route table) and then distributing it to
117 all applicable RMR based applications.
119 &ditem(Routing) The process of selecting an &ital(endpoint) which will
120 be the recipient of a message.
122 &ditem(Routing key) A combination of &ital(message type) and
123 &ital(subscription ID) which RMR uses to
124 select the destination &ital(endpoint) when
127 &ditem(Source) The sender of a message.
130 &ditem(Subscription ID) A signed integer value (0-32000) which
131 identifies the subscription characteristic of
132 a message. It is used in conjunction with the
133 &ital(message type) to determine the
136 &ditem(Target) The &ital(endpoint) selected to receive a message.
138 &ditem(TCP) Transmission Control Protocol. A connection based
139 internet protocol which provides for lossless
140 packet transportation, usually over IP.
142 &ditem(Thread) Also called a &ital(process thread, or pthread.) This
143 is a lightweight process which executes in
144 concurrently with the application and shares
145 the same address space. RMR uses threads to
146 manage asynchronous functions such as route
149 &ditem(Trace information) An optional portion of the message buffer
150 that the application may populate with data
151 that allows for tracing the progress of the
152 transaction or application activity across
153 components. RMR makes no use of this data.
155 &ditem(Transaction ID) A fixed number of bytes in the &ital(message
156 buffer) which the application may populate
157 with information related to the
158 transaction. RMR makes use of the transaction
159 ID for matching response messages with the
160 &c(rmr_call) function is used to send a
163 &ditem(Transient failure) An error state that is believed to be short
164 lived and that the operation, if retried by
165 the application, might be successful. C
166 programmers will recognise this as
169 &ditem(Warning) A warning occurs when RMR has encountered something
170 that it believes isn't correct, but has a
173 &ditem(Wormhole) A direct connection managed by RMR between the user
174 application and a remote, RMR based, application.