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.
7 ============================================================================================
8 Man Page: rmr_alloc_msg
9 ============================================================================================
33 rmr_mbuf_t* rmr_alloc_msg( void* ctx, int size );
40 The ``rmr_alloc_msg`` function is used to allocate a buffer
41 which the user programme can write into and then send through
42 the RMR library. The buffer is allocated such that sending it
43 requires no additional copying out of the buffer. If the
44 value passed in ``size`` is less than or equal to 0, then the
45 *normal maximum size* supplied on the *rmr_init* call will be
46 used. When *size* is greater than zero, the message allocated
47 will have at least the indicated number of bytes in the
48 payload. There is no maximum size imposed by RMR, however the
49 underlying system memory management (e.g. malloc) functions
52 The *ctx* parameter is the void context pointer that was
53 returned by the *rmr_init* function.
55 The pointer to the message buffer returned is a structure
56 which has some user application visible fields; the structure
57 is described in ``rmr.h,`` and is illustrated below.
66 unsigned char* payload;
67 unsigned char* xaction;
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 ``RMR_OK`` the buffer represents an empty buffer that the
89 application may fill in in preparation to send.
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 RMR 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.
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.
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 RMR library function the user programme should
119 **NOT** make use of the payload pointer.
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 RMR processing expects
128 that the matching reply message will also contain the same
129 data in the *xaction* field.
133 This value is the subscription ID. It, in combination with
134 the message type is used by rmr to determine the target
135 endpoint when sending a message. If the application to
136 application protocol does not warrant the use of a
137 subscription ID, the RMR constant RMR_VOID_SUBID should be
138 placed in this field. When an application is forwarding or
139 returning a buffer to the sender, it is the application's
140 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
146 ``errno.`` However, some wrapper environments may not have
147 direct access to the C-lib ``errno`` value. RMR send and
148 receive operations will place the current value of
149 ``errno`` into this field which should make it available to
150 wrapper functions. User applications are strongly cautioned
151 against relying on the value of errno as some transport
152 mechanisms may not set this value on all calls. This value
153 should also be ignored any time the message status is
162 The function returns a pointer to a ``rmr_mbuf`` structure,
177 Unable to allocate memory.
185 rmr_tralloc_msg(3), rmr_call(3), rmr_free_msg(3),
186 rmr_init(3), rmr_init_trace(3), rmr_get_trace(3),
187 rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
188 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
189 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
190 rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)