docs/rmr_tralloc_msg.3.rst

   1
   2
   3 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   4 .. SPDX-License-Identifier: CC-BY-4.0
   5 .. CAUTION: this document is generated from source in doc/src/rtd.
   6 .. To make changes edit the source and recompile the document.
   7 .. Do NOT make changes directly to .rst or .md files.
   8
   9
  10 ============================================================================================
  11 Man Page: rmr_tralloc_msg
  12 ============================================================================================
  13
  14 RMR Library Functions
  15 ============================================================================================
  16
  17
  18 NAME
  19 --------------------------------------------------------------------------------------------
  20
  21 rmr_tralloc_msg
  22
  23 SYNOPSIS
  24 --------------------------------------------------------------------------------------------
  25
  26
  27 ::
  28
  29  #include <rmr/rmr.h>
  30  rmr_mbuf_t* rmr_tralloc_msg( void* vctx, int size,
  31                               int trace_size, unsigned const char *tr_data );
  32
  33
  34
  35 DESCRIPTION
  36 --------------------------------------------------------------------------------------------
  37
  38 The rmr_tralloc_msg function is used to allocate a buffer
  39 which the user programme can write into and then send through
  40 the library. The buffer is allocated such that sending it
  41 requires no additional copying from the buffer as it passes
  42 through the underlying transport mechanism.
  43
  44 The *size* parameter is used to set the payload length in the
  45 message. If it is 0, then the default size supplied on the
  46 *rmr_init* call will be used. In addition to allocating the
  47 payload, a space in the buffer is reserved for *trace* data
  48 (tr_size bytes), and the bytes pointed to by *tr_data* are
  49 copied into that portion of the message. The *vctx* parameter
  50 is the void context pointer that was returned by the
  51 *rmr_init* function.
  52
  53 The pointer to the message buffer returned is a structure
  54 which has some user application visible fields; the structure
  55 is described in rmr.h, and is illustrated below.
  56
  57
  58 ::
  59
  60  typedef struct {
  61      int state;
  62      int mtype;
  63      int len;
  64      unsigned char* payload;
  65      unsigned char* xaction;
  66  } rmr_mbuf_t;
  67
  68
  69
  70
  71
  72 state
  73
  74   Is the current buffer state. Following a call to
  75   rmr_send_msg the state indicates whether the buffer was
  76   successfully sent which determines exactly what the
  77   payload points to. If the send failed, the payload
  78   referenced by the buffer is the message that failed to
  79   send (allowing the application to attempt a
  80   retransmission). When the state is a_OK the buffer
  81   represents an empty buffer that the application may fill
  82   in in preparation to send.
  83
  84
  85 mtype
  86
  87   When sending a message, the application is expected to set
  88   this field to the appropriate message type value (as
  89   determined by the user programme). Upon send this value
  90   determines how the a library will route the message. For a
  91   buffer which has been received, this field will contain
  92   the message type that was set by the sending application.
  93
  94
  95 len
  96
  97   The application using a buffer to send a message is
  98   expected to set the length value to the actual number of
  99   bytes that it placed into the message. This is likely less
 100   than the total number of bytes that the message can carry.
 101   For a message buffer that is passed to the application as
 102   the result of a receive call, this will be the value that
 103   the sending application supplied and should indicate the
 104   number of bytes in the payload which are valid.
 105
 106
 107 payload
 108
 109   The payload is a pointer to the actual received data. The
 110   user programme may read and write from/to the memory
 111   referenced by the payload up until the point in time that
 112   the buffer is used on a rmr_send, rmr_call or rmr_reply
 113   function call. Once the buffer has been passed back to a a
 114   library function the user programme should **NOT** make
 115   use of the payload pointer.
 116
 117
 118 xaction
 119
 120   The *xaction* field is a pointer to a fixed sized area in
 121   the message into which the user may write a transaction
 122   ID. The ID is optional with the exception of when the user
 123   application uses the rmr_call function to send a message
 124   and wait for the reply; the underlying processing expects
 125   that the matching reply message will also contain the same
 126   data in the *xaction* field.
 127
 128
 129 RETURN VALUE
 130 --------------------------------------------------------------------------------------------
 131
 132 The function returns a pointer to a rmr_mbuf structure, or
 133 NULL on error.
 134
 135 ERRORS
 136 --------------------------------------------------------------------------------------------
 137
 138
 139
 140 ENOMEM
 141
 142   Unable to allocate memory.
 143
 144
 145 SEE ALSO
 146 --------------------------------------------------------------------------------------------
 147
 148 rmr_alloc_msg(3), rmr_mbuf(3) rmr_call(3), rmr_free_msg(3),
 149 rmr_init(3), rmr_init_trace(3), rmr_get_trace(3),
 150 rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
 151 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
 152 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
 153 rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)