doc/src/man/rmr_alloc_msg.3.xfm

   1 .if false
   2 ==================================================================================
   3    Copyright (c) 2019 Nokia
   4    Copyright (c) 2018-2019 AT&T Intellectual Property.
   5
   6    Licensed under the Apache License, Version 2.0 (the "License");
   7    you may not use this file except in compliance with the License.
   8    You may obtain a copy of the License at
   9
  10        http://www.apache.org/licenses/LICENSE-2.0
  11
  12    Unless required by applicable law or agreed to in writing, software
  13    distributed under the License is distributed on an "AS IS" BASIS,
  14    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15    See the License for the specific language governing permissions and
  16    limitations under the License.
  17 ==================================================================================
  18 .fi
  19 .if false
  20     Mnemonic    rmr_alloc_msg.xfm
  21     Abstract    The manual page for the rmr_alloc_msg function.
  22     Author      E. Scott Daniels
  23     Date        28 January 2019
  24 .fi
  25
  26 .gv e LIB lib
  27 .im &{lib}/man/setup.im
  28
  29 &line_len(6i)
  30 &h1(RMR Library Functions)
  31 &h2(NAME)
  32     rmr_alloc_msg
  33
  34 &h2(SYNOPSIS )
  35 &indent
  36 &ex_start
  37 #include <rmr/rmr.h>
  38
  39 rmr_mbuf_t* rmr_alloc_msg( void* ctx, int size );
  40 &ex_end
  41 &uindent
  42
  43 &h2(DESCRIPTION)
  44 The &cw(rmr_alloc_msg) function is used to allocate a buffer which the user
  45 programme can write into and then send through the RMR library.
  46 The buffer is allocated such that sending it requires no additional copying
  47 out of the buffer.
  48 If the value passed in &cw(size) is less than or equal to 0, then the
  49 &ital(normal maximum size) supplied on the &ital(rmr_init) call will be used.
  50 When &ital(size) is greater than zero, the message allocated will have at least
  51 the indicated number of bytes in the payload.
  52 There is no maximum size imposed by RMR, however the underlying system memory
  53 managerment (e.g. malloc) functions may impose a limit.
  54
  55 &space
  56 The &ital(ctx) parameter is the void context pointer that was returned by
  57 the &ital(rmr_init) function.
  58
  59 &space
  60 The pointer to the message buffer returned is a structure which has some
  61 user application visible fields; the structure is described in &cw(rmr.h,)
  62 and is illustrated below.
  63
  64 &space
  65 &ex_start
  66 typedef struct {
  67     int state;
  68     int mtype;
  69     int len;
  70     unsigned char* payload;
  71     unsigned char* xaction;
  72     int sub_id;
  73     int tp_state;
  74 } rmr_mbuf_t;
  75 &ex_end
  76
  77 &space
  78 &beg_dlist(.75i : ^&bold_font )
  79 &diitem(state)  Is the current buffer state.  Following a call to &cw(rmr_send_msg)
  80 the state indicates whether the buffer was successfully sent which determines
  81 exactly what the payload points to.  If the send failed, the payload referenced
  82 by the buffer is the message that failed to send (allowing the application to
  83 attempt a retransmission).
  84 When the state is &cw(RMR_OK) the buffer represents an empty buffer that the application
  85 may fill in in preparation to send.
  86
  87 &half_space
  88 &diitem(mtype)  When sending a message, the application is expected to set this field
  89 to the appropriate message type value (as determined by the user programme). Upon send
  90 this value determines how the RMR library will route the message.
  91 For a buffer which has been received, this field will contain the message type that was
  92 set by the sending application.
  93
  94 &half_space
  95 &diitem(len) The application using a buffer to send a message is expected to set the
  96 length value to the actual number of bytes that it placed into the message. This
  97 is likely less than the total number of bytes that the message can carry.
  98 For a message buffer that is passed to the application as the result of a receive
  99 call, this will be the value that the sending application supplied and should
 100 indicate the number of bytes in the payload which are valid.
 101
 102 &half_space
 103 &diitem(payload) The payload is a pointer to the actual received data.  The
 104 user programme may read and write from/to the memory referenced by the payload
 105 up until the point in time that the buffer is used on a &cw(rmr_send, rmr_call)
 106 or &cw(rmr_reply) function call.
 107 Once the buffer has been passed back to a RMR library function the user programme
 108 should &bold(NOT) make use of the payload pointer.
 109
 110
 111 &half_space
 112 &diitem(xaction) The &ital(xaction) field is a pointer to a fixed sized area in
 113 the message into which the user may write a transaction ID.
 114 The ID is optional with the exception of when the user application uses the &cw(rmr_call)
 115 function to send a message and wait for the reply; the underlying RMR processing
 116 expects that the matching reply message will also contain the same data in the
 117 &ital(xaction) field.
 118
 119 &half_space
 120 &diitem(sub_id)
 121 This value is the subscription ID. It, in combination with the message type is used
 122 by rmr to determine the target endpoint when sending a message.
 123 If the application to application protocol does not warrant the use of a subscription
 124 ID, the RMR constant RMR_VOID_SUBID should be placed in this field.
 125 When an application is forwarding or returning a buffer to the sender, it is the
 126 application's responsibility to set/reset this value.
 127
 128 &half_space
 129 &diitem(tp_state)
 130 For C applications making use of RMR, the state of a transport based failure will
 131 often be available via &cw(errno.)
 132 However, some wrapper environments may not have direct access to the C-lib &cw(errno)
 133 value.
 134 RMR send and receive operations will place the current value of &cw(errno) into this
 135 field which should make it available to wrapper functions.
 136 User applications are strongly cautioned against relying on the value of errno as
 137 some transport mechanisms may not set this value on all calls.
 138 This value should also be ignored any time the message status is &cw(RMR_OK.)
 139 &end_dlist
 140
 141 &h2(RETURN VALUE)
 142 The function returns a pointer to a &cw(rmr_mbuf) structure, or NULL on error.
 143
 144 &h2(ERRORS)
 145 &beg_dlist(.75i : ^&bold_font )
 146 &di(ENOMEM) Unable to allocate memory.
 147 &end_dlist
 148
 149 .** &h2(EXAMPLE)
 150
 151 &h2(SEE ALSO )
 152 rmr_tralloc_msg(3),
 153 rmr_call(3),
 154 rmr_free_msg(3),
 155 rmr_init(3),
 156 rmr_init_trace(3),
 157 rmr_get_trace(3),
 158 rmr_get_trlen(3),
 159 rmr_payload_size(3),
 160 rmr_send_msg(3),
 161 rmr_rcv_msg(3),
 162 rmr_rcv_specific(3),
 163 rmr_rts_msg(3),
 164 rmr_ready(3),
 165 rmr_fib(3),
 166 rmr_has_str(3),
 167 rmr_tokenise(3),
 168 rmr_mk_ring(3),
 169 rmr_ring_free(3),
 170 rmr_set_trace(3)
 171