doc/src/library/glossary.im

   1
   2 .if false
   3 ==================================================================================
   4         Copyright (c) 2019 Nokia
   5         Copyright (c) 2018-2019 AT&T Intellectual Property.
   6
   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
  10
  11        http://www.apache.org/licenses/LICENSE-2.0
  12
  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 ==================================================================================
  19 .fi
  20
  21
  22 .dv term ^&half_space ^&di($1)
  23 .ix pause
  24
  25 &h1(Appendix  &gloss_appendix -- Glossary)
  26
  27 Many terms in networking can be interpreted with multiple meanings,
  28 and several terms used in this document are RMR specific.  The
  29 following definitions are the meanings of terms used within this
  30 document and should help the reader to understand the intent of
  31 meaning.
  32
  33 &beg_dlist( &1.0i Helvetica-bold )
  34 &term(application) A programme which uses RMR to send and/or receive
  35                    messages to/from another RMR based application.
  36
  37 &term(Critical error)   An error that RMR has encountered which will
  38                         prevent further successful processing by
  39                         RMR. Critical errors usually indicate that the
  40                         application should abort.
  41
  42 &term(Endpoint) An RMR based application that is defined as being
  43                         capable of receiving one or more types of
  44                         messages (as defined by a &ital(message key.)
  45                         .sm )
  46
  47 &term(Environment variable) A key/value pair which is set externally
  48                         to the application, but which is available to
  49                         the application (and referenced libraries)
  50                         through the &cw(getenv) system
  51                         call. Environment variables are the main
  52                         method of communicating information such as
  53                         port numbers to RMR.
  54
  55 &term(Error) An abnormal condition that RMR has encountered, but will
  56                         not affect the overall processing by RMR, but
  57                         may impact certain aspects such as the ability
  58                         to communicate with a specific endpoint.
  59                         Errors generally indicate that something,
  60                         usually external to RMR, must be addressed.
  61
  62 &term(Host name) The name of the host as returned by the
  63                         &cw(gethostbyname) system call. In a
  64                         containerised  environment this might be the
  65                         container or service name depending on how the
  66                         container is started. From RMR's point of
  67                         view, a host name can be used to resolve an
  68                         &ital(endpoint) definition in a &ital(route
  69                         table.)
  70
  71 &term(IP)       Internet protocol. A low level transmission protocol
  72                         which governs the transmission of datagrams
  73                         across network boundaries.
  74
  75 &term(Listen socket) A &ital(TCP) socket used to await incoming
  76                         connection requests. Listen sockets are
  77                         defined by an interface and port number
  78                         combination where the port number is unique
  79                         for the interface.
  80
  81 &term(Message) A series of bytes transmitted from the application to
  82                         another RMR based application. A message is
  83                         comprised of RMR specific data (a header), and
  84                         application data (a payload).
  85
  86 &term(Message buffer) A data structure used to describe a message
  87                         which is to be sent or has been received. The
  88                         message buffer includes the payload length,
  89                         message type, message source, and other
  90                         information.
  91
  92 &term(Messgae type) A signed integer (0-32000) which identifies the
  93                         type of message being transmitted, and is one
  94                         of the two components of a &ital(routing key.)
  95                         See &ital(Subscription ID.)
  96
  97 &term(Payload) The portion of a message which holds the user data to
  98                         be transmitted to the remote &ital(endpoint.)
  99                         The payload contents are completely
 100                         application defined.
 101
 102 &term(RMR context) A set of information which defines the current
 103                         state of the underlying transport connections
 104                         that RMR is managing. The application will be
 105                         give a context reference (pointer) that is
 106                         supplied to most RMR functions as the first
 107                         parameter.
 108
 109 &term(Round robin) The method of selecting an &ital(endpoint) from a
 110                         list such that all &ital(endpoints) are
 111                         selected before starting at the head of the list.
 112
 113 &term(Route table) A series of "rules" which define the possible
 114                         &ital(endpoints) for each &ital(message key.)
 115
 116 &term(Route table manager) An application responsible for building a
 117                         &ital(route table) and then distributing it to
 118                         all applicable RMR based applications.
 119
 120 &term(Routing) The process of selecting an &ital(endpoint) which will
 121 be the recipient of a message.
 122
 123 &term(Routing key) A combination of &ital(message type) and
 124                         &ital(subscription ID) which RMR uses to
 125                         select the destination &ital(endpoint) when
 126                         sending a message.
 127
 128 &term(Source) The sender of a message.
 129
 130
 131 &term(Subscription ID) A signed integer value (0-32000) which
 132                         identifies the subscription characteristic of
 133                         a message. It is used in conjunction with the
 134                         &ital(message type) to determine the
 135                         &ital(routing key.)
 136
 137 &term(Target) The &ital(endpoint) selected to receive a message.
 138
 139 &term(TCP)      Transmission Control Protocol. A connection based
 140                         internet protocol which provides for lossless
 141                         packet transportation, usually over IP.
 142
 143 &term(Thread)   Also called a &ital(process thread, or pthread.)  This
 144                         is a lightweight process which executes in
 145                         concurrently with the application and shares
 146                         the same address space. RMR uses threads to
 147                         manage asynchronous functions such as route
 148                         table updates.
 149
 150 &Term(Trace information)  An optional portion of the message buffer
 151                         that the application may populate with data
 152                         that allows for tracing the progress of the
 153                         transaction or application activity across
 154                         components. RMR makes no use of this data.
 155
 156 &term(Transaction ID) A fixed number of bytes in the &ital(message
 157                         buffer) which the application may populate
 158                         with information related to the
 159                         transaction. RMR makes use of the transaction
 160                         ID for matching response messages with the
 161                         &c(rmr_call) function is used to send a
 162                         message.
 163
 164 &term(Transient failure) An error state that is believed to be short
 165                         lived and that the operation, if retried by
 166                         the  application, might be successful. C
 167                         programmers will recognise this as
 168                         &cw(EAGAIN.)
 169
 170 &term(Warning) A warning occurs when RMR has encountered something
 171                         that it believes isn't correct, but has a
 172                         defined work round.
 173
 174 &term(Wormhole) A direct connection managed by RMR between the user
 175                         application and a remote, RMR based, application.
 176
 177 &end_dlist
 178
 179 .ix resume