doc/src/library/mbuf.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 &h1(Appendix &mbuf_appendix -- Message Buffer Details)
  22
  23 The RMR message buffer is a C structure which is exposed in the &cw(rmr.h)
  24 header file.
  25 It is used to manage a message received from a peer endpoint, or a message
  26 that is being sent to a peer.
  27 Fields include payload length, amount of payload actually used, status,
  28 and a reference to the payload.
  29 There are also fields which the application should ignore, and could be
  30 hidden in the header file, but we chose not to. These fields include
  31 a reference to the RMR header information, and to the underlying transport
  32 mechanism message struct which may or may not be the same as the RMR
  33 header reference.
  34
  35 &h2(The Structure)
  36 The following is the C structure.
  37 Readers are cautioned to examine the header file directly; the information
  38 here may be out of date (old document in some cache), and thus it may
  39 be incorrect.
  40
  41 &space
  42 &indent
  43 &ex_start
  44
  45 typedef struct {
  46     int    state;            // state of processing
  47     int    mtype;            // message type
  48     int    len;              // length of data in the payload (send or received)
  49     unsigned char* payload;  // transported data
  50     unsigned char* xaction;  // pointer to fixed length transaction id bytes
  51     int    sub_id;           // subscription id
  52     int    tp_state;         // transport state (errno)
  53
  54                              // these things are off limits to the user application
  55     void*    tp_buf;         // underlying transport allocated pointer (e.g. nng message)
  56     void*    header;         // internal message header (whole buffer: header+payload)
  57     unsigned char* id;       // if we need an ID in the message separate from the xaction id
  58     int      flags;          // various MFL_ (private) flags as needed
  59     int      alloc_len;      // the length of the allocated space (hdr+payload)
  60 } rmr_mbuf_t;
  61 &ex_end
  62 &uindent
  63 &space
  64
  65 &h2(State vs Transport State)
  66 The state field reflects the state at the time the message buffer is returned to the
  67 calling applicaiton.
  68 For a send operation, if the state is not &cw(RMR_OK) then the message buffer references
  69 the payload that could not be sent, and when the state is &cw(RMR_OK) the buffer
  70 references a &ital(fresh) payload that the application may fill in.
  71
  72 &space
  73 When the state is not &cw(RMR_OK,) C programmes may examine the global &cw(errno) value
  74 which RMR will have left set, if it was set, by the underlying transport mechanism.
  75 In some cases, wrapper modules are not able to directly access the C-library &cw(errno)
  76 value, and to assist with possible transport error details, the send and receive
  77 operations populate &cw(tp_state) with the value of &cw(errno.)
  78
  79 &space
  80 Regardless of whether the application makes use of the &cw(tp_state,) or the &cw(errno)
  81 value, it should be noted that the underlying transport mechanism may not actually update
  82 the errno value; in other words: it might not be accurate.
  83 In addition, RMR populates the &cw(tp_state) value in the message buffer &bold(only) when
  84 the state is not &cw(RMR_OK.)
  85
  86 &h2(Field References)
  87 The transaction field was exposed in the first version of RMR, and in hindsight this
  88 shouldn't have been done.
  89 Rather than break any existing code the reference was left, but additional fields
  90 such as trace data, were not directly exposed to the application.
  91 The application developer is strongly encouraged to use the functions which get and
  92 set the transaction ID rather than using the pointer directly; any data overruns will
  93 not be detected if the reference is used directly.
  94
  95 &space
  96 In contrast, the payload reference should be used directly by the application in the
  97 interest of speed and ease of programming.
  98 The same care to prevent writing more bytes to the payload buffer than it can hold
  99 must be taken by the application.
 100 By the nature of the allocation of the payload in transport space, RMR is unable to
 101 add guard bytes and/or test for data overrun.
 102
 103 &h2(Actual Transmission)
 104 When RMR sends the application's message, the message buffer is &bold(not) transmitted.
 105 The transport buffer (tp_buf) which contains the RMR header and application payload
 106 is the only set of bytes which are transmitted.
 107 While it may seem to the caller like the function &func(rmr_send_msg) is returning a
 108 new message buffer, the same struct is reused and only a new transport buffer is allocated.
 109 The intent is to keep the alloc/free cycles to a minimum.