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