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)