docs/rmr_alloc_msg.3.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3 .. CAUTION: this document is generated from source in doc/src/rtd.
   4 .. To make changes edit the source and recompile the document.
   5 .. Do NOT make changes directly to .rst or .md files.
   6
   7 ============================================================================================
   8 Man Page: rmr_alloc_msg
   9 ============================================================================================
  10
  11
  12
  13
  14 RMR LIBRARY FUNCTIONS
  15 =====================
  16
  17
  18
  19 NAME
  20 ----
  21
  22 rmr_alloc_msg
  23
  24
  25 SYNOPSIS
  26 --------
  27
  28
  29 ::
  30
  31  #include <rmr/rmr.h>
  32
  33  rmr_mbuf_t* rmr_alloc_msg( void* ctx, int size );
  34
  35
  36
  37 DESCRIPTION
  38 -----------
  39
  40 The ``rmr_alloc_msg`` function is used to allocate a buffer
  41 which the user programme can write into and then send through
  42 the RMR library. The buffer is allocated such that sending it
  43 requires no additional copying out of the buffer. If the
  44 value passed in ``size`` is less than or equal to 0, then the
  45 *normal maximum size* supplied on the *rmr_init* call will be
  46 used. When *size* is greater than zero, the message allocated
  47 will have at least the indicated number of bytes in the
  48 payload. There is no maximum size imposed by RMR, however the
  49 underlying system memory management (e.g. malloc) functions
  50 may impose a limit.
  51
  52 The *ctx* parameter is the void context pointer that was
  53 returned by the *rmr_init* function.
  54
  55 The pointer to the message buffer returned is a structure
  56 which has some user application visible fields; the structure
  57 is described in ``rmr.h,`` and is illustrated below.
  58
  59
  60 ::
  61
  62  typedef struct {
  63      int state;
  64      int mtype;
  65      int len;
  66      unsigned char* payload;
  67      unsigned char* xaction;
  68      int sub_id;
  69      int tp_state;
  70  } rmr_mbuf_t;
  71
  72
  73 Where:
  74
  75    .. list-table::
  76      :widths: auto
  77      :header-rows: 0
  78      :class: borderless
  79
  80      * - **state**
  81        -
  82          Is the current buffer state. Following a call to
  83          ``rmr_send_msg`` the state indicates whether the buffer was
  84          successfully sent which determines exactly what the payload
  85          points to. If the send failed, the payload referenced by the
  86          buffer is the message that failed to send (allowing the
  87          application to attempt a retransmission). When the state is
  88          ``RMR_OK`` the buffer represents an empty buffer that the
  89          application may fill in in preparation to send.
  90
  91      * - **mtype**
  92        -
  93          When sending a message, the application is expected to set
  94          this field to the appropriate message type value (as
  95          determined by the user programme). Upon send this value
  96          determines how the RMR library will route the message. For a
  97          buffer which has been received, this field will contain the
  98          message type that was set by the sending application.
  99
 100      * - **len**
 101        -
 102          The application using a buffer to send a message is expected
 103          to set the length value to the actual number of bytes that it
 104          placed into the message. This is likely less than the total
 105          number of bytes that the message can carry. For a message
 106          buffer that is passed to the application as the result of a
 107          receive call, this will be the value that the sending
 108          application supplied and should indicate the number of bytes
 109          in the payload which are valid.
 110
 111      * - **payload**
 112        -
 113          The payload is a pointer to the actual received data. The
 114          user programme may read and write from/to the memory
 115          referenced by the payload up until the point in time that the
 116          buffer is used on a ``rmr_send, rmr_call`` or
 117          ``rmr_reply`` function call. Once the buffer has been passed
 118          back to a RMR library function the user programme should
 119          **NOT** make use of the payload pointer.
 120
 121      * - **xaction**
 122        -
 123          The *xaction* field is a pointer to a fixed sized area in the
 124          message into which the user may write a transaction ID. The
 125          ID is optional with the exception of when the user
 126          application uses the ``rmr_call`` function to send a message
 127          and wait for the reply; the underlying RMR processing expects
 128          that the matching reply message will also contain the same
 129          data in the *xaction* field.
 130
 131      * - **sub_id**
 132        -
 133          This value is the subscription ID. It, in combination with
 134          the message type is used by rmr to determine the target
 135          endpoint when sending a message. If the application to
 136          application protocol does not warrant the use of a
 137          subscription ID, the RMR constant RMR_VOID_SUBID should be
 138          placed in this field. When an application is forwarding or
 139          returning a buffer to the sender, it is the application's
 140          responsibility to set/reset this value.
 141
 142      * - **tp_state**
 143        -
 144          For C applications making use of RMR, the state of a
 145          transport based failure will often be available via
 146          ``errno.`` However, some wrapper environments may not have
 147          direct access to the C-lib ``errno`` value. RMR send and
 148          receive operations will place the current value of
 149          ``errno`` into this field which should make it available to
 150          wrapper functions. User applications are strongly cautioned
 151          against relying on the value of errno as some transport
 152          mechanisms may not set this value on all calls. This value
 153          should also be ignored any time the message status is
 154          ``RMR_OK.``
 155
 156
 157
 158
 159 RETURN VALUE
 160 ------------
 161
 162 The function returns a pointer to a ``rmr_mbuf`` structure,
 163 or NULL on error.
 164
 165
 166 ERRORS
 167 ------
 168
 169
 170    .. list-table::
 171      :widths: auto
 172      :header-rows: 0
 173      :class: borderless
 174
 175      * - **ENOMEM**
 176        -
 177          Unable to allocate memory.
 178
 179
 180
 181
 182 SEE ALSO
 183 --------
 184
 185 rmr_tralloc_msg(3), rmr_call(3), rmr_free_msg(3),
 186 rmr_init(3), rmr_init_trace(3), rmr_get_trace(3),
 187 rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
 188 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
 189 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
 190 rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)