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_tralloc_msg
12 ============================================================================================
15 ============================================================================================
19 --------------------------------------------------------------------------------------------
24 --------------------------------------------------------------------------------------------
30 rmr_mbuf_t* rmr_tralloc_msg( void* vctx, int size,
31 int trace_size, unsigned const char *tr_data );
36 --------------------------------------------------------------------------------------------
38 The rmr_tralloc_msg function is used to allocate a buffer
39 which the user programme can write into and then send through
40 the library. The buffer is allocated such that sending it
41 requires no additional copying from the buffer as it passes
42 through the underlying transport mechanism.
44 The *size* parameter is used to set the payload length in the
45 message. If it is 0, then the default size supplied on the
46 *rmr_init* call will be used. In addition to allocating the
47 payload, a space in the buffer is reserved for *trace* data
48 (tr_size bytes), and the bytes pointed to by *tr_data* are
49 copied into that portion of the message. The *vctx* parameter
50 is the void context pointer that was returned by the
53 The pointer to the message buffer returned is a structure
54 which has some user application visible fields; the structure
55 is described in rmr.h, and is illustrated below.
64 unsigned char* payload;
65 unsigned char* xaction;
74 Is the current buffer state. Following a call to
75 rmr_send_msg the state indicates whether the buffer was
76 successfully sent which determines exactly what the
77 payload points to. If the send failed, the payload
78 referenced by the buffer is the message that failed to
79 send (allowing the application to attempt a
80 retransmission). When the state is a_OK the buffer
81 represents an empty buffer that the application may fill
82 in in preparation to send.
87 When sending a message, the application is expected to set
88 this field to the appropriate message type value (as
89 determined by the user programme). Upon send this value
90 determines how the a library will route the message. For a
91 buffer which has been received, this field will contain
92 the message type that was set by the sending application.
97 The application using a buffer to send a message is
98 expected to set the length value to the actual number of
99 bytes that it placed into the message. This is likely less
100 than the total number of bytes that the message can carry.
101 For a message buffer that is passed to the application as
102 the result of a receive call, this will be the value that
103 the sending application supplied and should indicate the
104 number of bytes in the payload which are valid.
109 The payload is a pointer to the actual received data. The
110 user programme may read and write from/to the memory
111 referenced by the payload up until the point in time that
112 the buffer is used on a rmr_send, rmr_call or rmr_reply
113 function call. Once the buffer has been passed back to a a
114 library function the user programme should **NOT** make
115 use of the payload pointer.
120 The *xaction* field is a pointer to a fixed sized area in
121 the message into which the user may write a transaction
122 ID. The ID is optional with the exception of when the user
123 application uses the rmr_call function to send a message
124 and wait for the reply; the underlying processing expects
125 that the matching reply message will also contain the same
126 data in the *xaction* field.
130 --------------------------------------------------------------------------------------------
132 The function returns a pointer to a rmr_mbuf structure, or
136 --------------------------------------------------------------------------------------------
142 Unable to allocate memory.
146 --------------------------------------------------------------------------------------------
148 rmr_alloc_msg(3), rmr_mbuf(3) rmr_call(3), rmr_free_msg(3),
149 rmr_init(3), rmr_init_trace(3), rmr_get_trace(3),
150 rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
151 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
152 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
153 rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)