docs/rmr_tralloc_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_tralloc_msg
   9 ============================================================================================
  10
  11
  12
  13
  14 RMR LIBRARY FUNCTIONS
  15 =====================
  16
  17
  18
  19 NAME
  20 ----
  21
  22 rmr_tralloc_msg
  23
  24
  25 SYNOPSIS
  26 --------
  27
  28
  29 ::
  30
  31  #include <rmr/rmr.h>
  32
  33  rmr_mbuf_t* rmr_tralloc_msg( void* vctx, int size,
  34                               int trace_size, unsigned const char *tr_data );
  35
  36
  37
  38 DESCRIPTION
  39 -----------
  40
  41 The ``rmr_tralloc_msg`` function is used to allocate a buffer
  42 which the user programme can write into and then send through
  43 the library. The buffer is allocated such that sending it
  44 requires no additional copying from the buffer as it passes
  45 through the underlying transport mechanism.
  46
  47 The *size* parameter is used to set the payload length in the
  48 message. If it is 0, then the default size supplied on the
  49 *rmr_init* call will be used. In addition to allocating the
  50 payload, a space in the buffer is reserved for *trace* data
  51 (tr_size bytes), and the bytes pointed to by *tr_data* are
  52 copied into that portion of the message. The *vctx* parameter
  53 is the void context pointer that was returned by the
  54 *rmr_init* function.
  55
  56 The pointer to the message buffer returned is a structure
  57 which has some user application visible fields; the structure
  58 is described in ``rmr.h,`` and is illustrated below.
  59
  60
  61 ::
  62
  63  typedef struct {
  64      int state;
  65      int mtype;
  66      int len;
  67      unsigned char* payload;
  68      unsigned char* xaction;
  69  } rmr_mbuf_t;
  70
  71
  72 Where:
  73
  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          ``a_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 a 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 a 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 processing expects
 128          that the matching reply message will also contain the same
 129          data in the *xaction* field.
 130
 131
 132
 133
 134 RETURN VALUE
 135 ------------
 136
 137 The function returns a pointer to a ``rmr_mbuf`` structure,
 138 or NULL on error.
 139
 140
 141 ERRORS
 142 ------
 143
 144
 145    .. list-table::
 146      :widths: auto
 147      :header-rows: 0
 148      :class: borderless
 149
 150      * - **ENOMEM**
 151        -
 152          Unable to allocate memory.
 153
 154
 155
 156
 157 SEE ALSO
 158 --------
 159
 160 rmr_alloc_msg(3), rmr_mbuf(3) rmr_call(3), rmr_free_msg(3),
 161 rmr_init(3), rmr_init_trace(3), rmr_get_trace(3),
 162 rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
 163 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
 164 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
 165 rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)