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.
12 ============================================================================================
14 The RIC Message Router (RMR) is a library for peer-to-peer
15 communication. Applications use the library to send and
16 receive messages where the message routing and endpoint
17 selection is based on the message type rather than DNS host
18 name-IP port combinations.
20 This document contains information that developers need to
21 know to use the RMR library. Because the primary
22 documentation for the RMR library is a collection of UNIX
23 manpages (included in the development package, and available
24 via the man command when installed), there is no separate
25 "User's Guide." To provide something for the document
26 scrapers to find, this is a collection of the RMR manual
27 pages formatted directly from their source, which might be a
28 bit ragged when combined into a single markup document. Read
34 --------------------------------------------------------------------------------------------
39 --------------------------------------------------------------------------------------------
45 rmr_mbuf_t* rmr_alloc_msg( void* ctx, int size );
50 --------------------------------------------------------------------------------------------
52 The rmr_alloc_msg function is used to allocate a buffer which
53 the user programme can write into and then send through the
54 RMR library. The buffer is allocated such that sending it
55 requires no additional copying out of the buffer. If the
56 value passed in size is less than or equal to 0, then the
57 *normal maximum size* supplied on the *rmr_init* call will be
58 used. When *size* is greater than zero, the message allocated
59 will have at least the indicated number of bytes in the
60 payload. There is no maximum size imposed by RMR, however the
61 underlying system memory managerment (e.g. malloc) functions
64 The *ctx* parameter is the void context pointer that was
65 returned by the *rmr_init* function.
67 The pointer to the message buffer returned is a structure
68 which has some user application visible fields; the structure
69 is described in rmr.h, and is illustrated below.
78 unsigned char* payload;
79 unsigned char* xaction;
90 Is the current buffer state. Following a call to
91 rmr_send_msg the state indicates whether the buffer was
92 successfully sent which determines exactly what the
93 payload points to. If the send failed, the payload
94 referenced by the buffer is the message that failed to
95 send (allowing the application to attempt a
96 retransmission). When the state is RMR_OK the buffer
97 represents an empty buffer that the application may fill
98 in in preparation to send.
103 When sending a message, the application is expected to set
104 this field to the appropriate message type value (as
105 determined by the user programme). Upon send this value
106 determines how the RMR library will route the message. For
107 a buffer which has been received, this field will contain
108 the message type that was set by the sending application.
113 The application using a buffer to send a message is
114 expected to set the length value to the actual number of
115 bytes that it placed into the message. This is likely less
116 than the total number of bytes that the message can carry.
117 For a message buffer that is passed to the application as
118 the result of a receive call, this will be the value that
119 the sending application supplied and should indicate the
120 number of bytes in the payload which are valid.
125 The payload is a pointer to the actual received data. The
126 user programme may read and write from/to the memory
127 referenced by the payload up until the point in time that
128 the buffer is used on a rmr_send, rmr_call or rmr_reply
129 function call. Once the buffer has been passed back to a
130 RMR library function the user programme should **NOT**
131 make use of the payload pointer.
136 The *xaction* field is a pointer to a fixed sized area in
137 the message into which the user may write a transaction
138 ID. The ID is optional with the exception of when the user
139 application uses the rmr_call function to send a message
140 and wait for the reply; the underlying RMR processing
141 expects that the matching reply message will also contain
142 the same data in the *xaction* field.
147 This value is the subscription ID. It, in combination with
148 the message type is used by rmr to determine the target
149 endpoint when sending a message. If the application to
150 application protocol does not warrant the use of a
151 subscription ID, the RMR constant RMR_VOID_SUBID should be
152 placed in this field. When an application is forwarding or
153 returning a buffer to the sender, it is the application's
154 responsibility to set/reset this value.
159 For C applications making use of RMR, the state of a
160 transport based failure will often be available via errno.
161 However, some wrapper environments may not have direct
162 access to the C-lib errno value. RMR send and receive
163 operations will place the current value of errno into this
164 field which should make it available to wrapper functions.
165 User applications are strongly cautioned against relying
166 on the value of errno as some transport mechanisms may not
167 set this value on all calls. This value should also be
168 ignored any time the message status is RMR_OK.
172 --------------------------------------------------------------------------------------------
174 The function returns a pointer to a rmr_mbuf structure, or
178 --------------------------------------------------------------------------------------------
184 Unable to allocate memory.
188 --------------------------------------------------------------------------------------------
190 rmr_tralloc_msg(3), rmr_call(3), rmr_free_msg(3),
191 rmr_init(3), rmr_init_trace(3), rmr_get_trace(3),
192 rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
193 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
194 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
195 rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)
199 --------------------------------------------------------------------------------------------
204 --------------------------------------------------------------------------------------------
210 int rmr_bytes2meid( rmr_mbuf_t* mbuf, unsigned char* src, int len )
215 --------------------------------------------------------------------------------------------
217 The rmr_bytes2meid function will copy up to *len* butes from
218 *src* to the managed entity ID (meid) field in the message.
219 The field is a fixed length, gated by the constant
220 RMR_MAX_MEID and if len is larger than this value, only
221 RMR_MAX_MEID bytes will actually be copied.
224 --------------------------------------------------------------------------------------------
226 On success, the actual number of bytes copied is returned, or
227 -1 to indicate a hard error. If the length is less than 0, or
228 not the same as length passed in, errno is set to one of the
229 errors described in the *Errors* section.
232 --------------------------------------------------------------------------------------------
234 If the returned length does not match the length passed in,
235 errno will be set to one of the following constants with the
236 meaning listed below.
242 The message, or an internal portion of the message, was
243 corrupted or the pointer was invalid.
248 The length passed in was larger than the maximum length of
249 the field; only a portion of the source bytes were copied.
253 --------------------------------------------------------------------------------------------
257 --------------------------------------------------------------------------------------------
259 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_call(3),
260 rmr_free_msg(3), rmr_get_rcvfd(3), rmr_get_meid(3),
261 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
262 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
263 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
264 rmr_ring_free(3), rmr_str2meid(3), rmr_str2xact(3),
265 rmr_wh_open(3), rmr_wh_send_msg(3)
269 --------------------------------------------------------------------------------------------
274 --------------------------------------------------------------------------------------------
280 void rmr_bytes2payload( rmr_mbuf_t* mbuf, unsigned char* src, int len )
285 --------------------------------------------------------------------------------------------
287 This is a convenience function as some wrapper languages
288 might not have the ability to directly copy into the payload
289 buffer. The bytes from *src* for the length given are copied
290 to the payload. It is the caller's responsibility to ensure
291 that the payload is large enough. Upon successfully copy, the
292 len field in the message buffer is updated to reflect the
293 number of bytes copied.
295 There is little error checking, and no error reporting.
298 --------------------------------------------------------------------------------------------
303 --------------------------------------------------------------------------------------------
307 --------------------------------------------------------------------------------------------
309 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2payload(3),
310 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
311 rmr_get_meid(3), rmr_payload_size(3), rmr_send_msg(3),
312 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
313 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
314 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
315 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
319 --------------------------------------------------------------------------------------------
324 --------------------------------------------------------------------------------------------
330 int rmr_bytes2xact( rmr_mbuf_t* mbuf, unsigned char* src, int len )
335 --------------------------------------------------------------------------------------------
337 The rmr_bytes2xact function will copy up to *len* butes from
338 *src* to the transaction ID (xaction) field in the message.
339 The field is a fixed length, gated by the constant
340 RMR_MAX_XID and if len is larger than this value, only
341 RMR_MAX_XID bytes will actually be copied.
345 --------------------------------------------------------------------------------------------
347 On success, the actual number of bytes copied is returned,
348 or -1 to indicate a hard error. If the length is less than
349 0, or not the same as length passed in, errno is set to
350 one of the errors described in the *Errors* section.
353 --------------------------------------------------------------------------------------------
355 If the returned length does not match the length passed
356 in, errno will be set to one of the following constants
357 with the meaning listed below.
362 The message, or an internal portion of the message, was
363 corrupted or the pointer was invalid.
368 The length passed in was larger than the maximum length of
369 the field; only a portion of the source bytes were copied.
373 --------------------------------------------------------------------------------------------
377 --------------------------------------------------------------------------------------------
379 rmr_alloc_msg(3), rmr_bytes2meid(3), rmr_call(3),
380 rmr_free_msg(3), rmr_get_meid(3), rmr_get_rcvfd(3),
381 rmr_get_xact(3), rmr_payload_size(3), rmr_send_msg(3),
382 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
383 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
384 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
385 rmr_wh_open(3), rmr_wh_send_msg(3)
389 --------------------------------------------------------------------------------------------
394 --------------------------------------------------------------------------------------------
400 extern rmr_mbuf_t* rmr_call( void* vctx, rmr_mbuf_t* msg );
405 --------------------------------------------------------------------------------------------
407 The rmr_call function sends the user application message to a
408 remote endpoint, and waits for a corresponding response
409 message before returning control to the user application. The
410 user application supplies a completed message buffer, as it
411 would for a rmr_send call, but unlike with the send, the
412 buffer returned will have the response from the application
413 that received the message.
415 Messages which are received while waiting for the response
416 are queued internally by RMR, and are returned to the user
417 application when rmr_rcv_msg is invoked. These messages are
418 returned in the order received, one per call to rmr_rcv_msg.
421 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
423 The rmr_call function implements a timeout failsafe to
424 prevent, in most cases, the function from blocking forever.
425 The timeout period is **not** based on time (calls to clock
426 are deemed too expensive for a low latency system level
427 library), but instead the period is based on the number of
428 received messages which are not the response. Using a
429 non-time mechanism for *timeout* prevents the async queue
430 from filling (which would lead to message drops) in an
431 environment where there is heavy message traffic.
433 When the threshold number of messages have been queued
434 without receiving a response message, control is returned to
435 the user application and a nil pointer is returned to
436 indicate that no message was received to process. Currently
437 the threshold is fixed at 20 messages, though in future
438 versions of the library this might be extended to be a
439 parameter which the user application may set.
442 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
444 The send operations in RMR will retry *soft* send failures
445 until one of three conditions occurs:
451 The message is sent without error
456 The underlying transport reports a *hard* failure
461 The maximum number of retry loops has been attempted
464 A retry loop consists of approximately 1000 send attempts
465 **without** any intervening calls to *sleep()* or *usleep().*
466 The number of retry loops defaults to 1, thus a maximum of
467 1000 send attempts is performed before returning to the user
468 application. This value can be set at any point after RMR
469 initialisation using the *rmr_set_stimeout()* function
470 allowing the user application to completely disable retires
471 (set to 0), or to increase the number of retry loops.
473 Transport Level Blocking
474 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
476 The underlying transport mechanism used to send messages is
477 configured in *non-blocking* mode. This means that if a
478 message cannot be sent immediately the transport mechanism
479 will **not** pause with the assumption that the inability to
480 send will clear quickly (within a few milliseconds). This
481 means that when the retry loop is completely disabled (set to
482 0), that the failure to accept a message for sending by the
483 underlying mechanisms (software or hardware) will be reported
484 immediately to the user application.
486 It should be noted that depending on the underlying transport
487 mechanism being used, it is extremely likely that retry
488 conditions will happen during normal operations. These are
489 completely out of RMR's control, and there is nothing that
490 RMR can do to avoid or mitigate these other than by allowing
491 RMR to retry the send operation, and even then it is possible
492 (e.g., during connection reattempts), that a single retry
493 loop is not enough to guarantee a successful send.
496 --------------------------------------------------------------------------------------------
498 The rmr_call function returns a pointer to a message buffer
499 with the state set to reflect the overall state of call
500 processing (see Errors below). In some cases a nil pointer
501 will be returned; when this is the case only *errno* will be
502 available to describe the reason for failure.
505 --------------------------------------------------------------------------------------------
507 These values are reflected in the state field of the returned
514 The call was successful and the message buffer references
515 the response message.
520 The call failed and the value of *errno,* as described
521 below, should be checked for the specific reason.
524 The global "variable" *errno* will be set to one of the
525 following values if the overall call processing was not
532 Too many messages were queued before receiving the
538 The queued message ring is full, messages were dropped
543 A parameter was not valid
548 The underlying message system was interrupted or the
549 device was busy; the message was **not** sent, and the
550 user application should call this function with the
555 --------------------------------------------------------------------------------------------
557 The following code snippet shows one way of using the
558 rmr_call function, and illustrates how the transaction ID
564 int retries_left = 5; // max retries on dev not available
565 int retry_delay = 50000; // retry delay (usec)
566 static rmr_mbuf_t* mbuf = NULL; // response msg
567 msg_t* pm; // application struct for payload
568 // get a send buffer and reference the payload
569 mbuf = rmr_alloc_msg( mr, sizeof( pm->req ) );
570 pm = (msg_t*) mbuf->payload;
571 // generate an xaction ID and fill in payload with data and msg type
572 snprintf( mbuf->xaction, RMR_MAX_XID, "%s", gen_xaction() );
573 snprintf( pm->req, sizeof( pm->req ), "{ \\"req\\": \\"num users\\"}" );
574 mbuf->mtype = MT_REQ;
575 msg = rmr_call( mr, msg );
576 if( ! msg ) { // probably a timeout and no msg received
577 return NULL; // let errno trickle up
579 if( mbuf->state != RMR_OK ) {
580 while( retries_left-- > 0 && // loop as long as eagain
582 (msg = rmr_call( mr, msg )) != NULL &&
583 mbuf->state != RMR_OK ) {
584 usleep( retry_delay );
586 if( mbuf == NULL || mbuf->state != RMR_OK ) {
587 rmr_free_msg( mbuf ); // safe if nil
591 // do something with mbuf
596 --------------------------------------------------------------------------------------------
598 rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3),
599 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
600 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
601 rmr_fib(3), rmr_has_str(3), rmr_set_stimeout(3),
602 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
606 --------------------------------------------------------------------------------------------
611 --------------------------------------------------------------------------------------------
617 void rmr_close( void* vctx )
622 --------------------------------------------------------------------------------------------
624 The rmr_close function closes the listen socket effectively
625 cutting the application off. The route table listener is also
626 stopped. Calls to rmr_rcv_msg() will fail with unpredictable
627 error codes, and calls to rmr_send_msg(), rmr_call(), and
628 rmr_rts_msg() will have unknown results.
632 --------------------------------------------------------------------------------------------
634 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
635 rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3),
636 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
637 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
638 rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_open(3),
643 --------------------------------------------------------------------------------------------
648 --------------------------------------------------------------------------------------------
654 void rmr_free_msg( rmr_mbuf_t* mbuf );
659 --------------------------------------------------------------------------------------------
661 The message buffer is returned to the pool, or the associated
662 memory is released depending on the needs of the underlying
663 messaging system. This allows the user application to release
664 a buffer that is not going to be used. It is safe to pass a
665 nil pointer to this function, and doing so does not result in
666 a change to the value of errrno.
668 After calling, the user application should **not** use any of
669 the pointers (transaction ID, or payload) which were
673 --------------------------------------------------------------------------------------------
675 rmr_alloc_msg(3), rmr_call(3), rmr_init(3),
676 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
677 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
678 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
683 --------------------------------------------------------------------------------------------
688 --------------------------------------------------------------------------------------------
694 unsigned char* rmr_get_const();
699 --------------------------------------------------------------------------------------------
701 The rmr_get_const function is a convenience function for
702 wrappers which do not have the ability to "compile in" RMR
703 constants. The function will build a nil terminated string
704 containing JSON which defines the RMR constants that C and Go
705 applications have at compile time via the rmr.h header file.
707 All values are represented as strings and the JSON format is
708 illustrated in the following (partial) example:
716 "RMR_ERR_BADARG", "1",
717 "RMR_ERR_NOENDPT" "2"
723 --------------------------------------------------------------------------------------------
725 On success, a pointer to a string containing the JSON
726 defining constant and value pairs. On failure a nil pointer
730 --------------------------------------------------------------------------------------------
736 --------------------------------------------------------------------------------------------
741 --------------------------------------------------------------------------------------------
747 char* rmr_get_meid( rmr_mbuf_t* mbuf, unsigned char* dest )
752 --------------------------------------------------------------------------------------------
754 The rmr_get_meid function will copy the managed entity ID
755 (meid) field from the message into the *dest* buffer provided
756 by the user. The buffer referenced by *dest* is assumed to be
757 at least RMR_MAX_MEID bytes in length. If *dest* is NULL,
758 then a buffer is allocated (the calling application is
759 expected to free when the buffer is no longer needed).
762 --------------------------------------------------------------------------------------------
764 On success, a pointer to the extracted string is returned. If
765 *dest* was supplied, then this is just a pointer to the
766 caller's buffer. If *dest* was NULL, this is a pointer to the
767 allocated buffer. If an error occurs, a nil pointer is
768 returned and errno is set as described below.
771 --------------------------------------------------------------------------------------------
773 If an error occurs, the value of the global variable errno
774 will be set to one of the following with the indicated
781 The message, or an internal portion of the message, was
782 corrupted or the pointer was invalid.
787 A nil pointer was passed for *dest,* however it was not
788 possible to allocate a buffer using malloc().
792 --------------------------------------------------------------------------------------------
794 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3),
795 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
796 rmr_get_xact(3), rmr_payload_size(3), rmr_send_msg(3),
797 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
798 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
799 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
800 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
804 --------------------------------------------------------------------------------------------
809 --------------------------------------------------------------------------------------------
815 void* rmr_get_rcvfd( void* ctx )
820 --------------------------------------------------------------------------------------------
822 The rmr_get_rcvfd function returns a file descriptor which
823 may be given to epoll_wait() by an application that wishes to
824 use event poll in a single thread rather than block on the
825 arrival of a message via calls to rmr_rcv_msg(). When
826 epoll_wait() indicates that this file descriptor is ready, a
827 call to rmr_rcv_msg() will not block as at least one message
830 The context (ctx) pointer passed in is the pointer returned
831 by the call to rmr_init().
834 --------------------------------------------------------------------------------------------
836 The rmr_get_rcvfd function returns a file descriptor greater
837 or equal to 0 on success and -1 on error.
840 --------------------------------------------------------------------------------------------
842 The following error values are specifically set by this RMR
843 function. In some cases the error message of a system call is
844 propagated up, and thus this list might be incomplete.
849 The use of this function is invalid in this environment.
853 --------------------------------------------------------------------------------------------
855 The following short code bit illustrates the use of this
856 function. Error checking has been omitted for clarity.
863 #include <sys/epoll.h>
866 int rcv_fd; // pollable fd
867 void* mrc; //msg router context
868 struct epoll_event events[10]; // support 10 events to poll
869 struct epoll_event epe; // event definition for event to listen to
871 rmr_mbuf_t* msg = NULL;
874 int norm_msg_size = 1500; // 95% messages are less than this
875 mrc = rmr_init( "43086", norm_msg_size, RMRFL_NONE );
876 rcv_fd = rmr_get_rcvfd( mrc );
877 ep_fd = epoll_create1( 0 ); // initialise epoll environment
878 epe.events = EPOLLIN;
879 epe.data.fd = rcv_fd;
880 epoll_ctl( ep_fd, EPOLL_CTL_ADD, rcv_fd, &epe ); // add our info to the mix
882 nready = epoll_wait( ep_fd, events, 10, -1 ); // -1 == block forever (no timeout)
883 for( i = 0; i < nready && i < 10; i++ ) { // loop through to find what is ready
884 if( events[i].data.fd == rcv_fd ) { // RMR has something
885 msg = rmr_rcv_msg( mrc, msg );
887 // do something with msg
890 // check for other ready fds....
898 --------------------------------------------------------------------------------------------
900 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
901 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
902 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
903 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
908 --------------------------------------------------------------------------------------------
913 --------------------------------------------------------------------------------------------
919 unsigned char* rmr_get_src( rmr_mbuf_t* mbuf, unsigned char* dest )
924 --------------------------------------------------------------------------------------------
926 The rmr_get_src function will copy the *source* information
927 from the message to a buffer (dest) supplied by the user. In
928 an RMR message, the source is the sender's information that
929 is used for return to sender function calls, and is generally
930 the hostname and port in the form *name*. The source might be
931 an IP address port combination; the data is populated by the
932 sending process and the only requirement is that it be
933 capable of being used to start a TCP session with the sender.
935 The maximum size allowed by RMR is 64 bytes (including the
936 nil string terminator), so the user must ensure that the
937 destination buffer given is at least 64 bytes.
940 --------------------------------------------------------------------------------------------
942 On success, a pointer to the destination buffer is given as a
943 convenience to the user programme. On failure, a nil pointer
944 is returned and the value of errno is set.
947 --------------------------------------------------------------------------------------------
949 If an error occurs, the value of the global variable errno
950 will be set to one of the following with the indicated
957 The message, or an internal portion of the message, was
958 corrupted or the pointer was invalid.
962 --------------------------------------------------------------------------------------------
964 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3),
965 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
966 rmr_get_srcip(3), rmr_payload_size(3), rmr_send_msg(3),
967 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
968 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
969 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
970 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
974 --------------------------------------------------------------------------------------------
979 --------------------------------------------------------------------------------------------
985 unsigned char* rmr_get_srcip( rmr_mbuf_t* mbuf, unsigned char* dest )
990 --------------------------------------------------------------------------------------------
992 The rmr_get_srcip function will copy the *source IP address*
993 from the message to a buffer (dest) supplied by the user. In
994 an RMR message, the source IP address is the sender's
995 information that is used for return to sender function calls;
996 this function makes it available to the user application. The
997 address is maintained as IP:port where *IP* could be either
998 an IPv6 or IPv4 address depending on what was provided by the
1001 The maximum size allowed by RMR is 64 bytes (including the
1002 nil string terminator), so the user must ensure that the
1003 destination buffer given is at least 64 bytes. The user
1004 application should use the RMR constant RMR_MAX_SRC to ensure
1005 that the buffer supplied is large enough, and to protect
1006 against future RMR enhancements which might increase the
1007 address buffer size requirement.
1010 --------------------------------------------------------------------------------------------
1012 On success, a pointer to the destination buffer is given as a
1013 convenience to the user programme. On failure, a nil pointer
1014 is returned and the value of errno is set.
1017 --------------------------------------------------------------------------------------------
1019 If an error occurs, the value of the global variable errno
1020 will be set to one of the following with the indicated
1027 The message, or an internal portion of the message, was
1028 corrupted or the pointer was invalid.
1032 --------------------------------------------------------------------------------------------
1034 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3),
1035 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
1036 rmr_get_src(3), rmr_payload_size(3), rmr_send_msg(3),
1037 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1038 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
1039 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
1040 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
1044 --------------------------------------------------------------------------------------------
1049 --------------------------------------------------------------------------------------------
1054 #include <rmr/rmr.h>
1055 int rmr_get_trace( rmr_mbuf_t* mbuf, unsigned char* dest, int size )
1060 --------------------------------------------------------------------------------------------
1062 The rmr_get_trace function will copy the trace information
1063 from the message into the user's allocated memory referenced
1064 by dest. The size parameter is assumed to be the maximum
1065 number of bytes which can be copied (size of the destination
1069 --------------------------------------------------------------------------------------------
1071 On success, the number of bytes actually copied is returned.
1072 If the return value is 0, no bytes copied, then the reason
1073 could be that the message pointer was nil, or the size
1077 --------------------------------------------------------------------------------------------
1079 rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3),
1080 rmr_bytes2meid(3), rmr_call(3), rmr_free_msg(3),
1081 rmr_get_rcvfd(3), rmr_get_trlen(3), rmr_init(3),
1082 rmr_init_trace(3), rmr_payload_size(3), rmr_send_msg(3),
1083 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1084 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
1085 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
1086 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3),
1087 rmr_set_trace(3), rmr_trace_ref(3)
1091 --------------------------------------------------------------------------------------------
1096 --------------------------------------------------------------------------------------------
1101 #include <rmr/rmr.h>
1102 int rmr_get_trlen( rmr_mbuf_t* msg );
1107 --------------------------------------------------------------------------------------------
1109 Given a message buffer, this function returns the amount of
1110 space (bytes) that have been allocated for trace data. If no
1111 trace data has been allocated, then 0 is returned.
1114 --------------------------------------------------------------------------------------------
1116 The number of bytes allocated for trace information in the
1120 --------------------------------------------------------------------------------------------
1126 Parameter(s) passed to the function were not valid.
1130 --------------------------------------------------------------------------------------------
1132 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
1133 rmr_get_trace(3), rmr_init(3), rmr_init_trace(3),
1134 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
1135 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
1136 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
1137 rmr_set_trace(3), rmr_tralloc_msg(3)
1141 --------------------------------------------------------------------------------------------
1146 --------------------------------------------------------------------------------------------
1151 #include <rmr/rmr.h>
1152 char* rmr_get_xact( rmr_mbuf_t* mbuf, unsigned char* dest )
1157 --------------------------------------------------------------------------------------------
1159 The rmr_get_xact function will copy the transaction field
1160 from the message into the *dest* buffer provided by the user.
1161 The buffer referenced by *dest* is assumed to be at least
1162 RMR_MAX_XID bytes in length. If *dest* is NULL, then a buffer
1163 is allocated (the calling application is expected to free
1164 when the buffer is no longer needed).
1167 --------------------------------------------------------------------------------------------
1169 On success, a pointer to the extracted string is returned. If
1170 *dest* was supplied, then this is just a pointer to the
1171 caller's buffer. If *dest* was NULL, this is a pointer to the
1172 allocated buffer. If an error occurs, a nil pointer is
1173 returned and errno is set as described below.
1176 --------------------------------------------------------------------------------------------
1178 If an error occurs, the value of the global variable errno
1179 will be set to one of the following with the indicated
1186 The message, or an internal portion of the message, was
1187 corrupted or the pointer was invalid.
1192 A nil pointer was passed for *dest,* however it was not
1193 possible to allocate a buffer using malloc().
1197 --------------------------------------------------------------------------------------------
1199 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3),
1200 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
1201 rmr_get_meid(3), rmr_payload_size(3), rmr_send_msg(3),
1202 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1203 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
1204 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
1205 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
1209 --------------------------------------------------------------------------------------------
1214 --------------------------------------------------------------------------------------------
1219 #include <rmr/rmr.h>
1220 void* rmr_init( char* proto_port, int norm_msg_size, int flags );
1225 --------------------------------------------------------------------------------------------
1227 The rmr_init function prepares the environment for sending
1228 and receiving messages. It does so by establishing a worker
1229 thread (pthread) which subscribes to a route table generator
1230 which provides the necessary routing information for the RMR
1231 library to send messages.
1233 *Port* is used to listen for connection requests from other
1234 RMR based applications. The *norm_msg_size* parameter is used
1235 to allocate receive buffers and should be set to what the
1236 user application expects to be a size which will hold the
1237 vast majority of expected messages. When computing the size,
1238 the application should consider the usual payload size
1239 **and** the maximum trace data size that will be used. This
1240 value is also used as the default message size when
1241 allocating message buffers (when a zero size is given to
1242 rmr_alloc_msg(); see the rmr_alloc_msg() manual page).
1243 Messages arriving which are longer than the given normal size
1244 will cause RMR to allocate a new buffer which is large enough
1245 for the arriving message.
1247 Starting with version 3.8.0 RMR no longer places a maximum
1248 buffer size for received messages. The underlying system
1249 memory manager might impose such a limit and the attempt to
1250 allocate a buffer larger than that limit will likely result
1251 in an application abort. Other than the potential performance
1252 impact from extra memory allocation and release, there is no
1253 penality to the user programme for specifyning a normal
1254 buffer size which is usually smaller than received buffers.
1255 Similarly, the only penality to the application for over
1256 specifying the normal buffer size might be a larger memory
1259 *Flags* allows for selection of some RMR options at the time
1260 of initialisation. These are set by ORing RMRFL constants
1261 from the RMR header file. Currently the following flags are
1273 The route table collector thread is not to be started.
1274 This should only be used by the route table generator
1275 application if it is based on RMR.
1280 Enable multi-threaded call support.
1285 Some underlying transport providers (e.g. SI95) enable
1286 locking to be turned off if the user application is single
1287 threaded, or otherwise can guarantee that RMR functions
1288 will not be invoked concurrently from different threads.
1289 Turning off locking can help make message receipt more
1290 efficient. If this flag is set when the underlying
1291 transport does not support disabling locks, it will be
1295 Multi-threaded Calling
1296 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1298 The support for an application to issue a *blocking call* by
1299 the rmr_call() function was limited such that only user
1300 applications which were operating in a single thread could
1301 safely use the function. Further, timeouts were message count
1302 based and not time unit based. Multi-threaded call support
1303 adds the ability for a user application with multiple threads
1304 to invoke a blocking call function with the guarantee that
1305 the correct response message is delivered to the thread. The
1306 additional support is implemented with the *rmr_mt_call()*
1307 and *rmr_mt_rcv()* function calls.
1309 Multi-threaded call support requires the user application to
1310 specifically enable it when RMR is initialised. This is
1311 necessary because a second, dedicated, receiver thread must
1312 be started, and requires all messages to be examined and
1313 queued by this thread. The additional overhead is minimal,
1314 queuing information is all in the RMR message header, but as
1315 an additional process is necessary the user application must
1316 "opt in" to this approach.
1320 --------------------------------------------------------------------------------------------
1322 As a part of the initialisation process rmr_init reads
1323 environment variables to configure itself. The following
1324 variables are used if found.
1330 Allows the async connection mode to be turned off (by
1331 setting the value to 0). When set to 1, or missing from
1332 the environment, RMR will invoke the connection interface
1333 in the transport mechanism using the non-blocking (async)
1334 mode. This will likely result in many "soft failures"
1335 (retry) until the connection is established, but allows
1336 the application to continue unimpeded should the
1337 connection be slow to set up.
1342 This provides the interface that RMR will bind listen
1343 ports to, allowing for a single interface to be used
1344 rather than listening across all interfaces. This should
1345 be the IP address assigned to the interface that RMR
1346 should listen on, and if not defined RMR will listen on
1352 This variable defines the port that RMR should open for
1353 communications with Route Manager, and other RMR control
1354 applications. If not defined, the port 4561 is assumed.
1356 Previously, the RMR_RTG_SVC (route table generator service
1357 port) was used to define this port. However, a future
1358 version of Route Manager will require RMR to connect and
1359 request tables, thus that variable is now used to supply
1360 the Route Manager's well-known address and port.
1362 To maintain backwards compatibility with the older Route
1363 Manager versions, the presence of this variable in the
1364 environment will shift RMR's behaviour with respect to the
1365 default value used when RMR_RTG_SVC is **not** defined.
1367 When RMR_CTL_PORT is **defined:** RMR assumes that Route
1368 Manager requires RMR to connect and request table updates
1369 is made, and the default well-known address for Route
1370 manager is used (routemgr:4561).
1372 When RMR_CTL_PORT is **undefined:** RMR assumes that Route
1373 Manager will connect and push table updates, thus the
1374 default listen port (4561) is used.
1376 To avoid any possible misinterpretation and/or incorrect
1377 assumptions on the part of RMR, it is recommended that
1378 both the RMR_CTL_PORT and RMR_RTG_SVC be defined. In the
1379 case where both variables are defined, RMR will behave
1380 exactly as is communicated with the variable's values.
1385 The value of this variable depends on the Route Manager in
1388 When the Route Manager is expecting to connect to an xAPP
1389 and push route tables, this variable must indicate the
1390 port which RMR should use to listen for these connections.
1392 When the Route Manager is expecting RMR to connect and
1393 request a table update during initialisation, the variable
1394 should be the host of the Route Manager process.
1396 The RMR_CTL_PORT variable (added with the support of
1397 sending table update requests to Route manager), controls
1398 the behaviour if this variable is not set. See the
1399 description of that variable for details.
1404 By default RMR writes messages to standard error
1405 (incorrectly referred to as log messages) in human
1406 readable format. If this environment variable is set to 0,
1407 the format of standard error messages might be written in
1408 some format not easily read by humans. If missing, a value
1414 This is a numeric value which corresponds to the verbosity
1415 level used to limit messages written to standard error.
1416 The lower the number the less chatty RMR functions are
1417 during execution. The following is the current
1418 relationship between the value set on this variable and
1419 the messages written:
1424 Off; no messages of any sort are written.
1429 Only critical messages are written (default if this
1430 variable does not exist)
1435 Errors and all messages written with a lower value.
1440 Warnings and all messages written with a lower value.
1445 Informational and all messages written with a lower
1451 Debugging mode -- all messages written, however this
1452 requires RMR to have been compiled with debugging
1459 **Deprecated.** Should be set to 1 if the route table
1460 generator is sending "plain" messages (not using RMR to
1461 send messages), 0 if the RTG is using RMR to send. The
1462 default is 1 as we don't expect the RTG to use RMR.
1464 This variable is only recognised when using the NNG
1465 transport library as it is not possible to support NNG
1466 "raw" communications with other transport libraries. It is
1467 also necessary to match the value of this variable with
1468 the capabilities of the Route Manager; at some point in
1469 the future RMR will assume that all Route Manager messages
1470 will arrive via an RMR connection and will ignore this
1475 This is used to supply a static route table which can be
1476 used for debugging, testing, or if no route table
1477 generator process is being used to supply the route table.
1478 If not defined, no static table is used and RMR will not
1479 report *ready* until a table is received. The static route
1480 table may contain both the route table (between newrt
1481 start and end records), and the MEID map (between meid_map
1482 start and end records).
1486 This is either the name or IP address which is placed into
1487 outbound messages as the message source. This will used
1488 when an RMR based application uses the rmr_rts_msg()
1489 function to return a response to the sender. If not
1490 supplied RMR will use the hostname which in some container
1491 environments might not be routable.
1493 The value of this variable is also used for Route Manager
1494 messages which are sent via an RMR connection.
1498 This supplies the name of a verbosity control file. The
1499 core RMR functions do not produce messages unless there is
1500 a critical failure. However, the route table collection
1501 thread, not a part of the main message processing
1502 component, can write additional messages to standard
1503 error. If this variable is set, RMR will extract the
1504 verbosity level for these messages (0 is silent) from the
1505 first line of the file. Changes to the file are detected
1506 and thus the level can be changed dynamically, however RMR
1507 will only suss out this variable during initialisation, so
1508 it is impossible to enable verbosity after startup.
1512 If set to 1, RMR will write some warnings which are
1513 non-performance impacting. If the variable is not defined,
1514 or set to 0, RMR will not write these additional warnings.
1518 --------------------------------------------------------------------------------------------
1520 The rmr_init function returns a void pointer (a contex if you
1521 will) that is passed as the first parameter to nearly all
1522 other RMR functions. If rmr_init is unable to properly
1523 initialise the environment, NULL is returned and errno is set
1524 to an appropriate value.
1527 --------------------------------------------------------------------------------------------
1529 The following error values are specifically set by this RMR
1530 function. In some cases the error message of a system call is
1531 propagated up, and thus this list might be incomplete.
1536 Unable to allocate memory.
1540 --------------------------------------------------------------------------------------------
1546 rmr_mbuf* buf = NULL;
1547 uh = rmr_init( "43086", 4096, 0 );
1548 buf = rmr_rcv_msg( uh, buf );
1553 --------------------------------------------------------------------------------------------
1555 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
1556 rmr_get_rcvfd(3), rmr_mt_call(3), rmr_mt_rcv(3),
1557 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
1558 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
1559 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
1564 --------------------------------------------------------------------------------------------
1569 --------------------------------------------------------------------------------------------
1574 #include <rmr/rmr.h>
1575 void* rmr_init_trace( void* ctx )
1580 --------------------------------------------------------------------------------------------
1582 The rmr_init_trace function establishes the default trace
1583 space placed in each message buffer allocated with
1584 rmr_alloc_msg(). If this function is never called, then no
1585 trace space is allocated by default into any message buffer.
1587 Trace space allows the user application to pass some trace
1588 token, or other data with the message, but outside of the
1589 payload. Trace data may be added to any message with
1590 rmr_set_trace(), and may be extracted from a message with
1591 rmr_get_trace(). The number of bytes that a message contains
1592 for/with trace data can be determined by invoking
1595 This function may be safely called at any time during the
1596 life of the user programme to (re)set the default trace space
1597 reserved. If the user programme needs to allocate a message
1598 with trace space of a different size than is allocated by
1599 default, without fear of extra overhead of reallocating a
1600 message later, the rmr_tralloc_msg() function can be used.
1603 --------------------------------------------------------------------------------------------
1605 A value of 1 is returned on success, and 0 on failure. A
1606 failure indicates that the RMR context (a void pointer passed
1607 to this function was not valid.
1610 --------------------------------------------------------------------------------------------
1612 rmr_alloc_msg(3), rmr_tr_alloc_msg(3), rmr_call(3),
1613 rmr_free_msg(3), rmr_get_rcvfd(3), rmr_get_trace(3),
1614 rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
1615 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1616 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
1617 rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)
1621 --------------------------------------------------------------------------------------------
1626 --------------------------------------------------------------------------------------------
1631 #include <rmr/rmr.h>
1632 extern rmr_mbuf_t* rmr_mt_call( void* vctx, rmr_mbuf_t* msg, int id, int timeout );
1637 --------------------------------------------------------------------------------------------
1639 The rmr_mt_call function sends the user application message
1640 to a remote endpoint, and waits for a corresponding response
1641 message before returning control to the user application. The
1642 user application supplies a completed message buffer, as it
1643 would for a rmr_send_msg call, but unlike with a send, the
1644 buffer returned will have the response from the application
1645 that received the message. The thread invoking the
1646 *rmr_mt_call()* will block until a message arrives or until
1647 *timeout* milliseconds has passed; which ever comes first.
1648 Using a timeout value of zero (0) will cause the thread to
1649 block without a timeout.
1651 The *id* supplied as the third parameter is an integer in the
1652 range of 2 through 255 inclusive. This is a caller defined
1653 "thread number" and is used to match the response message
1654 with the correct user application thread. If the ID value is
1655 not in the proper range, the attempt to make the call will
1658 Messages which are received while waiting for the response
1659 are queued on a *normal* receive queue and will be delivered
1660 to the user application with the next invocation of
1661 *rmr_mt_rcv()* or *rmr_rvv_msg().* by RMR, and are returned
1662 to the user application when rmr_rcv_msg is invoked. These
1663 messages are returned in the order received, one per call to
1667 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1669 The user application is responsible for setting the value of
1670 the transaction ID field before invoking *rmr_mt_call.* The
1671 transaction ID is a RMR_MAX_XID byte field that is used to
1672 match the response message when it arrives. RMR will compare
1673 **all** of the bytes in the field, so the caller must ensure
1674 that they are set correctly to avoid missing the response
1675 message. The application which returns the response message
1676 is also expected to ensure that the return buffer has the
1677 matching transaction ID. This can be done transparently if
1678 the application uses the *rmr_rts_msg()* function and does
1679 not adjust the transaction ID.
1682 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1684 The send operations in RMR will retry *soft* send failures
1685 until one of three conditions occurs:
1691 The message is sent without error
1696 The underlying transport reports a *hard* failure
1701 The maximum number of retry loops has been attempted
1704 A retry loop consists of approximately 1000 send attempts
1705 **without** any intervening calls to *sleep()* or *usleep().*
1706 The number of retry loops defaults to 1, thus a maximum of
1707 1000 send attempts is performed before returning to the user
1708 application. This value can be set at any point after RMR
1709 initialisation using the *rmr_set_stimeout()* function
1710 allowing the user application to completely disable retires
1711 (set to 0), or to increase the number of retry loops.
1713 Transport Level Blocking
1714 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1716 The underlying transport mechanism used to send messages is
1717 configured in *non-blocking* mode. This means that if a
1718 message cannot be sent immediately the transport mechanism
1719 will **not** pause with the assumption that the inability to
1720 send will clear quickly (within a few milliseconds). This
1721 means that when the retry loop is completely disabled (set to
1722 0), that the failure to accept a message for sending by the
1723 underlying mechanisms (software or hardware) will be reported
1724 immediately to the user application.
1726 It should be noted that depending on the underlying transport
1727 mechanism being used, it is extremely likely that retry
1728 conditions will happen during normal operations. These are
1729 completely out of RMR's control, and there is nothing that
1730 RMR can do to avoid or mitigate these other than by allowing
1731 RMR to retry the send operation, and even then it is possible
1732 (e.g., during connection reattempts), that a single retry
1733 loop is not enough to guarantee a successful send.
1736 --------------------------------------------------------------------------------------------
1738 The rmr_mt_call function returns a pointer to a message
1739 buffer with the state set to reflect the overall state of
1740 call processing. If the state is RMR_OK then the buffer
1741 contains the response message; otherwise the state indicates
1742 the error encountered while attempting to send the message.
1744 If no response message is received when the timeout period
1745 has expired, a nil pointer will be returned (NULL).
1748 --------------------------------------------------------------------------------------------
1750 These values are reflected in the state field of the returned
1757 The call was successful and the message buffer references
1758 the response message.
1763 An argument passed to the function was invalid.
1768 The call failed and the value of *errno,* as described
1769 below, should be checked for the specific reason.
1774 An endpoint associated with the message type could not be
1775 found in the route table.
1780 The underlying transport mechanism was unable to accept
1781 the message for sending. The user application can retry
1782 the call operation if appropriate to do so.
1785 The global "variable" *errno* will be set to one of the
1786 following values if the overall call processing was not
1793 Too many messages were queued before receiving the
1799 The queued message ring is full, messages were dropped
1804 A parameter was not valid
1809 The underlying message system wsa interrupted or the
1810 device was busy; the message was **not** sent, and user
1811 application should call this function with the message
1816 --------------------------------------------------------------------------------------------
1818 The following code bit shows one way of using the rmr_mt_call
1819 function, and illustrates how the transaction ID must be set.
1824 int retries_left = 5; // max retries on dev not available
1825 static rmr_mbuf_t* mbuf = NULL; // response msg
1826 msg_t* pm; // appl message struct (payload)
1827 // get a send buffer and reference the payload
1828 mbuf = rmr_alloc_msg( mr, sizeof( pm->req ) );
1829 pm = (msg_t*) mbuf->payload;
1830 // generate an xaction ID and fill in payload with data and msg type
1831 rmr_bytes2xact( mbuf, xid, RMR_MAX_XID );
1832 snprintf( pm->req, sizeof( pm->req ), "{ \\"req\\": \\"num users\\"}" );
1833 mbuf->mtype = MT_USR_RESP;
1834 msg = rmr_mt_call( mr, msg, my_id, 100 ); // wait up to 100ms
1835 if( ! msg ) { // probably a timeout and no msg received
1836 return NULL; // let errno trickle up
1838 if( mbuf->state != RMR_OK ) {
1839 while( retries_left-- > 0 && // loop as long as eagain
1840 mbuf->state == RMR_ERR_RETRY &&
1841 (msg = rmr_mt_call( mr, msg )) != NULL &&
1842 mbuf->state != RMR_OK ) {
1843 usleep( retry_delay );
1845 if( mbuf == NULL || mbuf->state != RMR_OK ) {
1846 rmr_free_msg( mbuf ); // safe if nil
1850 // do something with mbuf
1855 --------------------------------------------------------------------------------------------
1857 rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3),
1858 rmr_mt_rcv(3), rmr_payload_size(3), rmr_send_msg(3),
1859 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1860 rmr_ready(3), rmr_fib(3), rmr_has_str(3),
1861 rmr_set_stimeout(3), rmr_tokenise(3), rmr_mk_ring(3),
1866 --------------------------------------------------------------------------------------------
1871 --------------------------------------------------------------------------------------------
1876 #include <rmr/rmr.h>
1877 rmr_mbuf_t* rmr_mt_rcv( void* vctx, rmr_mbuf_t* old_msg, int timeout );
1882 --------------------------------------------------------------------------------------------
1884 The rmr_mt_rcv function blocks until a message is received,
1885 or the timeout period (milliseconds) has passed. The result
1886 is an RMR message buffer which references a received message.
1887 In the case of a timeout the state will be reflected in an
1888 "empty buffer" (if old_msg was not nil, or simply with the
1889 return of a nil pointer. If a timeout value of zero (0) is
1890 given, then the function will block until the next message
1893 The *vctx* pointer is the pointer returned by the rmr_init
1894 function. *Old_msg* is a pointer to a previously used message
1895 buffer or NULL. The ability to reuse message buffers helps to
1896 avoid alloc/free cycles in the user application. When no
1897 buffer is available to supply, the receive function will
1900 The *old_msg* parameter allows the user to pass a previously
1901 generated RMR message back to RMR for reuse. Optionally, the
1902 user application may pass a nil pointer if no reusable
1903 message is available. When a timeout occurs, and old_msg was
1904 not nil, the state will be returned by returning a pointer to
1905 the old message with the state set.
1907 It is possible to use the *rmr_rcv_msg()* function instead of
1908 this function. Doing so might be advantageous if the user
1909 programme does not always start the multi-threaded mode and
1910 the use of *rmr_rcv_msg()* would make the flow of the code
1911 more simple. The advantages of using this function are the
1912 ability to set a timeout without using epoll, and a small
1913 performance gain (if multi-threaded mode is enabled, and the
1914 *rmr_rcv_msg()* function is used, it simply invokes this
1915 function without a timeout value, thus there is the small
1916 cost of a second call that results). Similarly, the
1917 *rmr_torcv_msg()* call can be used when in multi-threaded
1918 mode with the same "pass through" overhead to using this
1922 --------------------------------------------------------------------------------------------
1924 When a message is received before the timeout period expires,
1925 a pointer to the RMR message buffer which describes the
1926 message is returned. This will, with a high probability, be a
1927 different message buffer than *old_msg;* the user application
1928 should not continue to use *old_msg* after it is passed to
1931 In the event of a timeout the return value will be the old
1932 msg with the state set, or a nil pointer if no old message
1936 --------------------------------------------------------------------------------------------
1938 The *state* field in the message buffer will be set to one of
1939 the following values:
1945 The message was received without error.
1950 A parameter passed to the function was not valid (e.g. a
1951 nil pointer). indicate either RMR_OK or RMR_ERR_EMPTY if
1952 an empty message was received.
1957 The message received had no associated data. The length of
1958 the message will be 0.
1963 The multi-threaded option was not enabled when RMR was
1964 initialised. See the man page for *rmr_init()* for
1970 A hard error occurred preventing the receive from
1973 When a nil pointer is returned, or any other state value was
1974 set in the message buffer, errno will be set to one of the
1981 Parameter(s) passed to the function were not valid.
1986 The underlying message transport is unable to process the
1992 The underlying message transport is unable to process the
1998 The underlying message transport is unable to process the
2004 The underlying message transport is unable to process the
2010 The underlying message transport is unable to process the
2016 The underlying message transport is unable to process the
2022 The underlying message transport is unable to process the
2027 --------------------------------------------------------------------------------------------
2033 rmr_mbuf_t* mbuf = NULL; // received msg
2034 msg = rmr_mt_recv( mr, mbuf, 100 ); // wait up to 100ms
2036 switch( msg->state ) {
2038 printf( "got a good message\\n" );
2041 printf( "received timed out\\n" );
2044 printf( "receive error: %d\\n", mbuf->state );
2048 printf( "receive timeout (nil)\\n" );
2054 --------------------------------------------------------------------------------------------
2056 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
2057 rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3),
2058 rmr_mt_call(3), rmr_payload_size(3), rmr_send_msg(3),
2059 rmr_torcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
2060 rmr_ready(3), rmr_ring_free(3), rmr_torcv_msg(3)
2064 --------------------------------------------------------------------------------------------
2069 --------------------------------------------------------------------------------------------
2074 #include <rmr/rmr.h>
2075 int rmr_payload_size( rmr_mbuf_t* msg );
2080 --------------------------------------------------------------------------------------------
2082 Given a message buffer, this function returns the amount of
2083 space (bytes) available for the user application to consume
2084 in the message payload. This is different than the message
2085 length available as a field in the message buffer.
2088 --------------------------------------------------------------------------------------------
2090 The number of bytes available in the payload.
2093 --------------------------------------------------------------------------------------------
2099 Parameter(s) passed to the function were not valid.
2103 --------------------------------------------------------------------------------------------
2105 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2106 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
2107 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
2108 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
2112 --------------------------------------------------------------------------------------------
2117 --------------------------------------------------------------------------------------------
2122 #include <rmr/rmr.h>
2123 rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg );
2128 --------------------------------------------------------------------------------------------
2130 The rmr_rcv_msg function blocks until a message is received,
2131 returning the message to the caller via a pointer to a
2132 rmr_mbuf_t structure type. If messages were queued while
2133 waiting for the response to a previous invocation of
2134 rmr_call, the oldest message is removed from the queue and
2135 returned without delay.
2137 The *vctx* pointer is the pointer returned by the rmr_init
2138 function. *Old_msg* is a pointer to a previously used message
2139 buffer or NULL. The ability to reuse message buffers helps to
2140 avoid alloc/free cycles in the user application. When no
2141 buffer is available to supply, the receive function will
2145 --------------------------------------------------------------------------------------------
2147 The function returns a pointer to the rmr_mbuf_t structure
2148 which references the message information (state, length,
2149 payload), or a nil pointer in the case of an extreme error.
2152 --------------------------------------------------------------------------------------------
2154 The *state* field in the message buffer will indicate RMR_OK
2155 when the message receive process was successful and the
2156 message can be used by the caller. Depending on the
2157 underlying transport mechanism, one of the following RMR
2158 error stats may be returned:
2164 The message received had no payload, or was completely
2170 For some transport mechanisms, or if reading the receive
2171 queue from multiple threads, it is possible for one thread
2172 to find no data waiting when it queries the queue. When
2173 this state is reported, the message buffer does not
2174 contain message data and the user application should
2175 reinvoke the receive function.
2178 When an RMR error state is reported, the underlying errno
2179 value might provide more information. The following is a list
2180 of possible values that might accompany the states listed
2183 RMR_ERR_EMPTY if an empty message was received. If a nil
2184 pointer is returned, or any other state value was set in the
2185 message buffer, errno will be set to one of the following:
2191 Parameter(s) passed to the function were not valid.
2196 The underlying message transport is unable to process the
2202 The underlying message transport is unable to process the
2208 The underlying message transport is unable to process the
2214 The underlying message transport is unable to process the
2220 The underlying message transport is unable to process the
2226 The underlying message transport is unable to process the
2232 The underlying message transport is unable to process the
2237 --------------------------------------------------------------------------------------------
2241 --------------------------------------------------------------------------------------------
2243 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
2244 rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3),
2245 rmr_payload_size(3), rmr_send_msg(3), rmr_torcv_msg(3),
2246 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
2247 rmr_ring_free(3), rmr_torcv_msg(3)
2251 --------------------------------------------------------------------------------------------
2256 --------------------------------------------------------------------------------------------
2261 #include <rmr/rmr.h>
2262 int rmr_ready( void* vctx );
2267 --------------------------------------------------------------------------------------------
2269 The rmr_ready function checks to see if a routing table has
2270 been successfully received and installed. The return value
2271 indicates the state of readiness.
2274 --------------------------------------------------------------------------------------------
2276 A return value of 1 (true) indicates that the routing table
2277 is in place and attempts to send messages can be made. When 0
2278 is returned (false) the routing table has not been received
2279 and thus attempts to send messages will fail with *no
2283 --------------------------------------------------------------------------------------------
2285 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2286 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
2287 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_fib(3),
2288 rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
2293 --------------------------------------------------------------------------------------------
2298 --------------------------------------------------------------------------------------------
2303 #include <rmr/rmr.h>
2304 extern rmr_mbuf_t* rmr_realloc_payload( rmr_mbuf_t* msg, int new_len, int copy, int clone );
2309 --------------------------------------------------------------------------------------------
2311 The rmr_realloc_payload function will return a pointer to an
2312 RMR message buffer struct (rmr_mbuf_t) which has a payload
2313 large enough to accomodate *new_len* bytes. If necessary, the
2314 underlying payload is reallocated, and the bytes from the
2315 original payload are copied if the *copy* parameter is true
2316 (1). If the message passed in has a payload large enough,
2317 there is no additional memory allocation and copying.
2319 Cloning The Message Buffer
2320 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2322 This function can also be used to generate a separate copy of
2323 the original message, with the desired payload size, without
2324 destroying the original message buffer or the original
2325 payload. A standalone copy is made only when the *clone*
2326 parameter is true (1). When cloning, the payload is copied to
2327 the cloned message **only** if the *copy* parameter is true.
2329 Message Buffer Metadata
2330 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2332 The metadata in the original message buffer (message type,
2333 subscription ID, and payload length) will be preserved if the
2334 *copy* parameter is true. When this parameter is not true
2335 (0), then these values are set to the uninitialised value
2336 (-1) for type and ID, and the length is set to 0.
2339 --------------------------------------------------------------------------------------------
2341 The rmr_realloc_payload function returns a pointer to the
2342 message buffer with the payload which is large enough to hold
2343 *new_len* bytes. If the *clone* option is true, this will be
2344 a pointer to the newly cloned message buffer; the original
2345 message buffer pointer may still be used to reference that
2346 message. It is the calling application's responsibility to
2347 free the memory associateed with both messages using the
2348 rmr_free_msg() function.
2350 When the *clone* option is not used, it is still good
2351 practice by the calling application to capture and use this
2352 reference as it is possible that the message buffer, and not
2353 just the payload buffer, was reallocated. In the event of an
2354 error, a nil pointer will be returned and the value of
2355 *errno* will be set to reflect the problem.
2358 --------------------------------------------------------------------------------------------
2360 These value of *errno* will reflect the error condition if a
2361 nil pointer is returned:
2367 Memory allocation of the new payload failed.
2372 The pointer passed in was nil, or refrenced an invalid
2373 message, or the required length was not valid.
2377 --------------------------------------------------------------------------------------------
2379 The following code bit illustrates how this function can be
2380 used to reallocate a buffer for a return to sender
2381 acknowledgement message which is larger than the message
2387 if( rmr_payload_size( msg ) < ack_sz ) { // received message too small for ack
2388 msg = rmr_realloc_payload( msg, ack_sz, 0, 0 ); // reallocate the message with a payload big enough
2390 fprintf( stderr, "[ERR] realloc returned a nil pointer: %s\\n", strerror( errno ) );
2392 // populate and send ack message
2399 --------------------------------------------------------------------------------------------
2401 rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3),
2402 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
2403 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
2404 rmr_fib(3), rmr_has_str(3), rmr_set_stimeout(3),
2405 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
2409 --------------------------------------------------------------------------------------------
2414 --------------------------------------------------------------------------------------------
2419 #include <rmr/rmr.h>
2420 rmr_mbuf_t* rmr_rts_msg( void* vctx, rmr_mbuf_t* msg );
2425 --------------------------------------------------------------------------------------------
2427 The rmr_rts_msg function sends a message returning it to the
2428 endpoint which sent the message rather than selecting an
2429 endpoint based on the message type and routing table. Other
2430 than this small difference, the behaviour is exactly the same
2434 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2436 The send operations in RMR will retry *soft* send failures
2437 until one of three conditions occurs:
2443 The message is sent without error
2448 The underlying transport reports a *hard* failure
2453 The maximum number of retry loops has been attempted
2456 A retry loop consists of approximately 1000 send attempts
2457 **without** any intervening calls to *sleep()* or *usleep().*
2458 The number of retry loops defaults to 1, thus a maximum of
2459 1000 send attempts is performed before returning to the user
2460 application. This value can be set at any point after RMR
2461 initialisation using the *rmr_set_stimeout()* function
2462 allowing the user application to completely disable retires
2463 (set to 0), or to increase the number of retry loops.
2465 Transport Level Blocking
2466 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2468 The underlying transport mechanism used to send messages is
2469 configured in *non-blocking* mode. This means that if a
2470 message cannot be sent immediately the transport mechanism
2471 will **not** pause with the assumption that the inability to
2472 send will clear quickly (within a few milliseconds). This
2473 means that when the retry loop is completely disabled (set to
2474 0), that the failure to accept a message for sending by the
2475 underlying mechanisms (software or hardware) will be reported
2476 immediately to the user application.
2478 It should be noted that depending on the underlying transport
2479 mechanism being used, it is extremely likely that retry
2480 conditions will happen during normal operations. These are
2481 completely out of RMR's control, and there is nothing that
2482 RMR can do to avoid or mitigate these other than by allowing
2483 RMR to retry the send operation, and even then it is possible
2484 (e.g., during connection reattempts), that a single retry
2485 loop is not enough to guarantee a successful send.
2488 --------------------------------------------------------------------------------------------
2490 When crafting a response based on a received message, the
2491 user application must take care not to write more bytes to
2492 the message payload than the allocated message has. In the
2493 case of a received message, it is possible that the response
2494 needs to be larger than the payload associated with the
2495 inbound message. In order to use the return to sender
2496 function, the source information in the original message must
2497 be present in the response; information which cannot be added
2498 to a message buffer allocated through the standard RMR
2499 allocation function. To allocate a buffer with a larger
2500 payload, and which retains the necessary sender data needed
2501 by this function, the *rmr_realloc_payload()* function must
2502 be used to extend the payload to a size suitable for the
2506 --------------------------------------------------------------------------------------------
2508 On success, a new message buffer, with an empty payload, is
2509 returned for the application to use for the next send. The
2510 state in this buffer will reflect the overall send operation
2511 state and should be RMR_OK.
2513 If the state in the returned buffer is anything other than
2514 RMR_OK, the user application may need to attempt a
2515 retransmission of the message, or take other action depending
2516 on the setting of errno as described below.
2518 In the event of extreme failure, a nil pointer is returned.
2519 In this case the value of errno might be of some use, for
2520 documentation, but there will be little that the user
2521 application can do other than to move on.
2524 --------------------------------------------------------------------------------------------
2526 The following values may be passed back in the *state* field
2527 of the returned message buffer.
2533 The message buffer pointer did not refer to a valid
2538 The header in the message buffer was not valid or
2543 The message type in the message buffer did not map to a
2548 The send failed; errno has the possible reason.
2551 The following values may be assigned to errno on failure.
2556 Parameter(s) passed to the function were not valid, or the
2557 underlying message processing environment was unable to
2558 interpret the message.
2563 The header information in the message buffer was invalid.
2568 No known endpoint for the message could be found.
2573 The underlying transport refused to accept the message
2574 because of a size value issue (message was not attempted
2580 The message referenced by the message buffer is corrupt
2581 (nil pointer or bad internal length).
2586 Internal RMR error; information provided to the message
2587 transport environment was not valid.
2592 Sending was not supported by the underlying message
2598 The device is not in a state that can accept the message.
2603 The device is not able to accept a message for sending.
2604 The user application should attempt to resend.
2609 The operation was interrupted by delivery of a signal
2610 before the message was sent.
2615 The underlying message environment timed out during the
2621 The underlying message environment is in a shutdown state.
2625 --------------------------------------------------------------------------------------------
2629 --------------------------------------------------------------------------------------------
2631 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2632 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
2633 rmr_rcv_specific(3), rmr_ready(3), rmr_fib(3),
2634 rmr_has_str(3), rmr_set_stimeout(3), rmr_tokenise(3),
2635 rmr_mk_ring(3), rmr_ring_free(3)
2639 --------------------------------------------------------------------------------------------
2644 --------------------------------------------------------------------------------------------
2649 #include <rmr/rmr.h>
2650 rmr_mbuf_t* rmr_send_msg( void* vctx, rmr_mbuf_t* msg );
2655 --------------------------------------------------------------------------------------------
2657 The rmr_send_msg function accepts a message buffer from the
2658 user application and attempts to send it. The destination of
2659 the message is selected based on the message type specified
2660 in the message buffer, and the matching information in the
2661 routing tables which are currently in use by the RMR library.
2662 This may actually result in the sending of the message to
2663 multiple destinations which could degrade expected overall
2664 performance of the user application. (Limiting excessive
2665 sending of messages is the responsibility of the
2666 application(s) responsible for building the routing table
2667 used by the RMR library, and not the responsibility of the
2671 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2673 The send operations in RMR will retry *soft* send failures
2674 until one of three conditions occurs:
2680 The message is sent without error
2685 The underlying transport reports a *hard* failure
2690 The maximum number of retry loops has been attempted
2693 A retry loop consists of approximately 1000 send attempts
2694 **without** any intervening calls to *sleep()* or *usleep().*
2695 The number of retry loops defaults to 1, thus a maximum of
2696 1000 send attempts is performed before returning to the user
2697 application. This value can be set at any point after RMR
2698 initialisation using the *rmr_set_stimeout()* function
2699 allowing the user application to completely disable retires
2700 (set to 0), or to increase the number of retry loops.
2702 Transport Level Blocking
2703 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2705 The underlying transport mechanism used to send messages is
2706 configured in *non-blocking* mode. This means that if a
2707 message cannot be sent immediately the transport mechanism
2708 will **not** pause with the assumption that the inability to
2709 send will clear quickly (within a few milliseconds). This
2710 means that when the retry loop is completely disabled (set to
2711 0), that the failure to accept a message for sending by the
2712 underlying mechanisms (software or hardware) will be reported
2713 immediately to the user application.
2715 It should be noted that depending on the underlying transport
2716 mechanism being used, it is extremely likely that retry
2717 conditions will happen during normal operations. These are
2718 completely out of RMR's control, and there is nothing that
2719 RMR can do to avoid or mitigate these other than by allowing
2720 RMR to retry the send operation, and even then it is possible
2721 (e.g., during connection reattempts), that a single retry
2722 loop is not enough to guarantee a successful send.
2725 --------------------------------------------------------------------------------------------
2727 On success, a new message buffer, with an empty payload, is
2728 returned for the application to use for the next send. The
2729 state in this buffer will reflect the overall send operation
2730 state and will be RMR_OK when the send was successful.
2732 When the message cannot be successfully sent this function
2733 will return the unsent (original) message buffer with the
2734 state set to indicate the reason for failure. The value of
2735 *errno* may also be set to reflect a more detailed failure
2736 reason if it is known.
2738 In the event of extreme failure, a nil pointer is returned.
2739 In this case the value of errno might be of some use, for
2740 documentation, but there will be little that the user
2741 application can do other than to move on.
2743 **CAUTION:** In some cases it is extremely likely that the
2744 message returned by the send function does **not** reference
2745 the same memory structure. Thus is important for the user
2746 programme to capture the new pointer for future use or to be
2747 passed to rmr_free(). If you are experiencing either double
2748 free errors or segment faults in either rmr_free() or
2749 rmr_send_msg(), ensure that the return value from this
2750 function is being captured and used.
2753 --------------------------------------------------------------------------------------------
2755 The following values may be passed back in the *state* field
2756 of the returned message buffer.
2762 The message could not be sent, but the underlying
2763 transport mechanism indicates that the failure is
2764 temporary. If the send operation is tried again it might
2769 The send operation was not successful and the underlying
2770 transport mechanism indicates a permanent (hard) failure;
2771 retrying the send is not possible.
2775 The message buffer pointer did not refer to a valid
2780 The header in the message buffer was not valid or
2785 The message type in the message buffer did not map to a
2789 The following values may be assigned to errno on failure.
2794 Parameter(s) passed to the function were not valid, or the
2795 underlying message processing environment was unable to
2796 interpret the message.
2801 The header information in the message buffer was invalid.
2806 No known endpoint for the message could be found.
2811 The underlying transport refused to accept the message
2812 because of a size value issue (message was not attempted
2818 The message referenced by the message buffer is corrupt
2819 (nil pointer or bad internal length).
2824 Internal RMR error; information provided to the message
2825 transport environment was not valid.
2830 Sending was not supported by the underlying message
2836 The device is not in a state that can accept the message.
2841 The device is not able to accept a message for sending.
2842 The user application should attempt to resend.
2847 The operation was interrupted by delivery of a signal
2848 before the message was sent.
2853 The underlying message environment timed out during the
2859 The underlying message environment is in a shutdown state.
2863 --------------------------------------------------------------------------------------------
2865 The following is a simple example of how the rmr_send_msg
2866 function is called. In this example, the send message buffer
2867 is saved between calls and reused eliminating alloc/free
2873 static rmr_mbuf_t* send_msg = NULL; // message to send; reused on each call
2874 msg_t* send_pm; // payload for send
2875 msg_t* pm; // our message format in the received payload
2876 if( send_msg == NULL ) {
2877 send_msg = rmr_alloc_msg( mr, MAX_SIZE ); // new buffer to send
2879 // reference payload and fill in message type
2880 pm = (msg_t*) send_msg->payload;
2881 send_msg->mtype = MT_ANSWER;
2882 msg->len = generate_data( pm ); // something that fills the payload in
2883 msg = rmr_send_msg( mr, send_msg ); // ensure new pointer used after send
2887 if( msg->state != RMR_OK ) {
2888 // check for RMR_ERR_RETRY, and resend if needed
2889 // else return error
2897 --------------------------------------------------------------------------------------------
2899 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2900 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
2901 rmr_rts_msg(3), rmr_ready(3), rmr_mk_ring(3),
2902 rmr_ring_free(3), rmr_torcv_rcv(3), rmr_wh_send_msg(3)
2906 --------------------------------------------------------------------------------------------
2911 --------------------------------------------------------------------------------------------
2916 #include <rmr/rmr.h>
2917 void rmr_set_fack( void* vctx );
2922 --------------------------------------------------------------------------------------------
2924 The rmr_set_fack function enables *fast TCP acknowledgements*
2925 if the underlying transport library supports it. This might
2926 be useful for applications which must send messages at a
2930 --------------------------------------------------------------------------------------------
2932 There is no return value.
2935 --------------------------------------------------------------------------------------------
2937 This function does not generate any errors.
2940 --------------------------------------------------------------------------------------------
2946 --------------------------------------------------------------------------------------------
2951 --------------------------------------------------------------------------------------------
2956 #include <rmr/rmr.h>
2957 rmr_mbuf_t* rmr_set_stimeout( void* vctx, int rloops );
2962 --------------------------------------------------------------------------------------------
2964 The rmr_set_stimeout function sets the configuration for how
2965 RMR will retry message send operations which complete with
2966 either a *timeout* or *again* completion value. (Send
2967 operations include all of the possible message send
2968 functions: *rmr_send_msg(), rmr_call(), rmr_rts_msg()* and
2969 *rmr_wh_send_msg().* The *rloops* parameter sets the maximum
2970 number of retry loops that will be attempted before giving up
2971 and returning the unsuccessful state to the user application.
2972 Each retry loop is approximately 1000 attempts, and RMR does
2973 **not** invoke any sleep function between retries in the
2974 loop; a small, 1 mu-sec, sleep is executed between loop sets
2975 if the *rloops* value is greater than 1.
2979 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2981 By default, the send operations will execute with an *rloop*
2982 setting of 1; each send operation will attempt to resend the
2983 message approximately 1000 times before giving up. If the
2984 user application does not want to have send operations retry
2985 when the underlying transport mechanism indicates *timeout*
2986 or *again,* the application should invoke this function and
2987 pass a value of 0 (zero) for *rloops.* With this setting, all
2988 RMR send operations will attempt a send operation only
2989 **once,** returning immediately to the caller with the state
2990 of that single attempt.
2993 --------------------------------------------------------------------------------------------
2995 This function returns a -1 to indicate that the *rloops*
2996 value could not be set, and the value *RMR_OK* to indicate
3000 --------------------------------------------------------------------------------------------
3002 Currently errno is **not** set by this function; the only
3003 cause of a failure is an invalid context (*vctx*) pointer.
3006 --------------------------------------------------------------------------------------------
3008 The following is a simple example of how the rmr_set_stimeout
3015 char* port = "43086"; // port for message router listen
3016 int max_size = 4096; // max message size for default allocations
3017 void* mr_context; // message router context
3018 mr_context = rmr_init( port, max_size, NO_FLAGS );
3019 if( mr_context != NULL ) {
3020 rmr_set_stimeout( mr_context, 0 ); // turn off retries
3026 --------------------------------------------------------------------------------------------
3028 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
3029 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
3030 rmr_rts_msg(3), rmr_ready(3), rmr_mk_ring(3),
3031 rmr_ring_free(3), rmr_send_msg(3), rmr_torcv_rcv(3),
3036 --------------------------------------------------------------------------------------------
3041 --------------------------------------------------------------------------------------------
3046 #include <rmr/rmr.h>
3047 int rmr_set_trace( rmr_mbuf_t* mbuf, unsigned char* data, int len )
3052 --------------------------------------------------------------------------------------------
3054 The rmr_set_trace function will copy len bytes from data into
3055 the trace portion of mbuf. If the trace area of mbuf is not
3056 the correct size, the message buffer will be reallocated to
3057 ensure that enough space is available for the trace data.
3060 --------------------------------------------------------------------------------------------
3062 The rmr_set_trace function returns the number of bytes
3063 successfully copied to the message. If 0 is returned either
3064 the message pointer was nil, or the size in the parameters
3068 --------------------------------------------------------------------------------------------
3070 rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3),
3071 rmr_bytes2payload(3), rmr_call(3), rmr_free_msg(3),
3072 rmr_get_rcvfd(3), rmr_get_meid(3), rmr_get_trace(3),
3073 rmr_get_trlen(3), rmr_init(3), rmr_init_trace(3),
3074 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
3075 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
3076 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
3077 rmr_ring_free(3), rmr_str2meid(3), rmr_str2xact(3),
3078 rmr_wh_open(3), rmr_wh_send_msg(3)
3082 --------------------------------------------------------------------------------------------
3087 --------------------------------------------------------------------------------------------
3092 #include <rmr/rmr.h>
3093 #include <rmr/rmr_logging.h>
3094 void rmr_set_vlevel( int new_level )
3099 --------------------------------------------------------------------------------------------
3101 The rmr_set_vlevel allows the user programme to set the
3102 verbosity level which is used to determine the messages RMR
3103 writes to standard error. The new_vlevel value must be one of
3104 the following constants which have the indicated meanings:
3109 Turns off all message writing. This includes the stats and
3110 debugging messages generated by the route collector thread
3111 which are normally affected only by the externally managed
3112 verbose level file (and related environment variable).
3117 Write only messages of critical importance. From the point
3118 of view of RMR, when a critical proper behaviour of the
3119 library cannot be expected or guaranteed.
3123 Include error messages in the output. An error is an event
3124 from which RMR has no means to recover. Continued proper
3125 execution is likely except where the affected connection
3126 and/or component mentioned in the error is concerned.
3130 Include warning messages in the output. A warning
3131 indicates an event which is not considered to be normal,
3132 but is expected and continued acceptable behaviour of the
3137 Include informational messagees in the output.
3138 Informational messages include some diagnostic information
3139 which explain the activities of RMR.
3143 Include all debugging messages in the output. Debugging
3144 must have also been enabled during the build as a
3145 precaution to accidentally enabling this level of output
3146 as it can grossly affect performance.
3149 Generally RMR does not write messages to the standard error
3150 device from *critical path* functions, therefore it is
3151 usually not harmful to enable a verbosity level of either
3152 RMR_VL_CRIT or RMR_VL_ERR.
3154 Messages written from the route table collection thread are
3155 still governed by the value placed into the verbose level
3156 control file (see the man page for rmr_init()); those
3157 messages are affected only when logging is completely
3158 disabled by passing RMR_VL_OFF to this function.
3160 The verbosity level can also be set via an environment
3161 variable prior to the start of the RMR based application. The
3162 environment variable is read only during initialisation; if
3163 the programme must change the value during execution, this
3164 function must be used. The default value, if this function is
3165 never called, and the environment variable is not present, is
3169 --------------------------------------------------------------------------------------------
3175 --------------------------------------------------------------------------------------------
3180 --------------------------------------------------------------------------------------------
3185 #include <rmr/rmr.h>
3186 int rmr_str2meid( rmr_mbuf_t* mbuf, unsigned char* src, int len )
3191 --------------------------------------------------------------------------------------------
3193 The rmr_str2meid function will copy the string pointed to by
3194 src to the managed entity ID (meid) field in the given
3195 message. The field is a fixed length, gated by the constant
3196 RMR_MAX_MEID and if string length is larger than this value,
3197 then **nothing** will be copied. (Note, this differs slightly
3198 from the behaviour of the lrmr_bytes2meid() function.)
3201 --------------------------------------------------------------------------------------------
3203 On success, the value RMR_OK is returned. If the string
3204 cannot be copied to the message, the return value will be one
3205 of the errors listed below.
3208 --------------------------------------------------------------------------------------------
3210 If the return value is not RMR_OK, then it will be set to one
3211 of the values below.
3217 The message, or an internal portion of the message, was
3218 corrupted or the pointer was invalid.
3223 The length passed in was larger than the maximum length of
3224 the field; only a portion of the source bytes were copied.
3228 --------------------------------------------------------------------------------------------
3232 --------------------------------------------------------------------------------------------
3234 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
3235 rmr_get_meid(3), rmr_get_rcvfd(3), rmr_payload_size(3),
3236 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
3237 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
3238 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
3239 rmr_bytes2meid(3), rmr_wh_open(3), rmr_wh_send_msg(3)
3243 --------------------------------------------------------------------------------------------
3248 --------------------------------------------------------------------------------------------
3253 #include <rmr/rmr.h>
3254 int rmr_str2xact( rmr_mbuf_t* mbuf, unsigned char* src, int len )
3259 --------------------------------------------------------------------------------------------
3261 The rmr_str2xact function will copy the string pointed to by
3262 src to the transaction ID (xaction) field in the given
3263 message. The field is a fixed length, gated by the constant
3264 RMR_MAX_XID and if string length is larger than this value,
3265 then **nothing** will be copied. (Note, this differs slightly
3266 from the behaviour of the lrmr_bytes2xact() function.)
3270 --------------------------------------------------------------------------------------------
3272 On success, the value RMR_OK is returned. If the string
3273 cannot be copied to the message, the return value will be
3274 one of the errors listed below.
3277 --------------------------------------------------------------------------------------------
3279 If the return value is not RMR_OK, then it will be set to
3280 one of the values below.
3285 The message, or an internal portion of the message, was
3286 corrupted or the pointer was invalid.
3291 The length passed in was larger than the maximum length of
3292 the field; only a portion of the source bytes were copied.
3296 --------------------------------------------------------------------------------------------
3300 --------------------------------------------------------------------------------------------
3302 rmr_alloc_msg(3), rmr_bytes2meid(3), rmr_bytes2xact(3),
3303 rmr_call(3), rmr_free_msg(3), rmr_get_meid(3),
3304 rmr_get_rcvfd(3), rmr_get_xact(3), rmr_payload_size(3),
3305 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
3306 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
3307 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
3308 rmr_str2meid(3), rmr_wh_open(3), rmr_wh_send_msg(3)
3312 --------------------------------------------------------------------------------------------
3314 RMR support functions
3317 --------------------------------------------------------------------------------------------
3322 #include <rmr/rmr.h>
3323 #include <rmr/ring_inline.h>
3324 char* rmr_fib( char* fname );
3325 int rmr_has_str( char const* buf, char const* str, char sep, int max );
3326 int rmr_tokenise( char* buf, char** tokens, int max, char sep );
3327 void* rmr_mk_ring( int size );
3328 void rmr_ring_free( void* vr );
3329 static inline void* rmr_ring_extract( void* vr )
3330 static inline int rmr_ring_insert( void* vr, void* new_data )
3335 --------------------------------------------------------------------------------------------
3337 These functions support the RMR library, and are made
3338 available to user applications as some (e.g. route table
3339 generators) might need and/or want to make use of them. The
3340 rmr_fib function accepts a file name and reads the entire
3341 file into a single buffer. The intent is to provide an easy
3342 way to load a static route table without a lot of buffered
3345 The rmr_has_str function accepts a *buffer* containing a set
3346 of delimited tokens (e.g. foo,bar,goo) and returns true if
3347 the target string, *str,* matches one of the tokens. The
3348 *sep* parameter provides the separation character in the
3349 buffer (e.g a comma) and *max* indicates the maximum number
3350 of tokens to split the buffer into before checking.
3352 The rmr_tokenise function is a simple tokeniser which splits
3353 *buf* into tokens at each occurrence of *sep*. Multiple
3354 occurrences of the separator character (e.g. a,,b) result in
3355 a nil token. Pointers to the tokens are placed into the
3356 *tokens* array provided by the caller which is assumed to
3357 have at least enough space for *max* entries.
3359 The rmr_mk_ring function creates a buffer ring with *size*
3362 The rmr_ring_free function accepts a pointer to a ring
3363 context and frees the associated memory.
3365 The rmr_ring_insert and rmr_ring_extract functions are
3366 provided as static inline functions via the
3367 *rmr/ring_inline.h* header file. These functions both accept
3368 the ring *context* returned by mk_ring, and either insert a
3369 pointer at the next available slot (tail) or extract the data
3373 --------------------------------------------------------------------------------------------
3375 The following are the return values for each of these
3378 The rmr_fib function returns a pointer to the buffer
3379 containing the contents of the file. The buffer is terminated
3380 with a single nil character (0) making it a legitimate C
3381 string. If the file was empty or nonexistent, a buffer with
3382 an immediate nil character. If it is important to the calling
3383 programme to know if the file was empty or did not exist, the
3384 caller should use the system stat function call to make that
3387 The rmr_has_str function returns 1 if *buf* contains the
3388 token referenced by &ita and false (0) if it does not. On
3389 error, a -1 value is returned and errno is set accordingly.
3391 The rmr_tokenise function returns the actual number of token
3392 pointers placed into *tokens*
3394 The rmr_mk_ring function returns a void pointer which is the
3395 *context* for the ring.
3397 The rmr_ring_insert function returns 1 if the data was
3398 successfully inserted into the ring, and 0 if the ring is
3399 full and the pointer could not be deposited.
3401 The rmr_ring_extract will return the data which is at the
3402 head of the ring, or NULL if the ring is empty.
3405 --------------------------------------------------------------------------------------------
3407 Not many of these functions set the value in errno, however
3408 the value may be one of the following:
3413 Parameter(s) passed to the function were not valid.
3417 --------------------------------------------------------------------------------------------
3421 --------------------------------------------------------------------------------------------
3423 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
3424 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
3425 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
3429 --------------------------------------------------------------------------------------------
3434 --------------------------------------------------------------------------------------------
3439 #include <rmr/rmr.h>
3440 rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to );
3445 --------------------------------------------------------------------------------------------
3447 The rmr_torcv_msg function will pause for *ms_to*
3448 milliseconds waiting for a message to arrive. If a message
3449 arrives before the timeout expires the message buffer
3450 returned will have a status of RMR_OK and the payload will
3451 contain the data received. If the timeout expires before the
3452 message is received, the status will have the value
3453 RMR_ERR_TIMEOUT. When a received message is returned the
3454 message buffer will also contain the message type and length
3455 set by the sender. If messages were queued while waiting for
3456 the response to a previous invocation of rmr_call, the oldest
3457 message is removed from the queue and returned without delay.
3459 The *vctx* pointer is the pointer returned by the rmr_init
3460 function. *Old_msg* is a pointer to a previously used message
3461 buffer or NULL. The ability to reuse message buffers helps to
3462 avoid alloc/free cycles in the user application. When no
3463 buffer is available to supply, the receive function will
3467 --------------------------------------------------------------------------------------------
3469 The function returns a pointer to the rmr_mbuf_t structure
3470 which references the message information (state, length,
3471 payload), or a nil pointer in the case of an extreme error.
3474 --------------------------------------------------------------------------------------------
3476 The *state* field in the message buffer will be one of the
3483 The message buffer (payload) references the received data.
3488 The first call to this function must initialise an
3489 underlying system notification mechanism. On failure, this
3490 error is returned and errno will have the system error
3491 status set. If this function fails to intialise, the poll
3492 mechansim, it is likely that message receives will never
3498 The timeout expired before a complete message was
3499 received. All other fields in the message buffer are not
3505 A message was received, but it had no payload. All other
3506 fields in the message buffer are not valid.
3513 Parameter(s) passed to the function were not valid.
3518 The underlying message transport is unable to process the
3524 The underlying message transport is unable to process the
3530 The underlying message transport is unable to process the
3536 The underlying message transport is unable to process the
3542 The underlying message transport is unable to process the
3548 The underlying message transport is unable to process the
3554 The underlying message transport is unable to process the
3559 --------------------------------------------------------------------------------------------
3563 --------------------------------------------------------------------------------------------
3565 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
3566 rmr_get_rcvfd(3), rmr_init(3), rmr_payload_size(3),
3567 rmr_rcv_msg(3), rmr_send_msg(3), rmr_rcv_specific(3),
3568 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
3569 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
3573 --------------------------------------------------------------------------------------------
3578 --------------------------------------------------------------------------------------------
3583 #include <rmr/rmr.h>
3584 int rmr_trace_ref( rmr_mbuf_t* mbuf, int* sizeptr )
3589 --------------------------------------------------------------------------------------------
3591 The rmr_trace_ref function returns a pointer to the trace
3592 area in the message, and optionally populates the user
3593 programme supplied size integer with the trace area size, if
3594 *sizeptr* is not nil.
3597 --------------------------------------------------------------------------------------------
3599 On success, a void pointer to the trace area of the message
3600 is returned. A nil pointer is returned if the message has no
3601 trace data area allocated, or if the message itself is
3605 --------------------------------------------------------------------------------------------
3607 rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3),
3608 rmr_bytes2meid(3), rmr_call(3), rmr_free_msg(3),
3609 rmr_get_rcvfd(3), rmr_get_trlen(3), rmr_init(3),
3610 rmr_init_trace(3), rmr_payload_size(3), rmr_send_msg(3),
3611 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
3612 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
3613 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
3614 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3),
3619 --------------------------------------------------------------------------------------------
3624 --------------------------------------------------------------------------------------------
3629 #include <rmr/rmr.h>
3630 rmr_mbuf_t* rmr_tralloc_msg( void* vctx, int size,
3631 int trace_size, unsigned const char *tr_data );
3636 --------------------------------------------------------------------------------------------
3638 The rmr_tralloc_msg function is used to allocate a buffer
3639 which the user programme can write into and then send through
3640 the library. The buffer is allocated such that sending it
3641 requires no additional copying from the buffer as it passes
3642 through the underlying transport mechanism.
3644 The *size* parameter is used to set the payload length in the
3645 message. If it is 0, then the default size supplied on the
3646 *rmr_init* call will be used. In addition to allocating the
3647 payload, a space in the buffer is reserved for *trace* data
3648 (tr_size bytes), and the bytes pointed to by *tr_data* are
3649 copied into that portion of the message. The *vctx* parameter
3650 is the void context pointer that was returned by the
3651 *rmr_init* function.
3653 The pointer to the message buffer returned is a structure
3654 which has some user application visible fields; the structure
3655 is described in rmr.h, and is illustrated below.
3664 unsigned char* payload;
3665 unsigned char* xaction;
3674 Is the current buffer state. Following a call to
3675 rmr_send_msg the state indicates whether the buffer was
3676 successfully sent which determines exactly what the
3677 payload points to. If the send failed, the payload
3678 referenced by the buffer is the message that failed to
3679 send (allowing the application to attempt a
3680 retransmission). When the state is a_OK the buffer
3681 represents an empty buffer that the application may fill
3682 in in preparation to send.
3687 When sending a message, the application is expected to set
3688 this field to the appropriate message type value (as
3689 determined by the user programme). Upon send this value
3690 determines how the a library will route the message. For a
3691 buffer which has been received, this field will contain
3692 the message type that was set by the sending application.
3697 The application using a buffer to send a message is
3698 expected to set the length value to the actual number of
3699 bytes that it placed into the message. This is likely less
3700 than the total number of bytes that the message can carry.
3701 For a message buffer that is passed to the application as
3702 the result of a receive call, this will be the value that
3703 the sending application supplied and should indicate the
3704 number of bytes in the payload which are valid.
3709 The payload is a pointer to the actual received data. The
3710 user programme may read and write from/to the memory
3711 referenced by the payload up until the point in time that
3712 the buffer is used on a rmr_send, rmr_call or rmr_reply
3713 function call. Once the buffer has been passed back to a a
3714 library function the user programme should **NOT** make
3715 use of the payload pointer.
3720 The *xaction* field is a pointer to a fixed sized area in
3721 the message into which the user may write a transaction
3722 ID. The ID is optional with the exception of when the user
3723 application uses the rmr_call function to send a message
3724 and wait for the reply; the underlying processing expects
3725 that the matching reply message will also contain the same
3726 data in the *xaction* field.
3730 --------------------------------------------------------------------------------------------
3732 The function returns a pointer to a rmr_mbuf structure, or
3736 --------------------------------------------------------------------------------------------
3742 Unable to allocate memory.
3746 --------------------------------------------------------------------------------------------
3748 rmr_alloc_msg(3), rmr_mbuf(3) rmr_call(3), rmr_free_msg(3),
3749 rmr_init(3), rmr_init_trace(3), rmr_get_trace(3),
3750 rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
3751 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
3752 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
3753 rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)
3757 --------------------------------------------------------------------------------------------
3762 --------------------------------------------------------------------------------------------
3767 #include <rmr/rmr.h>
3768 rmr_mbuf_t* rmr_wh_call( void* vctx, rmr_whid_t whid, rmr_mbuf_t* msg, int call_id, int max_wait )
3773 --------------------------------------------------------------------------------------------
3775 The rmr_wh_call function accepts a message buffer (msg) from
3776 the user application and attempts to send it using the
3777 wormhole ID provided (whid). If the send is successful, the
3778 call will block until either a response message is received,
3779 or the max_wait number of milliseconds has passed. In order
3780 for the response to be recognised as a response, the remote
3781 process **must** use rmr_rts_msg() to send their response.
3783 Like *rmr_wh_send_msg,* this function attempts to send the
3784 message directly to a process at the other end of a wormhole
3785 which was created with *rmr_wh_open().* When sending message
3786 via wormholes, the normal RMR routing based on message type
3787 is ignored, and the caller may leave the message type
3788 unspecified in the message buffer (unless it is needed by the
3789 receiving process). The call_id parameter is a number in the
3790 range of 2 through 255 and is used to identify the calling
3791 thread in order to properly match a response message when it
3792 arrives. Providing this value, and ensuring the proper
3793 uniqueness, is the responsibility of the user application and
3794 as such the ability to use the rmr_wh_call() function from
3795 potentially non-threaded concurrent applications (such as
3796 Go's goroutines) is possible.
3799 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3801 The send operations in RMR will retry *soft* send failures
3802 until one of three conditions occurs:
3808 The message is sent without error
3813 The underlying transport reports a *hard* failure
3818 The maximum number of retry loops has been attempted
3821 A retry loop consists of approximately 1000 send attempts
3822 **without** any intervening calls to *sleep()* or *usleep().*
3823 The number of retry loops defaults to 1, thus a maximum of
3824 1000 send attempts is performed before returning to the user
3825 application. This value can be set at any point after RMR
3826 initialisation using the *rmr_set_stimeout()* function
3827 allowing the user application to completely disable retires
3828 (set to 0), or to increase the number of retry loops.
3830 Transport Level Blocking
3831 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3833 The underlying transport mechanism used to send messages is
3834 configured in *non-blocking* mode. This means that if a
3835 message cannot be sent immediately the transport mechanism
3836 will **not** pause with the assumption that the inability to
3837 send will clear quickly (within a few milliseconds). This
3838 means that when the retry loop is completely disabled (set to
3839 0), that the failure to accept a message for sending by the
3840 underlying mechanisms (software or hardware) will be reported
3841 immediately to the user application.
3843 It should be noted that depending on the underlying transport
3844 mechanism being used, it is extremely likely that retry
3845 conditions will happen during normal operations. These are
3846 completely out of RMR's control, and there is nothing that
3847 RMR can do to avoid or mitigate these other than by allowing
3848 RMR to retry the send operation, and even then it is possible
3849 (e.g., during connection reattempts), that a single retry
3850 loop is not enough to guarantee a successful send.
3853 --------------------------------------------------------------------------------------------
3855 On success, new message buffer, with the payload containing
3856 the response from the remote endpoint is returned. The state
3857 in this buffer will reflect the overall send operation state
3858 and should be RMR_OK.
3860 If a message is returned with a state which is anything other
3861 than RMR_OK, the indication is that the send was not
3862 successful. The user application must check the state and
3863 determine the course of action. If the return value is NULL,
3864 no message, the indication is that there was no response
3865 received within the timeout (max_wait) period of time.
3868 --------------------------------------------------------------------------------------------
3870 The following values may be passed back in the *state* field
3871 of the returned message buffer.
3877 The wormhole ID passed in was not associated with an open
3878 wormhole, or was out of range for a valid ID.
3882 No wormholes exist, further attempt to validate the ID are
3887 The message buffer pointer did not refer to a valid
3892 The header in the message buffer was not valid or
3897 --------------------------------------------------------------------------------------------
3899 The following is a simple example of how the a wormhole is
3900 created (rmr_wh_open) and then how rmr_wh_send_msg function
3901 is used to send messages. Some error checking is omitted for
3907 #include <rmr/rmr.h> // system headers omitted for clarity
3909 rmr_whid_t whid = -1; // wormhole id for sending
3910 void* mrc; //msg router context
3912 rmr_mbuf_t* sbuf; // send buffer
3914 int norm_msg_size = 1500; // most messages fit in this size
3915 mrc = rmr_init( "43086", norm_msg_size, RMRFL_NONE );
3917 fprintf( stderr, "[FAIL] unable to initialise RMR environment\\n" );
3920 while( ! rmr_ready( mrc ) ) { // wait for routing table info
3923 sbuf = rmr_alloc_msg( mrc, 2048 );
3926 whid = rmr_wh_open( mrc, "localhost:6123" ); // open fails if endpoint refuses conn
3927 if( RMR_WH_CONNECTED( wh ) ) {
3928 snprintf( sbuf->payload, 1024, "periodic update from sender: %d", count++ );
3929 sbuf->len = strlen( sbuf->payload );
3930 sbuf = rmr_wh_call( mrc, whid, sbuf, 1000 ); // expect a response in 1s or less
3931 if( sbuf != NULL && sbuf->state = RMR_OK ) {
3932 sprintf( stderr, "response: %s\\n", sbuf->payload ); // assume they sent a string
3934 sprintf( stderr, "response not received, or send error\\n" );
3945 --------------------------------------------------------------------------------------------
3947 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
3948 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
3949 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
3950 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
3951 rmr_set_stimeout(3), rmr_wh_open(3), rmr_wh_close(3),
3956 --------------------------------------------------------------------------------------------
3961 --------------------------------------------------------------------------------------------
3966 #include <rmr/rmr.h>
3967 void rmr_close( void* vctx, rmr_whid_t whid )
3972 --------------------------------------------------------------------------------------------
3974 The rmr_wh_close function closes the wormhole associated with
3975 the wormhole id passed in. Future calls to rmr_wh_send_msg
3976 with this ID will fail.
3978 The underlying TCP connection to the remote endpoint is
3979 **not** closed as this session may be required for regularly
3980 routed messages (messages routed based on message type).
3981 There is no way to force a TCP session to be closed at this
3985 --------------------------------------------------------------------------------------------
3987 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
3988 rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3),
3989 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
3990 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
3991 rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_open(3),
3996 --------------------------------------------------------------------------------------------
4001 --------------------------------------------------------------------------------------------
4006 #include <rmr/rmr.h>
4007 void* rmr_wh_open( void* vctx, char* target )
4012 --------------------------------------------------------------------------------------------
4014 The rmr_wh_open function creates a direct link for sending, a
4015 wormhole, to another RMR based process. Sending messages
4016 through a wormhole requires that the connection be
4017 established overtly by the user application (via this
4018 function), and that the ID returned by rmr_wh_open be passed
4019 to the rmr_wh_send_msg function.
4021 *Target* is the *name* or *IP-address* combination of the
4022 processess that the wormhole should be connected to. *Vctx*
4023 is the RMR void context pointer that was returned by the
4026 When invoked, this function immediatly attempts to connect to
4027 the target process. If the connection cannot be established,
4028 an error is returned to the caller, and no direct messages
4029 can be sent to the target. Once a wormhole is connected, the
4030 underlying transport mechanism (e.g. NNG) will provide
4031 reconnects should the connection be lost, however the
4032 handling of messages sent when a connection is broken is
4033 undetermined as each underlying transport mechanism may
4034 handle buffering and retries differently.
4037 --------------------------------------------------------------------------------------------
4039 The rmr_wh_open function returns a type rmr_whid_t which must
4040 be passed to the rmr_wh_send_msg function when sending a
4041 message. The id may also be tested to determine success or
4042 failure of the connection by using the RMR_WH_CONNECTED macro
4043 and passing the ID as the parameter; a result of 1 indicates
4044 that the connection was esablished and that the ID is valid.
4047 --------------------------------------------------------------------------------------------
4049 The following error values are specifically set by this RMR
4050 function. In some cases the error message of a system call is
4051 propagated up, and thus this list might be incomplete.
4056 A parameter passed was not valid.
4060 The user application does not have the ability to
4061 establish a wormhole to the indicated target (or maybe any
4066 The connection was refused.
4070 --------------------------------------------------------------------------------------------
4077 rmc = rmr_init( "43086", 4096, 0 ); // init context
4078 wh = rmr_wh_open( rmc, "localhost:6123" );
4079 if( !RMR_WH_CONNECTED( wh ) ) {
4080 fprintf( stderr, "unable to connect wormhole: %s\\n",
4081 strerror( errno ) );
4087 --------------------------------------------------------------------------------------------
4089 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
4090 rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3),
4091 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
4092 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
4093 rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_close(3),
4094 rmr_wh_send_msg(3), rmr_wh_state(3)
4098 --------------------------------------------------------------------------------------------
4103 --------------------------------------------------------------------------------------------
4108 #include <rmr/rmr.h>
4109 rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t id, rmr_mbuf_t* msg );
4114 --------------------------------------------------------------------------------------------
4116 The rmr_wh_send_msg function accepts a message buffer from
4117 the user application and attempts to send it using the
4118 wormhole ID provided (id). Unlike *rmr_send_msg,* this
4119 function attempts to send the message directly to a process
4120 at the other end of a wormhole which was created with
4121 *rmr_wh_open().* When sending message via wormholes, the
4122 normal RMR routing based on message type is ignored, and the
4123 caller may leave the message type unspecified in the message
4124 buffer (unless it is needed by the receiving process).
4126 The message buffer (msg) used to send is the same format as
4127 used for regular RMR send and reply to sender operations,
4128 thus any buffer allocated by these means, or calls to
4129 *rmr_rcv_msg()* can be passed to this function.
4132 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4134 The send operations in RMR will retry *soft* send failures
4135 until one of three conditions occurs:
4141 The message is sent without error
4146 The underlying transport reports a *hard* failure
4151 The maximum number of retry loops has been attempted
4154 A retry loop consists of approximately 1000 send attempts
4155 **without** any intervening calls to *sleep()* or *usleep().*
4156 The number of retry loops defaults to 1, thus a maximum of
4157 1000 send attempts is performed before returning to the user
4158 application. This value can be set at any point after RMR
4159 initialisation using the *rmr_set_stimeout()* function
4160 allowing the user application to completely disable retires
4161 (set to 0), or to increase the number of retry loops.
4163 Transport Level Blocking
4164 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4166 The underlying transport mechanism used to send messages is
4167 configured in *non-blocking* mode. This means that if a
4168 message cannot be sent immediately the transport mechanism
4169 will **not** pause with the assumption that the inability to
4170 send will clear quickly (within a few milliseconds). This
4171 means that when the retry loop is completely disabled (set to
4172 0), that the failure to accept a message for sending by the
4173 underlying mechanisms (software or hardware) will be reported
4174 immediately to the user application.
4176 It should be noted that depending on the underlying transport
4177 mechanism being used, it is extremely likely that retry
4178 conditions will happen during normal operations. These are
4179 completely out of RMR's control, and there is nothing that
4180 RMR can do to avoid or mitigate these other than by allowing
4181 RMR to retry the send operation, and even then it is possible
4182 (e.g., during connection reattempts), that a single retry
4183 loop is not enough to guarantee a successful send.
4186 --------------------------------------------------------------------------------------------
4188 On success, a new message buffer, with an empty payload, is
4189 returned for the application to use for the next send. The
4190 state in this buffer will reflect the overall send operation
4191 state and should be RMR_OK.
4193 If the state in the returned buffer is anything other than
4194 RMR_OK, the user application may need to attempt a
4195 retransmission of the message, or take other action depending
4196 on the setting of errno as described below.
4198 In the event of extreme failure, a nil pointer is returned.
4199 In this case the value of errno might be of some use, for
4200 documentation, but there will be little that the user
4201 application can do other than to move on.
4204 --------------------------------------------------------------------------------------------
4206 The following values may be passed back in the *state* field
4207 of the returned message buffer.
4213 The wormhole ID passed in was not associated with an open
4214 wormhole, or was out of range for a valid ID.
4218 No wormholes exist, further attempt to validate the ID are
4223 The message buffer pointer did not refer to a valid
4228 The header in the message buffer was not valid or
4232 The following values may be assigned to errno on failure.
4237 Parameter(s) passed to the function were not valid, or the
4238 underlying message processing environment was unable to
4239 interpret the message.
4244 The header information in the message buffer was invalid.
4249 No known endpoint for the message could be found.
4254 The underlying transport refused to accept the message
4255 because of a size value issue (message was not attempted
4261 The message referenced by the message buffer is corrupt
4262 (nil pointer or bad internal length).
4267 Internal RMR error; information provided to the message
4268 transport environment was not valid.
4273 Sending was not supported by the underlying message
4279 The device is not in a state that can accept the message.
4284 The device is not able to accept a message for sending.
4285 The user application should attempt to resend.
4290 The operation was interrupted by delivery of a signal
4291 before the message was sent.
4296 The underlying message environment timed out during the
4302 The underlying message environment is in a shutdown state.
4306 --------------------------------------------------------------------------------------------
4308 The following is a simple example of how the a wormhole is
4309 created (rmr_wh_open) and then how rmr_wh_send_msg function
4310 is used to send messages. Some error checking is omitted for
4316 #include <rmr/rmr.h> // system headers omitted for clarity
4318 rmr_whid_t whid = -1; // wormhole id for sending
4319 void* mrc; //msg router context
4321 rmr_mbuf_t* sbuf; // send buffer
4323 int norm_msg_size = 1500; // most msg fit in this size
4324 mrc = rmr_init( "43086", norm_msg_size, RMRFL_NONE );
4326 fprintf( stderr, "[FAIL] unable to initialise RMR environment\\n" );
4329 while( ! rmr_ready( mrc ) ) { // wait for routing table info
4332 sbuf = rmr_alloc_msg( mrc, 2048 );
4335 whid = rmr_wh_open( mrc, "localhost:6123" ); // open fails if endpoint refuses conn
4336 if( RMR_WH_CONNECTED( wh ) ) {
4337 snprintf( sbuf->payload, 1024, "periodic update from sender: %d", count++ );
4338 sbuf->len = strlen( sbuf->payload );
4339 sbuf = rmr_wh_send_msg( mrc, whid, sbuf );
4349 --------------------------------------------------------------------------------------------
4351 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
4352 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
4353 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
4354 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
4355 rmr_set_stimeout(3), rmr_wh_open(3), rmr_wh_close(3),
4360 --------------------------------------------------------------------------------------------
4365 --------------------------------------------------------------------------------------------
4370 #include <rmr/rmr.h>
4371 int rmr_wh_state( void* vctx, rmr_whid_t whid )
4376 --------------------------------------------------------------------------------------------
4378 The rmr_wh_state function will return the current state of
4379 the connection associated with the given wormhole (whid). The
4380 return value indicates whether the connection is open
4381 (RMR_OK), or closed (any other return value).
4383 When using some transport mechanisms (e.g. NNG), it may not
4384 be possible for RMR to know the actual state and the
4385 connection may always be reported as "open."
4388 --------------------------------------------------------------------------------------------
4390 The following values are potential return values.
4396 The wormhole ID is valid and the connection is "open."
4401 THe wormhole ID passed into the function was not valid.
4406 The wormhole is not open (not connected).
4411 The context passed to the function was nil or invalid.
4416 Wormholes have not been initialised (no wormhole open call
4422 --------------------------------------------------------------------------------------------
4424 rmr_wh_open(3), rmr_wh_send_msg(3), rmr_wh_close(3)