blob: 59ee5b300cd2c8b380e12108eff54a453d6faffb [file] [log] [blame]
E. Scott Danielsece5bbe2020-07-21 13:39:18 -04001.. 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.
6
7============================================================================================
8Man Page: rmr_tralloc_msg
9============================================================================================
10
11
E. Scott Danielsa3a121c2020-05-06 09:07:08 -040012
13
14RMR LIBRARY FUNCTIONS
15=====================
16
17
18
19NAME
20----
21
E. Scott Danielsece5bbe2020-07-21 13:39:18 -040022rmr_tralloc_msg
E. Scott Danielsa3a121c2020-05-06 09:07:08 -040023
24
25SYNOPSIS
26--------
27
E. Scott Danielsece5bbe2020-07-21 13:39:18 -040028
29::
30
31 #include <rmr/rmr.h>
32
33 rmr_mbuf_t* rmr_tralloc_msg( void* vctx, int size,
34 int trace_size, unsigned const char *tr_data );
35
E. Scott Danielsa3a121c2020-05-06 09:07:08 -040036
37
38DESCRIPTION
39-----------
40
E. Scott Danielsece5bbe2020-07-21 13:39:18 -040041The ``rmr_tralloc_msg`` function is used to allocate a buffer
42which the user programme can write into and then send through
43the library. The buffer is allocated such that sending it
44requires no additional copying from the buffer as it passes
45through the underlying transport mechanism.
46
47The *size* parameter is used to set the payload length in the
48message. If it is 0, then the default size supplied on the
49*rmr_init* call will be used. In addition to allocating the
50payload, a space in the buffer is reserved for *trace* data
51(tr_size bytes), and the bytes pointed to by *tr_data* are
52copied into that portion of the message. The *vctx* parameter
53is the void context pointer that was returned by the
54*rmr_init* function.
55
56The pointer to the message buffer returned is a structure
57which has some user application visible fields; the structure
58is described in ``rmr.h,`` and is illustrated below.
59
60
61::
62
63 typedef struct {
64 int state;
65 int mtype;
66 int len;
67 unsigned char* payload;
68 unsigned char* xaction;
69 } rmr_mbuf_t;
70
71
72Where:
73
74
75 .. list-table::
76 :widths: auto
77 :header-rows: 0
78 :class: borderless
79
80 * - **state**
81 -
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.
90
91 * - **mtype**
92 -
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.
99
100 * - **len**
101 -
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.
110
111 * - **payload**
112 -
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.
120
121 * - **xaction**
122 -
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.
130
131
E. Scott Danielsa3a121c2020-05-06 09:07:08 -0400132
133
134RETURN VALUE
135------------
136
E. Scott Danielsece5bbe2020-07-21 13:39:18 -0400137The function returns a pointer to a ``rmr_mbuf`` structure,
138or NULL on error.
E. Scott Danielsa3a121c2020-05-06 09:07:08 -0400139
140
141ERRORS
142------
143
E. Scott Danielsece5bbe2020-07-21 13:39:18 -0400144
145 .. list-table::
146 :widths: auto
147 :header-rows: 0
148 :class: borderless
149
150 * - **ENOMEM**
151 -
152 Unable to allocate memory.
153
154
E. Scott Danielsa3a121c2020-05-06 09:07:08 -0400155
156
157SEE ALSO
158--------
159
E. Scott Danielsece5bbe2020-07-21 13:39:18 -0400160rmr_alloc_msg(3), rmr_mbuf(3) rmr_call(3), rmr_free_msg(3),
161rmr_init(3), rmr_init_trace(3), rmr_get_trace(3),
162rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
163rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
164rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
165rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)