doc/src/library/api_qref.im

   1 .if false
   2 ==================================================================================
   3         Copyright (c) 2019 Nokia
   4         Copyright (c) 2018-2019 AT&T Intellectual Property.
   5
   6    Licensed under the Apache License, Version 2.0 (the "License");
   7    you may not use this file except in compliance with the License.
   8    You may obtain a copy of the License at
   9
  10        http://www.apache.org/licenses/LICENSE-2.0
  11
  12    Unless required by applicable law or agreed to in writing, software
  13    distributed under the License is distributed on an "AS IS" BASIS,
  14    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15    See the License for the specific language governing permissions and
  16    limitations under the License.
  17 ==================================================================================
  18 .fi
  19
  20 .if false
  21         Mnemonic:       api_qr.im
  22         Abstract:       A quick reference to all external function calls
  23         Date:           2 August, 2019
  24         Author:         E. Scott Daniels
  25 .fi
  26
  27 &h1(Appendix &qr_appendix -- Quick Reference)
  28 The prototype for each of the externally available functions which comprise the RMR API is listed
  29 in alphabetical order below.
  30 For each prototype a brief description of the function is given.
  31 The developer is encouraged to install the RMR development package which contains the manual pages.
  32 The manual pages completely describe each function in a level of detail consistent with UNIX man pages.
  33
  34 &h2(Context Specific Functions)
  35 These functions require that the RMR context (provided as the result of an &func(rmr_init:) call, be
  36 passed as the first argument (vctx).
  37
  38 &proto_start
  39 rmr_mbuf_t* rmr_alloc_msg( void* vctx, int size );
  40 &proto_end
  41 This function allocates a &ital(zero copy) message buffer.
  42 The payload portion is allocated from the underlying transport space such that on send the buffer
  43 does not require a second copy.
  44 The size parameter is the size of the payload portion of the buffer; if the recipient of the
  45 message is expected to send a response, this should be large enough to accomodate the response
  46 which will enable the remote application to reuse the message for the response and avoid a costly
  47 reallocation.
  48
  49 &proto_start
  50 rmr_mbuf_t* rmr_call( void* vctx, rmr_mbuf_t* msg );
  51 &proto_end
  52 The call function accepts a message, selects an endpoint to receive the message and sends the message.
  53 RMR will block the return to the application until a matching response is received, or a timeout period
  54 is reached.
  55 The transaction ID in the outbound message is used to match a response, so it is imperative that
  56 the application making the response reuse the received message, or copy the transaction ID to the new
  57 message before sending.
  58 Messages arriving which do not match the expected response are queued and will be delivered to the
  59 application on subsequent calls to &func(rmr_rcv_msg:.)
  60
  61 &proto_start
  62 void rmr_close( void* vctx );
  63 &proto_end
  64 This function terminates all sessions with the underlying transport mechanism.
  65 Buffers pending may or may not be flushed (depending on the underlying mechanism), thus it is
  66 recommended that before using this function the application pause for a second or two to
  67 ensure that the pending transmissions have completed.
  68
  69 &proto_start
  70 int rmr_get_rcvfd( void* vctx );
  71 &proto_end
  72 When the underlying transport mechanism supports this, a file descriptor suitable for use with
  73 the &cw(select, poll) and &cw(epoll) system calls is returned.
  74 The file descriptor may not be used for read or write operations; doing so will have unpredictable
  75 results.
  76
  77 &proto_start
  78 void* rmr_init( char* proto_port, int max_msg_size, int flags );
  79 &proto_end
  80 This function must be used before all other RMR functions to initialise the environment.
  81 The &cw(max_msg_size) parameter defines the maximum receive buffer size which will be
  82 used if required by the underlying transport mechanism.
  83 The value is also used as the default payload size if a zero length is given to &func(rmr_alloc_msg:.)
  84
  85 &proto_start
  86 rmr_mbuf_t* rmr_mt_call( void* vctx, rmr_mbuf_t* mbuf, int call_id, int max_wait );
  87 &proto_end
  88 Similar to the &func(rmr_call:) function, the message is sent to an endpoint and a response message
  89 is waited for.
  90 This call is thread safe, and while the thread that invokes this function blocks on the response,
  91 it is possible for other application threads to continue to receive messages via the &func(rmr_rcv_msg:)
  92 function.
  93 &space
  94 In order to use the multi-threaded call functions, the option to enable threaded receive support
  95 must be set on the call to &func(rmr_init:.)
  96
  97 &proto_start
  98 rmr_mbuf_t* rmr_mtosend_msg( void* vctx, rmr_mbuf_t* msg, int max_to );
  99 &proto_end
 100 This function sends the provided message allowing RMR to retry soft failures for approximately
 101 &ccw(max_to) milliseconds.
 102 When a value of zero (0) is given for the maximum timeout, RMR will not attempt any retires
 103 and will return the state after the first attempt.
 104 It is unlikely that a user application will use this function as it is possible (and recommended)
 105 to set the max timeout via the specific, one time, function call, and then to allow that value
 106 to be used as the default when &func(rmr_send_msg:) is invoked.
 107
 108 &proto_start
 109 rmr_mbuf_t* rmr_mt_rcv( void* vctx, rmr_mbuf_t* mbuf, int max_wait );
 110 &proto_end
 111 This function waits for a message to arrive and returns a message buffer with the received
 112 message.
 113 The function will timeout after &cw(max_wait) milliseconds (approximately) if no message is
 114 received.
 115
 116 &proto_start
 117 rmr_mbuf_t* rmr_send_msg( void* vctx, rmr_mbuf_t* msg );
 118 &proto_end
 119 This function accepts a message, selects a destination endpoint using the message type and subscription ID,
 120 and then attempts to send the message to the destination.
 121 The function returns a message buffer to the caller with the state set to indicate the state of the
 122 send operation.
 123 On success, the message buffer is a new buffer that the application can "fill in," and send without the
 124 need to overtly allocate a new buffer.
 125 On failure, the message buffer is the buffer that the application attempted to send.
 126
 127 &proto_start
 128 int rmr_init_trace( void* vctx, int size );
 129 &proto_end
 130 This function is used to set the default trace data size.
 131 The size defaults to zero until this function is called; after the application sets a non-zero value
 132 messages created with the &func(rmr_alloc_msg:) function will be allocated with trace data set to
 133 the size provided.
 134
 135 &proto_start
 136 rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg );
 137 &proto_end
 138 The &func(rmr_rcv_msg:) function is used to block and wait for a message to arrive.
 139 When a message is received a pointer to an RMR message buffer structure is returned to the caller.
 140 The &cw(old_msg) parameter allows the application to to pass a message buffer for reuse.
 141 If the application does not have an old buffer, a nil pointer is given and the function will
 142 allocate a new buffer.
 143
 144 &proto_start
 145 rmr_mbuf_t* rmr_rcv_specific( void* uctx, rmr_mbuf_t* msg, char* expect,
 146      int allow2queue );
 147 &proto_end
 148 This function blocks until a message with a specific transaction ID is received.
 149 If the &cw(allowd2queue) parameter is set to 1, messagess which do not match the ID are queued
 150 and returned to the application on subsequent calls to &func(rmr_rcv_msg:.)
 151
 152
 153 &proto_start
 154 int rmr_ready( void* vctx );
 155 &proto_end
 156 This function is used to test whether RMR is capable of sending messages.
 157 In other words once this function returns true (!0) RMR has received a route table (either from a static
 158 file or from a route manager process, and can map message types to endpoints.
 159 If the application attempts to send a message before this function returns true, the sends
 160 will fail.
 161 Applications which are only message receivers do not need to use this function.
 162
 163 &proto_start
 164 rmr_mbuf_t*  rmr_rts_msg( void* vctx, rmr_mbuf_t* msg );
 165 &proto_end
 166 The &func(rmr_rts_msg:) function allows the application to send a response message to the endpoint
 167 from which the message originated.
 168 This requires that the application use the same message buffer that was received for the
 169 response as it contains the sender information that is needed for this function to be successful.
 170 If the message cannot be sent, a pointer to the message buffer is returned and the status in the
 171 message buffer is set to indicate the reason.
 172 On success, a nil pointer will be returned.
 173
 174
 175 &proto_start
 176 int rmr_set_rtimeout( void* vctx, int time );
 177 &proto_end
 178 This function provides the ability to return from a receive operation after a timeout threshold
 179 is reached before a message is received, and is intended only to support the underlying Nanomsg
 180 transport mechanism (support for Nanomsg is deprecated).
 181 The &func(rmr_torcv_msg) function should be used if timed receives are required.
 182 &space
 183
 184 For transport mechanisms which support a receive timeout, this function allows the application to
 185 set a default timeout for receive operations.
 186 If a call to &func(rmr_rcv_msg) does not complete before &ital(time) milliseconds has elapsed,
 187 the receive function will return a nil message buffer.
 188 This may not be supported by the underlying transport mechanism, and if it is not the return
 189 from this function will be -1.
 190
 191 &proto_start
 192 int rmr_set_stimeout( void* vctx, int rounds );
 193 &proto_end
 194 This function allows the application to set a maximum number of retry &ital(rounds) that RMR will
 195 attempt when send operations report a transient (retry) failure.
 196 Each &ital(round) of retries requires approximately 1 millisecond, and setting the number of
 197 rounds to zero (0) causes RMR to report the transient failure to the application without
 198 any retry attempts.
 199 If the user application does not invoke this function, the default is one (1) round of retries.
 200
 201 &proto_start
 202 rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to );
 203 &proto_end
 204 This function because identically to the &func(rmr_rcv_msg) function, and allows the application to
 205 set a specific timeout value for the receive operation.
 206 If a message is not received before the timeout period expires (ms_to milliseconds), a message buffer
 207 is returned with the state set to &cw(RMR_ERR_TIMEOUT.)
 208
 209
 210 &proto_start
 211 rmr_mbuf_t*  rmr_tralloc_msg( void* context, int msize, int trsize,
 212      unsigned const char* data );
 213 &proto_end
 214 Similar to the &func(rmr_alloc_msg) this function allocates a message buffer, and adds the
 215 referenced trace data to the buffer.
 216 The new message buffer is returned.
 217
 218 &proto_start
 219 void rmr_wh_close( void* vctx, int whid );
 220 &proto_end
 221 This function closes an existing wormhole connection.
 222
 223
 224 &proto_start
 225 rmr_whid_t rmr_wh_open( void* vctx, char const* target );
 226 &proto_end
 227 This function allows the application to create a &ital(wormhole,) direct, connection to another application.
 228 The peer application must also be using RMR (messages sent on a wormhole connection are RMR messages).
 229 The target may be a hostname:port or IP-address:port combination.
 230 Upon successful completion, the &ital(wormhole ID) is returned; this ID must be passed on all
 231 subsequent calls to wormhole functions for this connection.
 232
 233 &proto_start
 234 rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t whid, rmr_mbuf_t* msg );
 235 &proto_end
 236 Once a wormhole has been established to a peer application, this function allows the application
 237 to send a message to the peer.
 238 All semantics of normal RMR sends (retries, etc.) are observed.
 239 The application may opt not to supply the message type or subscription ID in the message as
 240 neither are used by RMR; they may be required by the peer application depending on the application
 241 level protocol(s) in use.
 242
 243
 244 .** ------------------------------------
 245 &space
 246 &h2(Message Buffer Functions)
 247 The message buffer functions operate directly on a message buffer, and as such do not
 248 require that RMR context as a parameter.
 249 &space
 250
 251 &proto_start
 252 int rmr_bytes2meid( rmr_mbuf_t* mbuf, unsigned char const* src, int len );
 253 &proto_end
 254 Copy the bytes referenced by &ital(src) to the &ital(meid) field in the RMR message header.
 255 Up to &ital(len) bytes are copied, though the maximum length of the field as
 256 governed by &cw(RMR_MAX_MEID) is enforced.
 257
 258 &proto_start
 259 void rmr_bytes2payload( rmr_mbuf_t* mbuf, unsigned char const* src, int len );
 260 &proto_end
 261 This function copies &ital(len) bytes from &ital(src) into the message buffer payload.
 262 This function is primarily provided to support wrappers which don't directly support
 263 C pointers.
 264
 265
 266 &proto_start
 267 int rmr_bytes2xact( rmr_mbuf_t* mbuf, unsigned char const* src, int len );
 268 &proto_end
 269 This function copies &ital(len) bytes of data from &ital(src) to the transaction ID
 270 field in the message buffer.
 271 The number of bytes provided will be limited to a maximum of &cw(RMR_MAX_XID.)
 272
 273 &proto_start
 274 void rmr_free_msg( rmr_mbuf_t* mbuf );
 275 &proto_end
 276 This function should be used by the application to release the storage used by a message buffer.
 277
 278 &proto_start
 279 unsigned char*  rmr_get_meid( rmr_mbuf_t* mbuf, unsigned char* dest );
 280 &proto_end
 281 The bytes from the &cw(meid) field of the message buffer are copied to the &ital(dest) buffer
 282 provided by the application.
 283 The full field of &cw(RMR_MAX_MEID) bytes are copied; the caller must ensure that &ital(dest)
 284 is large enough.
 285
 286 &proto_start
 287 unsigned char*  rmr_get_src( rmr_mbuf_t* mbuf, unsigned char* dest );
 288 &proto_end
 289 The source of a message is copied to the &ital(dest) buffer provided by the caller.
 290 This is generally the hostname and port, separated by a colon, of the application
 291 which sent the message, and is a zero terminated string.
 292 Up to &cw(RMR_MAX_SRC) bytes will be copied, so the caller must ensure that &ital(dest)
 293 is at least this large.
 294
 295 &proto_start
 296 unsigned char* rmr_get_srcip( rmr_mbuf_t* msg, unsigned char* dest );
 297 &proto_end
 298 This function copies the source IP address and port, separated by a colon, to the
 299 &ital(dest) buffer provided by the caller.
 300 This is the address of the application which sent the message.
 301 Up to &cw(RMR_MAX_SRC) bytes will be copied, so the caller must ensure that &ital(dest)
 302 is at least this large.
 303
 304 &proto_start
 305 int rmr_get_trlen( rmr_mbuf_t* msg );
 306 &proto_end
 307 This function can be used to determine the size of the trace information in the message buffer.
 308 If no trace data is present, then 0 is returned.
 309
 310 &proto_start
 311 int rmr_get_trace( rmr_mbuf_t* msg, unsigned char* dest, int size );
 312 &proto_end
 313 The bytes from the trace data, up to &tial(size) bytes, is copied from the message buffer
 314 to the &ital(dest) buffer provided by the caller.
 315 The return value is the number of bytes actually copied.
 316
 317 &proto_start
 318 int rmr_payload_size( rmr_mbuf_t* msg );
 319 &proto_end
 320 This function returns the number of bytes in the message buffer's payload that are available
 321 for the application to use.
 322
 323
 324 &proto_start
 325 rmr_mbuf_t* rmr_realloc_msg( rmr_mbuf_t* mbuf, int new_tr_size );
 326 &proto_end
 327 This function allows the application to reallocate a message buffer with a different trace
 328 data size.
 329 The contents of the message buffer supplied are copied to the new buffer, and a reference to
 330 the new buffer is returned.
 331
 332 &proto_start
 333 int rmr_set_trace( rmr_mbuf_t* msg, unsigned const char* data, int size );
 334 &proto_end
 335 The &ital(size) bytes, up to the size of the trace data in the message buffer,
 336 at &ital(data) are copied to the trace portion of the message buffer.
 337 The return value is the actual number of bytes copied which could be less than the number
 338 requested.
 339
 340
 341 &proto_start
 342 int rmr_str2meid( rmr_mbuf_t* mbuf, unsigned char const* str );
 343 &proto_end
 344 Accepts a pointer to a zero terminated string an copies it to the &cw(meid) field in the
 345 message header.
 346 Up to &cw(RMR_MAX_MEID) bytes are copied (including the final 0), and the number
 347 copied is returned.
 348
 349 &proto_start
 350 void rmr_str2payload( rmr_mbuf_t* mbuf, unsigned char const* str );
 351 &proto_end
 352 Accepts a pointer to a zero terminated string, and copies the string to the payload
 353 portion of the message buffer.
 354 If the string is longer than the allocated payload, the string will be truncated
 355 and will &bold(not) be terminated with a zero byte.
 356
 357
 358 &proto_start
 359 int rmr_str2xact( rmr_mbuf_t* mbuf, unsigned char const* str );
 360 &proto_end
 361 Accepts a pointer to a zero terminated string and copies the string to the transaction ID
 362 portion of the message buffer.
 363 If the string is longer than &cw(RMR_MAX_XID,) the string will be truncated and will &bold(not)
 364 be zero terminated.
 365
 366 &proto_start
 367 void* rmr_trace_ref( rmr_mbuf_t* msg, int* sizeptr );
 368 &proto_end
 369 This function returns a pointer to the trace information in the message buffer.
 370 The intent is that the application will treat this as a read/only field and will not
 371 write trace data into the message buffer.
 372 The length of data available should be determined by calling &func(rmr_get_trlen:.)
 373
 374
 375