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.
10 ============================================================================================
11 Man Page: rmr_alloc_msg
12 ============================================================================================
15 ============================================================================================
19 --------------------------------------------------------------------------------------------
24 --------------------------------------------------------------------------------------------
30 rmr_mbuf_t* rmr_alloc_msg( void* ctx, int size );
35 --------------------------------------------------------------------------------------------
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
49 The *ctx* parameter is the void context pointer that was
50 returned by the *rmr_init* function.
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.
63 unsigned char* payload;
64 unsigned char* xaction;
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.
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.
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.
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.
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.
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.
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.
157 --------------------------------------------------------------------------------------------
159 The function returns a pointer to a rmr_mbuf structure, or
163 --------------------------------------------------------------------------------------------
169 Unable to allocate memory.
173 --------------------------------------------------------------------------------------------
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)