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_tralloc_msg
9 ============================================================================================
33 rmr_mbuf_t* rmr_tralloc_msg( void* vctx, int size,
34 int trace_size, unsigned const char *tr_data );
41 The ``rmr_tralloc_msg`` function is used to allocate a buffer
42 which the user programme can write into and then send through
43 the library. The buffer is allocated such that sending it
44 requires no additional copying from the buffer as it passes
45 through the underlying transport mechanism.
47 The *size* parameter is used to set the payload length in the
48 message. If it is 0, then the default size supplied on the
49 *rmr_init* call will be used. In addition to allocating the
50 payload, a space in the buffer is reserved for *trace* data
51 (tr_size bytes), and the bytes pointed to by *tr_data* are
52 copied into that portion of the message. The *vctx* parameter
53 is the void context pointer that was returned by the
56 The pointer to the message buffer returned is a structure
57 which has some user application visible fields; the structure
58 is described in ``rmr.h,`` and is illustrated below.
67 unsigned char* payload;
68 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 ``a_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 a 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 a 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 processing expects
128 that the matching reply message will also contain the same
129 data in the *xaction* field.
137 The function returns a pointer to a ``rmr_mbuf`` structure,
152 Unable to allocate memory.
160 rmr_alloc_msg(3), rmr_mbuf(3) rmr_call(3), rmr_free_msg(3),
161 rmr_init(3), rmr_init_trace(3), rmr_get_trace(3),
162 rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
163 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
164 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
165 rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)