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