2 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
3 .. SPDX-License-Identifier: CC-BY-4.0
4 .. CAUTION: this document is generated from source in doc/src/rtd.
5 .. To make changes edit the source and recompile the document.
6 .. Do NOT make changes directly to .rst or .md files.
10 ============================================================================================
12 The RIC Message Router (RMR) is a library which applications
13 use to send and receive messages where the message routing,
14 endpoint selection, is based on the message type rather than
15 on traditional DNS names or IP addresses. Because the user
16 documentation for RMR is a collection of UNIX manpages
17 (included in the development package, and available via the
18 man command when installed), there is no separate "User's
19 Guide." To provide something for the document scrapers to
20 find, this is a collection of the RMR manual pages formatted
21 directly from their source which might be a bit ragged when
22 combined into a single markup document. Read the manual pages
28 --------------------------------------------------------------------------------------------
33 --------------------------------------------------------------------------------------------
39 rmr_mbuf_t* rmr_alloc_msg( void* ctx, int size );
44 --------------------------------------------------------------------------------------------
46 The rmr_alloc_msg function is used to allocate a buffer which
47 the user programme can write into and then send through the
48 RMR library. The buffer is allocated such that sending it
49 requires no additional copying out of the buffer. If the
50 value passed in size is 0, then the default size supplied on
51 the *rmr_init* call will be used. The *ctx* parameter is the
52 void context pointer that was returned by the *rmr_init*
55 The pointer to the message buffer returned is a structure
56 which has some user application visible fields; the structure
57 is described in rmr.h, and is illustrated below.
66 unsigned char* payload;
67 unsigned char* xaction;
78 Is the current buffer state. Following a call to
79 rmr_send_msg the state indicates whether the buffer was
80 successfully sent which determines exactly what the
81 payload points to. If the send failed, the payload
82 referenced by the buffer is the message that failed to
83 send (allowing the application to attempt a
84 retransmission). When the state is RMR_OK the buffer
85 represents an empty buffer that the application may fill
86 in in preparation to send.
91 When sending a message, the application is expected to set
92 this field to the appropriate message type value (as
93 determined by the user programme). Upon send this value
94 determines how the RMR library will route the message. For
95 a buffer which has been received, this field will contain
96 the message type that was set by the sending application.
101 The application using a buffer to send a message is
102 expected to set the length value to the actual number of
103 bytes that it placed into the message. This is likely less
104 than the total number of bytes that the message can carry.
105 For a message buffer that is passed to the application as
106 the result of a receive call, this will be the value that
107 the sending application supplied and should indicate the
108 number of bytes in the payload which are valid.
113 The payload is a pointer to the actual received data. The
114 user programme may read and write from/to the memory
115 referenced by the payload up until the point in time that
116 the buffer is used on a rmr_send, rmr_call or rmr_reply
117 function call. Once the buffer has been passed back to a
118 RMR library function the user programme should **NOT**
119 make use of the payload pointer.
124 The *xaction* field is a pointer to a fixed sized area in
125 the message into which the user may write a transaction
126 ID. The ID is optional with the exception of when the user
127 application uses the rmr_call function to send a message
128 and wait for the reply; the underlying RMR processing
129 expects that the matching reply message will also contain
130 the same data in the *xaction* field.
136 This value is the subscription ID. It, in combination with
137 the message type is used by rmr to determine the target
138 endpoint when sending a message. If the application to
139 application protocol does not warrant the use of a
140 subscription ID, the RMR constant RMR_VOID_SUBID should be
141 placed in this field. When an application is forwarding or
142 returning a buffer to the sender, it is the application's
143 responsibility to set/reset this value.
148 For C applications making use of RMR, the state of a
149 transport based failure will often be available via errno.
150 However, some wrapper environments may not have direct access
151 to the C-lib errno value. RMR send and receive operations
152 will place the current value of errno into this field which
153 should make it available to wrapper functions. User
154 applications are strongly cautioned against relying on the
155 value of errno as some transport mechanisms may not set this
156 value on all calls. This value should also be ignored any
157 time the message status is RMR_OK.
161 --------------------------------------------------------------------------------------------
163 The function returns a pointer to a rmr_mbuf structure, or NULL
167 --------------------------------------------------------------------------------------------
173 Unable to allocate memory.
177 --------------------------------------------------------------------------------------------
179 rmr_tralloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
180 rmr_init_trace(3), rmr_get_trace(3), rmr_get_trlen(3),
181 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
182 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), rmr_fib(3),
183 rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
184 rmr_ring_free(3), rmr_set_trace(3)
188 --------------------------------------------------------------------------------------------
193 --------------------------------------------------------------------------------------------
199 int rmr_bytes2meid( rmr_mbuf_t* mbuf, unsigned char* src, int len )
204 --------------------------------------------------------------------------------------------
206 The rmr_bytes2meid function will copy up to *len* butes from
207 *src* to the managed equipment ID (meid) field in the
208 message. The field is a fixed length, gated by the constant
209 RMR_MAX_MEID and if len is larger than this value, only
210 RMR_MAX_MEID bytes will actually be copied.
213 --------------------------------------------------------------------------------------------
215 On success, the actual number of bytes copied is returned, or
216 -1 to indicate a hard error. If the length is less than 0, or
217 not the same as length passed in, errno is set to one of the
218 errors described in the *Errors* section.
221 --------------------------------------------------------------------------------------------
223 If the returned length does not match the length passed in,
224 errno will be set to one of the following constants with the
225 meaning listed below.
231 The message, or an internal portion of the message, was
232 corrupted or the pointer was invalid.
237 The length passed in was larger than the maximum length of
238 the field; only a portion of the source bytes were copied.
242 --------------------------------------------------------------------------------------------
246 --------------------------------------------------------------------------------------------
248 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_call(3),
249 rmr_free_msg(3), rmr_get_rcvfd(3), rmr_get_meid(3),
250 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
251 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
252 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
253 rmr_ring_free(3), rmr_str2meid(3), rmr_str2xact(3),
254 rmr_wh_open(3), rmr_wh_send_msg(3)
258 --------------------------------------------------------------------------------------------
263 --------------------------------------------------------------------------------------------
269 void rmr_bytes2payload( rmr_mbuf_t* mbuf, unsigned char* src, int len )
274 --------------------------------------------------------------------------------------------
276 This is a convenience function as some wrapper languages
277 might not have the ability to directly copy into the payload
278 buffer. The bytes from *src* for the length given are copied
279 to the payload. It is the caller's responsibility to ensure
280 that the payload is large enough. Upon successfully copy, the
281 len field in the message buffer is updated to reflect the
282 number of bytes copied.
284 There is little error checking, and no error reporting.
287 --------------------------------------------------------------------------------------------
292 --------------------------------------------------------------------------------------------
296 --------------------------------------------------------------------------------------------
298 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2payload(3),
299 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
300 rmr_get_meid(3), rmr_payload_size(3), rmr_send_msg(3),
301 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
302 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
303 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
304 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
308 --------------------------------------------------------------------------------------------
313 --------------------------------------------------------------------------------------------
319 int rmr_bytes2xact( rmr_mbuf_t* mbuf, unsigned char* src, int len )
324 --------------------------------------------------------------------------------------------
326 The rmr_bytes2xact function will copy up to *len* butes from
327 *src* to the transaction ID (xaction) field in the message.
328 The field is a fixed length, gated by the constant
329 RMR_MAX_XID and if len is larger than this value, only
330 RMR_MAX_XID bytes will actually be copied.
334 --------------------------------------------------------------------------------------------
336 On success, the actual number of bytes copied is returned,
337 or -1 to indicate a hard error. If the length is less than
338 0, or not the same as length passed in, errno is set to
339 one of the errors described in the *Errors* section.
342 --------------------------------------------------------------------------------------------
344 If the returned length does not match the length passed
345 in, errno will be set to one of the following constants
346 with the meaning listed below.
351 The message, or an internal portion of the message, was
352 corrupted or the pointer was invalid.
357 The length passed in was larger than the maximum length of
358 the field; only a portion of the source bytes were copied.
362 --------------------------------------------------------------------------------------------
366 --------------------------------------------------------------------------------------------
368 rmr_alloc_msg(3), rmr_bytes2meid(3), rmr_call(3),
369 rmr_free_msg(3), rmr_get_meid(3), rmr_get_rcvfd(3),
370 rmr_get_xact(3), rmr_payload_size(3), rmr_send_msg(3),
371 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
372 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
373 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
374 rmr_wh_open(3), rmr_wh_send_msg(3)
378 --------------------------------------------------------------------------------------------
383 --------------------------------------------------------------------------------------------
389 extern rmr_mbuf_t* rmr_call( void* vctx, rmr_mbuf_t* msg );
394 --------------------------------------------------------------------------------------------
396 The rmr_call function sends the user application message to a
397 remote endpoint, and waits for a corresponding response
398 message before returning control to the user application. The
399 user application supplies a completed message buffer, as it
400 would for a rmr_send call, but unlike with the send, the
401 buffer returned will have the response from the application
402 that received the message.
404 Messages which are received while waiting for the response
405 are queued internally by RMR, and are returned to the user
406 application when rmr_rcv_msg is invoked. These messages are
407 returned in th order received, one per call to rmr_rcv_msg.
410 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
412 The rmr_call function implements a timeout failsafe to
413 prevent, in most cases, the function from blocking forever.
414 The timeout period is **not** based on time (calls to clock
415 are deemed too expensive for a low latency system level
416 library, but instead the period is based on the number of
417 received messages which are not the response. Using a
418 non-time mechanism for *timeout* prevents the async queue
419 from filling (which would lead to message drops) in an
420 environment where there is heavy message traffic.
422 When the threshold number of messages have been queued
423 without receiving a response message, control is returned to
424 the user application and a NULL pointer is returned to
425 indicate that no message was received to process. Currently
426 the threshold is fixed at 20 messages, though in future
427 versions of the library this might be extended to be a
428 parameter which the user application may set.
431 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
433 The send operations in RMr will retry *soft* send failures
434 until one of three conditions occurs:
440 The message is sent without error
445 The underlying transport reports a * hard * failure
450 The maximum number of retry loops has been attempted
453 A retry loop consists of approximately 1000 send attemps **
454 without** any intervening calls to * sleep() * or * usleep().
455 * The number of retry loops defaults to 1, thus a maximum of
456 1000 send attempts is performed before returning to the user
457 application. This value can be set at any point after RMr
458 initialisation using the * rmr_set_stimeout() * function
459 allowing the user application to completely disable retires
460 (set to 0), or to increase the number of retry loops.
462 Transport Level Blocking
463 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
465 The underlying transport mechanism used to send messages is
466 configured in *non-blocking* mode. This means that if a
467 message cannot be sent immediately the transport mechanism
468 will **not** pause with the assumption that the inability to
469 send will clear quickly (within a few milliseconds). This
470 means that when the retry loop is completely disabled (set to
471 0), that the failure to accept a message for sending by the
472 underlying mechanisms (software or hardware) will be reported
473 immediately to the user application.
475 It should be noted that depending on the underlying transport
476 mechanism being used, it is extremly possible that during
477 normal operations that retry conditions are very likely to
478 happen. These are completely out of RMr's control, and there
479 is nothing that RMr can do to avoid or midigate these other
480 than by allowing RMr to retry the send operation, and even
481 then it is possible (e.g. during connection reattempts), that
482 a single retry loop is not enough to guarentee a successful
486 --------------------------------------------------------------------------------------------
488 The rmr_call function returns a pointer to a message buffer
489 with the state set to reflect the overall state of call
490 processing (see Errors below). In some cases a NULL pointer
491 will be returned; when this is the case only *errno* will be
492 available to describe the reason for failure.
495 --------------------------------------------------------------------------------------------
497 These values are reflected in the state field of the returned
504 The call was successful and the message buffer references
505 the response message.
510 The call failed and the value of *errno,* as described
511 below, should be checked for the specific reason.
514 The global "variable" *errno* will be set to one of the
515 following values if the overall call processing was not
522 Too many messages were queued before receiving the
528 The queued message ring is full, messages were dropped
533 A parameter was not valid
538 The underlying message system wsa interrupted or the
539 device was busy; the message was **not** sent, and user
540 application should call this function with the message
545 --------------------------------------------------------------------------------------------
547 The following code bit shows one way of using the rmr_call
548 function, and illustrates how the transaction ID must be set.
553 int retries_left = 5; // max retries on dev not available
554 int retry_delay = 50000; // retry delay (usec)
555 static rmr_mbuf_t* mbuf = NULL; // response msg
556 msg_t* pm; // private message (payload)
557 m// get a send buffer and reference the payload
558 mbuf = rmr_alloc_msg( mr, RMR_MAX_RCV_BYTES );
559 pm = (msg_t*) mbuf->payload;
560 p// generate an xaction ID and fill in payload with data and msg type
561 snprintf( mbuf->xaction, RMR_MAX_XID, "%s", gen_xaction() );
562 snprintf( pm->req, sizeof( pm->req ), "{ \\"req\\": \\"num users\\"}" );
563 mbuf->mtype = MT_REQ;
565 msg = rmr_call( mr, msg );
566 if( ! msg ) { // probably a timeout and no msg received
567 return NULL; // let errno trickle up
569 if( mbuf->state != RMR_OK ) {
570 while( retries_left-- > 0 && // loop as long as eagain
572 (msg = rmr_call( mr, msg )) != NULL &&
573 mbuf->state != RMR_OK ) {
574 usleep( retry_delay );
577 if( mbuf == NULL || mbuf->state != RMR_OK ) {
578 rmr_free_msg( mbuf ); // safe if nil
582 // do something with mbuf
587 --------------------------------------------------------------------------------------------
589 rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3),
590 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
591 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
592 rmr_fib(3), rmr_has_str(3), rmr_set_stimeout(3),
593 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
597 --------------------------------------------------------------------------------------------
602 --------------------------------------------------------------------------------------------
608 void rmr_close( void* vctx )
613 --------------------------------------------------------------------------------------------
615 The rmr_close function closes the listen socket effectively
616 cutting the application off. The route table listener is also
617 stopped. Calls to rmr_rcv_msg() will fail with unpredictable
618 error codes, and calls to rmr_send_msg(), rmr_call(), and
619 rmr_rts_msg() will have unknown results.
623 --------------------------------------------------------------------------------------------
625 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
626 rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3),
627 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
628 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
629 rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_open(3),
634 --------------------------------------------------------------------------------------------
639 --------------------------------------------------------------------------------------------
645 void rmr_free_msg( rmr_mbuf_t* mbuf );
650 --------------------------------------------------------------------------------------------
652 The message buffer is returned to the pool, or the associated
653 memory is released depending on the needs of the underlying
654 messaging system. This allows the user application to release
655 a buffer that is not going to be used. It is safe to pass a
656 nil pointer to this function, and doing so does not result in
657 a change to the value of errrno.
659 After calling, the user application should **not** use any of
660 the pointers (transaction ID, or payload) which were
664 --------------------------------------------------------------------------------------------
666 rmr_alloc_msg(3), rmr_call(3), rmr_init(3),
667 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
668 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
669 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
674 --------------------------------------------------------------------------------------------
679 --------------------------------------------------------------------------------------------
685 char* rmr_get_meid( rmr_mbuf_t* mbuf, unsigned char* dest )
690 --------------------------------------------------------------------------------------------
692 The rmr_get_meid function will copy the managed equipment ID
693 (meid) field from the message into the *dest* buffer provided
694 by the user. The buffer referenced by *dest* is assumed to be
695 at least RMR_MAX_MEID bytes in length. If *dest* is NULL,
696 then a buffer is allocated (the calling application is
697 expected to free when the buffer is no longer needed).
700 --------------------------------------------------------------------------------------------
702 On success, a pointer to the extracted string is returned. If
703 *dest* was supplied, then this is just a pointer to the
704 caller's buffer. If *dest* was NULL, this is a pointer to the
705 allocated buffer. If an error occurs, a nil pointer is
706 returned and errno is set as described below.
709 --------------------------------------------------------------------------------------------
711 If an error occurs, the value of the global variable errno
712 will be set to one of the following with the indicated
719 The message, or an internal portion of the message, was
720 corrupted or the pointer was invalid.
725 A nil pointer was passed for *dest,* however it was not
726 possible to allocate a buffer using malloc().
730 --------------------------------------------------------------------------------------------
732 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3),
733 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
734 rmr_get_xact(3), rmr_payload_size(3), rmr_send_msg(3),
735 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
736 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
737 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
738 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
742 --------------------------------------------------------------------------------------------
747 --------------------------------------------------------------------------------------------
753 void* rmr_get_rcvfd( void* ctx )
758 --------------------------------------------------------------------------------------------
760 The rmr_get_rcvfd function returns a file descriptor which
761 may be given to epoll_wait() by an application that wishes to
762 use event poll in a single thread rather than block on the
763 arrival of a message via calls to rmr_rcv_msg(). When
764 epoll_wait() indicates that this file descriptor is ready, a
765 call to rmr_rcv_msg() will not block as at least one message
768 The context (ctx) pointer passed in is the pointer returned
769 by the call to rmr_init().
771 **NOTE:** There is no support for epoll in Nanomsg, thus his
772 function is only supported when linking with the NNG version
773 of RMr and the file descriptor returned when using the
774 Nanomsg verfsion will always return an error.
777 --------------------------------------------------------------------------------------------
779 The rmr_get_rcvfd function returns a file descriptor greater
780 or equal to 0 on success and -1 on error. If this function is
781 called from a user application linked against the Nanomsg RMr
782 library, calls will always return -1 with errno set to
786 --------------------------------------------------------------------------------------------
788 The following error values are specifically set by this RMR
789 function. In some cases the error message of a system call is
790 propagated up, and thus this list might be incomplete.
795 The use of this function is invalid in this environment.
799 --------------------------------------------------------------------------------------------
801 The following short code bit illustrates the use of this
802 function. Error checking has been omitted for clarity.
809 #include <sys/epoll.h>
812 int rcv_fd; // pollable fd
813 void* mrc; //msg router context
814 struct epoll_event events[10]; // support 10 events to poll
815 struct epoll_event epe; // event definition for event to listen to
817 rmr_mbuf_t* msg = NULL;
821 mrc = rmr_init( "43086", RMR_MAX_RCV_BYTES, RMRFL_NONE );
822 rcv_fd = rmr_get_rcvfd( mrc );
824 rep_fd = epoll_create1( 0 ); _ B ,// initialise epoll environment
825 epe.events = EPOLLIN;
826 epe.data.fd = rcv_fd;
827 epoll_ctl( ep_fd, EPOLL_CTL_ADD, rcv_fd, &epe ); // add our info to the mix
830 nready = epoll_wait( ep_fd, events, 10, -1 ); // -1 == block forever (no timeout)
831 for( i = 0; i < nready && i < 10; i++ ) { // loop through to find what is ready
832 if( events[i].data.fd == rcv_fd ) { // RMr has something
833 msg = rmr_rcv_msg( mrc, msg );
835 // do something with msg
839 // check for other ready fds....
847 --------------------------------------------------------------------------------------------
849 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
850 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
851 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
852 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
857 --------------------------------------------------------------------------------------------
862 --------------------------------------------------------------------------------------------
868 unsigned char* rmr_get_src( rmr_mbuf_t* mbuf, unsigned char* dest )
873 --------------------------------------------------------------------------------------------
875 The rmr_get_src function will copy the *source* information
876 from the message to a buffer (dest) supplied by the user. In
877 an RMr message, the source is the sender's information that
878 is used for return to sender function calls, and is generally
879 the hostname and port in the form *name*. The source might be
880 an IP address port combination; the data is populated by the
881 sending process and the only requirement is that it be
882 capable of being used to start a TCP session with the sender.
884 The maximum size allowed by RMr is 64 bytes (including the
885 nil string terminator), so the user must ensure that the
886 destination buffer given is at least 64 bytes.
889 --------------------------------------------------------------------------------------------
891 On success, a pointer to the destination buffer is given as a
892 convenience to the user programme. On failure, a nil pointer
893 is returned and the value of errno is set.
896 --------------------------------------------------------------------------------------------
898 If an error occurs, the value of the global variable errno
899 will be set to one of the following with the indicated
906 The message, or an internal portion of the message, was
907 corrupted or the pointer was invalid.
911 --------------------------------------------------------------------------------------------
913 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3),
914 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
915 rmr_get_srcip(3), rmr_payload_size(3), rmr_send_msg(3),
916 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
917 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
918 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
919 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
923 --------------------------------------------------------------------------------------------
928 --------------------------------------------------------------------------------------------
934 unsigned char* rmr_get_srcip( rmr_mbuf_t* mbuf, unsigned char* dest )
939 --------------------------------------------------------------------------------------------
941 The rmr_get_srcip function will copy the *source IP address*
942 from the message to a buffer (dest) supplied by the user. In
943 an RMr message, the source IP address is the sender's
944 information that is used for return to sender function calls;
945 this function makes it available to the user application. The
946 address is maintained as IP:port where *IP* could be either
947 an IPv6 or IPv4 address depending on what was provided by the
950 The maximum size allowed by RMr is 64 bytes (including the
951 nil string terminator), so the user must ensure that the
952 destination buffer given is at least 64 bytes. The user
953 application should use the RMr constant RMR_MAX_SRC to ensure
954 that the buffer supplied is large enough, and to protect
955 against future RMr enhancements which might increase the
956 address buffer size requirement.
959 --------------------------------------------------------------------------------------------
961 On success, a pointer to the destination buffer is given as a
962 convenience to the user programme. On failure, a nil pointer
963 is returned and the value of errno is set.
966 --------------------------------------------------------------------------------------------
968 If an error occurs, the value of the global variable errno
969 will be set to one of the following with the indicated
976 The message, or an internal portion of the message, was
977 corrupted or the pointer was invalid.
981 --------------------------------------------------------------------------------------------
983 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3),
984 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
985 rmr_get_src(3), rmr_payload_size(3), rmr_send_msg(3),
986 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
987 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
988 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
989 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
993 --------------------------------------------------------------------------------------------
998 --------------------------------------------------------------------------------------------
1003 #include <rmr/rmr.h>
1004 int rmr_get_trace( rmr_mbuf_t* mbuf, unsigned char* dest, int size )
1009 --------------------------------------------------------------------------------------------
1011 The rmr_get_trace function will copy the trace information
1012 from the message into the user's allocated memory referenced
1013 by dest. The size parameter is assumed to be the maximum
1014 number of bytes which can be copied (size of the destination
1018 --------------------------------------------------------------------------------------------
1020 On success, the number of bytes actually copied is returned.
1021 If the return value is 0, no bytes copied, then the reason
1022 could be that the message pointer was nil, or the size
1026 --------------------------------------------------------------------------------------------
1028 rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3),
1029 rmr_bytes2meid(3), rmr_call(3), rmr_free_msg(3),
1030 rmr_get_rcvfd(3), rmr_get_trlen(3), rmr_init(3),
1031 rmr_init_trace(3), rmr_payload_size(3), rmr_send_msg(3),
1032 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1033 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
1034 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
1035 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3),
1036 rmr_set_trace(3), rmr_trace_ref(3)
1040 --------------------------------------------------------------------------------------------
1045 --------------------------------------------------------------------------------------------
1050 #include <rmr/rmr.h>
1051 int rmr_get_trlen( rmr_mbuf_t* msg );
1056 --------------------------------------------------------------------------------------------
1058 Given a message buffer, this function returns the amount of
1059 space (bytes) that have been allocated for trace data. If no
1060 trace data has been allocated, then 0 is returned.
1063 --------------------------------------------------------------------------------------------
1065 The number of bytes allocated for trace information in the
1069 --------------------------------------------------------------------------------------------
1075 Parameter(s) passed to the function were not valid.
1079 --------------------------------------------------------------------------------------------
1081 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
1082 rmr_get_trace(3), rmr_init(3), rmr_init_trace(3),
1083 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
1084 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
1085 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
1086 rmr_set_trace(3), rmr_tralloc_msg(3)
1090 --------------------------------------------------------------------------------------------
1095 --------------------------------------------------------------------------------------------
1100 #include <rmr/rmr.h>
1101 char* rmr_get_xact( rmr_mbuf_t* mbuf, unsigned char* dest )
1106 --------------------------------------------------------------------------------------------
1108 The rmr_get_xact function will copy the transaction field
1109 from the message into the *dest* buffer provided by the user.
1110 The buffer referenced by *dest* is assumed to be at least
1111 RMR_MAX_XID bytes in length. If *dest* is NULL, then a buffer
1112 is allocated (the calling application is expected to free
1113 when the buffer is no longer needed).
1116 --------------------------------------------------------------------------------------------
1118 On success, a pointer to the extracted string is returned. If
1119 *dest* was supplied, then this is just a pointer to the
1120 caller's buffer. If *dest* was NULL, this is a pointer to the
1121 allocated buffer. If an error occurs, a nil pointer is
1122 returned and errno is set as described below.
1125 --------------------------------------------------------------------------------------------
1127 If an error occurs, the value of the global variable errno
1128 will be set to one of the following with the indicated
1135 The message, or an internal portion of the message, was
1136 corrupted or the pointer was invalid.
1141 A nil pointer was passed for *dest,* however it was not
1142 possible to allocate a buffer using malloc().
1146 --------------------------------------------------------------------------------------------
1148 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3),
1149 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
1150 rmr_get_meid(3), rmr_payload_size(3), rmr_send_msg(3),
1151 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1152 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
1153 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
1154 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
1158 --------------------------------------------------------------------------------------------
1163 --------------------------------------------------------------------------------------------
1168 #include <rmr/rmr.h>
1169 void* rmr_init( char* proto_port, int max_msg_size, int flags );
1174 --------------------------------------------------------------------------------------------
1176 The rmr_init function prepares the environment for sending
1177 and receiving messages. It does so by establishing a worker
1178 thread (pthread) which subscribes to a route table generator
1179 which provides the necessary routing information for the RMR
1180 library to send messages.
1182 *Port* is used to listen for connection requests from other
1183 RMR based applications. The value of *max_msg_size* will be
1184 used when allocating zero copy send buffers which must be
1185 allocated, possibly, prior to the application knowing the
1186 actual size of a specific message.
1188 *Flags* allows for selection of some RMr options at the time
1189 of initialisation. These are set by ORing RMRFL constants
1190 from the RMr header file. Currently the following flags are
1202 The route table collector thread is not to be started.
1203 This should only be used by the route table generator
1204 application if it is based on RMr.
1209 Enable multi-threaded call support.
1212 Multi-threaded Calling
1213 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1215 The support for an application to issue a *blocking call* by
1216 the rmr_call() function was limited such that only user
1217 applications which were operating in a single thread could
1218 safely use the function. Further, timeouts were message count
1219 based and not time unit based. Multi-threaded call support
1220 adds the ability for a user application with multiple threads
1221 to invoke a blocking call function with the guarentee that
1222 the correct response message is delivered to the thread. The
1223 additional support is implemented with the *rmr_mt_call()*
1224 and *rmr_mt_rcv()* function calls.
1226 Multi-threaded call support requires the user application to
1227 specifically enable it when RMr is initialised. This is
1228 necessary because a second, dedicated, receiver thread must
1229 be started, and requires all messages to be examined and
1230 queued by this thread. The additional overhead is minimal,
1231 queuing information is all in the RMr message header, but as
1232 an additional process is necessary the user application must
1233 "opt in" to this approach.
1237 --------------------------------------------------------------------------------------------
1239 As a part of the initialisation process rmr_init will look
1240 into the available environment variables to influence it's
1241 setup. The following variables will be used when found.
1247 Assumes this is the filename of the seed route table file
1248 to use. In normal situations, the library will wait for an
1249 update from the route table generator (expected within a
1250 few seconds of initialisation) before being able to send
1251 messages. However, in some situations where a bootstrap
1252 table is necessary, this is the means to supply it to the
1258 The route table generator assumes that RMr is listening on
1259 a well known port (4561) by default, but this environment
1260 variable can be used to change the listening port if
1261 needed. The value of the variable is expected to be just
1266 --------------------------------------------------------------------------------------------
1268 The rmr_init function returns a void pointer (a contex if you
1269 will) that is passed as the first parameter to nearly all
1270 other RMR functions. If rmr_init is unable to properly
1271 initialise the environment, NULL is returned and errno is set
1272 to an appropriate value.
1275 --------------------------------------------------------------------------------------------
1277 The following error values are specifically set by this RMR
1278 function. In some cases the error message of a system call is
1279 propagated up, and thus this list might be incomplete.
1284 Unable to allocate memory.
1288 --------------------------------------------------------------------------------------------
1294 rmr_mbuf* buf = NULL;
1295 uh = rmr_init( "43086", 4096, 0 );
1296 buf = rmr_rcv_msg( uh, buf );
1301 --------------------------------------------------------------------------------------------
1303 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
1304 rmr_get_rcvfd(3), rmr_mt_call(3), rmr_mt_rcv(3),
1305 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
1306 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
1307 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
1312 --------------------------------------------------------------------------------------------
1317 --------------------------------------------------------------------------------------------
1322 #include <rmr/rmr.h>
1323 void* rmr_init_trace( void* ctx )
1328 --------------------------------------------------------------------------------------------
1330 The rmr_init_trace function establishes the default trace
1331 space placed in each message buffer allocated with
1332 rmr_alloc_msg(). If this function is never called, then no
1333 trace space is allocated by default into any message buffer.
1335 Trace space allows the user application to pass some trace
1336 token, or other data with the message, but outside of the
1337 payload. Trace data may be added to any message with
1338 rmr_set_trace(), and may be extracted from a message with
1339 rmr_get_trace(). The number of bytes that a message contains
1340 for/with trace data can be determined by invoking
1343 This function may be safely called at any time during the
1344 life of the user programme to (re)set the default trace space
1345 reserved. If the user programme needs to allocate a message
1346 with trace space of a different size than is allocated by
1347 default, without fear of extra overhead of reallocating a
1348 message later, the rmr_tralloc_msg() function can be used.
1351 --------------------------------------------------------------------------------------------
1353 A value of 1 is returned on success, and 0 on failure. A
1354 failure indicates that the RMr context (a void pointer passed
1355 to this function was not valid.
1358 --------------------------------------------------------------------------------------------
1360 rmr_alloc_msg(3), rmr_tr_alloc_msg(3), rmr_call(3),
1361 rmr_free_msg(3), rmr_get_rcvfd(3), rmr_get_trace(3),
1362 rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
1363 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1364 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
1365 rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)
1369 --------------------------------------------------------------------------------------------
1374 --------------------------------------------------------------------------------------------
1379 #include <rmr/rmr.h>
1380 extern rmr_mbuf_t* rmr_mt_call( void* vctx, rmr_mbuf_t* msg, int id, int timeout );
1385 --------------------------------------------------------------------------------------------
1387 The rmr_mt_call function sends the user application message
1388 to a remote endpoint, and waits for a corresponding response
1389 message before returning control to the user application. The
1390 user application supplies a completed message buffer, as it
1391 would for a rmr_send_msg call, but unlike with a send, the
1392 buffer returned will have the response from the application
1393 that received the message. The thread invoking the
1394 *rmr_mt_call()* will block until a message arrives or until
1395 *timeout* milliseconds has passed; which ever comes first.
1396 Using a timeout value of zero (0) will cause the thread to
1397 block without a timeout.
1399 The *id* supplied as the third parameter is an integer in the
1400 range of 2 through 255 inclusive. This is a caller defined
1401 "thread number" and is used to match the response message
1402 with the correct user application thread. If the ID value is
1403 not in the proper range, the attempt to make the call will
1406 Messages which are received while waiting for the response
1407 are queued on a *normal* receive queue and will be delivered
1408 to the user application with the next invocation of
1409 *rmr_mt_rcv()* or *rmr_rvv_msg().* by RMR, and are returned
1410 to the user application when rmr_rcv_msg is invoked. These
1411 messages are returned in th order received, one per call to
1414 NOTE: Currently the multi-threaded functions are supported
1415 only when the NNG transport mechanism is being used. It will
1416 not be possible to link a programme using the Nanomsg version
1417 of the library when references to this function are present.
1420 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1422 The user application is responsible for setting the value of
1423 the transaction ID field before invoking *rmr_mt_call.* The
1424 transaction ID is a RMR_MAX_XID byte field that is used to
1425 match the response message when it arrives. RMr will compare
1426 **all** of the bytes in the field, so the caller must ensure
1427 that they are set correctly to avoid missing the response
1428 message. (The application which returns the response message
1429 is also expected to ensure that the return buffer has the
1430 matching transaction ID. This can be done transparently if
1431 the application uses the *rmr_rts_msg()* function and does
1432 not adjust the transaction ID.
1435 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1437 The send operations in RMr will retry *soft* send failures
1438 until one of three conditions occurs:
1444 The message is sent without error
1449 The underlying transport reports a * hard * failure
1454 The maximum number of retry loops has been attempted
1457 A retry loop consists of approximately 1000 send attemps **
1458 without** any intervening calls to * sleep() * or * usleep().
1459 * The number of retry loops defaults to 1, thus a maximum of
1460 1000 send attempts is performed before returning to the user
1461 application. This value can be set at any point after RMr
1462 initialisation using the * rmr_set_stimeout() * function
1463 allowing the user application to completely disable retires
1464 (set to 0), or to increase the number of retry loops.
1466 Transport Level Blocking
1467 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1469 The underlying transport mechanism used to send messages is
1470 configured in *non-blocking* mode. This means that if a
1471 message cannot be sent immediately the transport mechanism
1472 will **not** pause with the assumption that the inability to
1473 send will clear quickly (within a few milliseconds). This
1474 means that when the retry loop is completely disabled (set to
1475 0), that the failure to accept a message for sending by the
1476 underlying mechanisms (software or hardware) will be reported
1477 immediately to the user application.
1479 It should be noted that depending on the underlying transport
1480 mechanism being used, it is extremly possible that during
1481 normal operations that retry conditions are very likely to
1482 happen. These are completely out of RMr's control, and there
1483 is nothing that RMr can do to avoid or midigate these other
1484 than by allowing RMr to retry the send operation, and even
1485 then it is possible (e.g. during connection reattempts), that
1486 a single retry loop is not enough to guarentee a successful
1490 --------------------------------------------------------------------------------------------
1492 The rmr_mt_call function returns a pointer to a message
1493 buffer with the state set to reflect the overall state of
1494 call processing. If the state is RMR_OK then the buffer
1495 contains the response message; otherwise the state indicates
1496 the error encountered while attempting to send the message.
1498 If no response message is received when the timeout period
1499 has expired, a nil pointer will be returned (NULL).
1502 --------------------------------------------------------------------------------------------
1504 These values are reflected in the state field of the returned
1511 The call was successful and the message buffer references
1512 the response message.
1517 An argument passed to the function was invalid.
1522 The call failed and the value of *errno,* as described
1523 below, should be checked for the specific reason.
1528 An endpoint associated with the message type could not be
1529 found in the route table.
1534 The underlying transport mechanism was unable to accept
1535 the message for sending. The user application can retry
1536 the call operation if appropriate to do so.
1539 The global "variable" *errno* will be set to one of the
1540 following values if the overall call processing was not
1547 Too many messages were queued before receiving the
1553 The queued message ring is full, messages were dropped
1558 A parameter was not valid
1563 The underlying message system wsa interrupted or the
1564 device was busy; the message was **not** sent, and user
1565 application should call this function with the message
1570 --------------------------------------------------------------------------------------------
1572 The following code bit shows one way of using the rmr_mt_call
1573 function, and illustrates how the transaction ID must be set.
1578 int retries_left = 5; // max retries on dev not available
1579 static rmr_mbuf_t* mbuf = NULL; // response msg
1580 msg_t* pm; // private message (payload)
1581 m// get a send buffer and reference the payload
1582 mbuf = rmr_alloc_msg( mr, RMR_MAX_RCV_BYTES );
1583 pm = (msg_t*) mbuf->payload;
1584 p// generate an xaction ID and fill in payload with data and msg type
1585 rmr_bytes2xact( mbuf, xid, RMR_MAX_XID );
1586 snprintf( pm->req, sizeof( pm->req ), "{ \\"req\\": \\"num users\\"}" );
1587 mbuf->mtype = MT_USR_RESP;
1589 msg = rmr_mt_call( mr, msg, my_id, 100 ); e :// wait up to 100ms
1590 if( ! msg ) { // probably a timeout and no msg received
1591 return NULL; // let errno trickle up
1593 if( mbuf->state != RMR_OK ) {
1594 while( retries_left-- > 0 && // loop as long as eagain
1595 mbuf->state == RMR_ERR_RETRY &&
1596 (msg = rmr_mt_call( mr, msg )) != NULL &&
1597 mbuf->state != RMR_OK ) {
1598 usleep( retry_delay );
1601 if( mbuf == NULL || mbuf->state != RMR_OK ) {
1602 rmr_free_msg( mbuf ); // safe if nil
1606 // do something with mbuf
1611 --------------------------------------------------------------------------------------------
1613 rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3),
1614 rmr_mt_rcv(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),
1617 rmr_set_stimeout(3), rmr_tokenise(3), rmr_mk_ring(3),
1622 --------------------------------------------------------------------------------------------
1627 --------------------------------------------------------------------------------------------
1632 #include <rmr/rmr.h>
1633 rmr_mbuf_t* rmr_mt_rcv( void* vctx, rmr_mbuf_t* old_msg, int timeout );
1638 --------------------------------------------------------------------------------------------
1640 The rmr_mt_rcv function blocks until a message is received,
1641 or the timeout period (milliseconds) has passed. The result
1642 is an RMr message buffer which references a received message.
1643 In the case of a timeout the state will be reflected in an
1644 "empty buffer" (if old_msg was not nil, or simply with the
1645 return of a nil pointer. If a timeout value of zero (0) is
1646 given, then the function will block until the next message
1649 The *vctx* pointer is the pointer returned by the rmr_init
1650 function. *Old_msg* is a pointer to a previously used message
1651 buffer or NULL. The ability to reuse message buffers helps to
1652 avoid alloc/free cycles in the user application. When no
1653 buffer is available to supply, the receive function will
1656 The *old_msg* parameter allows the user to pass a previously
1657 generated RMr message back to RMr for reuse. Optionally, the
1658 user application may pass a nil pointer if no reusable
1659 message is available. When a timeout occurs, and old_msg was
1660 not nil, the state will be returned by returning a pointer to
1661 the old message with the state set.
1663 It is possible to use the *rmr_rcv_msg()* function instead of
1664 this function. Doing so might be advantagous if the user
1665 programme does not always start the multi-threaded mode and
1666 the use of *rmr_rcv_msg()* would make the flow of the code
1667 more simple. The advantags of using this function are the
1668 ability to set a timeout without using epoll, and a small
1669 performance gain (if multi-threaded mode is enabled, and the
1670 *rmr_rcv_msg()* function is used, it simply invokes this
1671 function without a timeout value, thus there is the small
1672 cost of a second call that results). Similarly, the
1673 *rmr_torcv_msg()* call can be used when in multi-threaded
1674 mode with the same "pass through" overhead to using this
1677 NOTE: Currently the multi-threaded functions are supported
1678 only when the NNG transport mechanism is being used. It will
1679 not be possible to link a programme using the nanomsg version
1680 of the library when references to this function are present.
1683 --------------------------------------------------------------------------------------------
1685 When a message is received before the timeout period expires,
1686 a pointer to the RMr message buffer which describes the
1687 message is returned. This will, with a high probability, be a
1688 different message buffer than *old_msg;* the user application
1689 should not continue to use *old_msg* after it is passed to
1692 In the event of a timeout the return value will be the old
1693 msg with the state set, or a nil pointer if no old message
1697 --------------------------------------------------------------------------------------------
1699 The *state* field in the message buffer will be set to one of
1700 the following values:
1706 The message was received without error.
1711 A parameter passed to the function was not valid (e.g. a
1712 nil pointer). indicate either RMR_OK or RMR_ERR_EMPTY if
1713 an empty message was received.
1718 The message received had no associated data. The length of
1719 the message will be 0.
1724 The multi-threaded option was not enabled when RMr was
1725 initialised. See the man page for *rmr_init()* for
1731 A hard error occurred preventing the receive from
1734 When a nil pointer is returned, or any other state value was
1735 set in the message buffer, errno will be set to one of the
1742 Parameter(s) passed to the function were not valid.
1747 The underlying message transport is unable to process the
1753 The underlying message transport is unable to process the
1759 The underlying message transport is unable to process the
1765 The underlying message transport is unable to process the
1771 The underlying message transport is unable to process the
1777 The underlying message transport is unable to process the
1783 The underlying message transport is unable to process the
1788 --------------------------------------------------------------------------------------------
1794 rmr_mbuf_t* mbuf = NULL; // received msg
1795 msg = rmr_mt_recv( mr, mbuf, 100 ); // wait up to 100ms
1797 switch( msg->state ) {
1799 printf( "got a good message\\n" );
1802 printf( "received timed out\\n" );
1805 printf( "receive error: %d\\n", mbuf->state );
1809 printf( "receive timeout (nil)\\n" );
1815 --------------------------------------------------------------------------------------------
1817 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
1818 rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3),
1819 rmr_mt_call(3), rmr_payload_size(3), rmr_send_msg(3),
1820 rmr_torcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1821 rmr_ready(3), rmr_ring_free(3), rmr_torcv_msg(3)
1825 --------------------------------------------------------------------------------------------
1830 --------------------------------------------------------------------------------------------
1835 #include <rmr/rmr.h>
1836 int rmr_payload_size( rmr_mbuf_t* msg );
1841 --------------------------------------------------------------------------------------------
1843 Given a message buffer, this function returns the amount of
1844 space (bytes) available for the user application to consume
1845 in the message payload. This is different than the message
1846 length available as a field in the message buffer.
1849 --------------------------------------------------------------------------------------------
1851 The number of bytes available in the payload.
1854 --------------------------------------------------------------------------------------------
1860 Parameter(s) passed to the function were not valid.
1864 --------------------------------------------------------------------------------------------
1866 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
1867 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
1868 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
1869 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
1873 --------------------------------------------------------------------------------------------
1878 --------------------------------------------------------------------------------------------
1883 #include <rmr/rmr.h>
1884 rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg );
1889 --------------------------------------------------------------------------------------------
1891 The rmr_rcv_msg function blocks until a message is received,
1892 returning the message to the caller via a pointer to a
1893 rmr_mbuf_t structure type. If messages were queued while
1894 waiting for the response to a previous invocation of
1895 rmr_call, the oldest message is removed from the queue and
1896 returned without delay.
1898 The *vctx* pointer is the pointer returned by the rmr_init
1899 function. *Old_msg* is a pointer to a previously used message
1900 buffer or NULL. The ability to reuse message buffers helps to
1901 avoid alloc/free cycles in the user application. When no
1902 buffer is available to supply, the receive function will
1906 --------------------------------------------------------------------------------------------
1908 The function returns a pointer to the rmr_mbuf_t structure
1909 which references the message information (state, length,
1910 payload), or a NULL pointer in the case of an extreme error.
1913 --------------------------------------------------------------------------------------------
1915 The *state* field in the message buffer will indicate either
1916 RMR_OK or RMR_ERR_EMPTY if an empty message was received. If
1917 a nil pointer is returned, or any other state value was set
1918 in the message buffer, errno will be set to one of the
1925 Parameter(s) passed to the function were not valid.
1930 The underlying message transport is unable to process the
1936 The underlying message transport is unable to process the
1942 The underlying message transport is unable to process the
1948 The underlying message transport is unable to process the
1954 The underlying message transport is unable to process the
1960 The underlying message transport is unable to process the
1966 The underlying message transport is unable to process the
1971 --------------------------------------------------------------------------------------------
1975 --------------------------------------------------------------------------------------------
1977 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
1978 rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3),
1979 rmr_payload_size(3), rmr_send_msg(3), rmr_torcv_msg(3),
1980 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
1981 rmr_ring_free(3), rmr_torcv_msg(3)
1985 --------------------------------------------------------------------------------------------
1990 --------------------------------------------------------------------------------------------
1995 #include <rmr/rmr.h>
1996 int rmr_ready( void* vctx );
2001 --------------------------------------------------------------------------------------------
2003 The rmr_ready function checks to see if a routing table has
2004 been successfully received and installed. The return value
2005 indicates the state of readiness.
2008 --------------------------------------------------------------------------------------------
2010 A return value of 1 (true) indicates that the routing table
2011 is in place and attempts to send messages can be made. When 0
2012 is returned (false) the routing table has not been received
2013 and thus attempts to send messages will fail with *no
2017 --------------------------------------------------------------------------------------------
2019 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2020 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
2021 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_fib(3),
2022 rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
2027 --------------------------------------------------------------------------------------------
2032 --------------------------------------------------------------------------------------------
2037 #include <rmr/rmr.h>
2038 extern rmr_mbuf_t* rmr_realloc_payload( rmr_mbuf_t* msg, int new_len, int copy, int clone );
2043 --------------------------------------------------------------------------------------------
2045 The rmr_realloc_payload function will return a pointer to an
2046 RMR message buffer struct (rmr_mbuf_t) which has a payload
2047 large enough to accomodate *new_len* bytes. If necessary, the
2048 underlying payload is reallocated, and the bytes from the
2049 original payload are copied if the *copy* parameter is true
2050 (1). If the message passed in has a payload large enough,
2051 there is no additional memory allocation and copying.
2053 Cloning The Message Buffer
2054 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2056 This function can also be used to generate a separate copy of
2057 the original message, with the desired payload size, without
2058 destroying the original message buffer or the original
2059 payload. A standalone copy is made only when the *clone*
2060 parameter is true (1). When cloning, the payload is copied to
2061 the cloned message **only** if the *copy* parameter is true.
2063 Message Buffer Metadata
2064 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2066 The metadata in the original message buffer (message type,
2067 subscription ID, and payload length) will be preserved if the
2068 *copy* parameter is true. When this parameter is not true
2069 (0), then these values are set to the uninitialised value
2070 (-1) for type and ID, and the length is set to 0.
2073 --------------------------------------------------------------------------------------------
2075 The rmr_realloc_payload function returns a pointer to the
2076 message buffer with the payload which is large enough to hold
2077 *new_len* bytes. If the *clone* option is true, this will be
2078 a pointer to the newly cloned message buffer; the original
2079 message buffer pointer may still be used to referenced that
2080 message. It is the calling application's responsibility to
2081 free the memory associateed with both messages using the
2082 rmr_free_msg() function.
2084 When the *clone* option is not used, it is still good
2085 practice by the calling application to capture and use this
2086 reference as it is possible that the message buffer, and not
2087 just the payload buffer, was reallocated. In the event of an
2088 error, a nil pointer will be returned and the value of
2089 *errno* will be set to reflect the problem.
2092 --------------------------------------------------------------------------------------------
2094 These value of *errno* will reflect the error condition if a
2095 nil pointer is returned:
2101 Memory allocation of the new payload failed.
2106 The pointer passed in was nil, or refrenced an invalid
2107 message, or the required length was not valid.
2111 --------------------------------------------------------------------------------------------
2113 The following code bit illustrates how this function can be
2114 used to reallocate a buffer for a return to sender
2115 acknowledgement message which is larger than the message
2121 if( rmr_payload_size( msg ) < ack_sz ) { // received message too small for ack
2122 msg = rmr_realloc_payload( msg, ack_sz, 0, 0 ); // reallocate the message with a payload big enough
2124 fprintf( stderr, "[ERR] realloc returned a nil pointer: %s\\n", strerror( errno ) );
2126 } e// populate and send ack message
2133 --------------------------------------------------------------------------------------------
2135 rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3),
2136 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
2137 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
2138 rmr_fib(3), rmr_has_str(3), rmr_set_stimeout(3),
2139 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
2143 --------------------------------------------------------------------------------------------
2148 --------------------------------------------------------------------------------------------
2153 #include <rmr/rmr.h>
2154 rmr_mbuf_t* rmr_rts_msg( void* vctx, rmr_mbuf_t* msg );
2159 --------------------------------------------------------------------------------------------
2161 The rmr_rts_msg function sends a message returning it to the
2162 endpoint which sent the message rather than selecting an
2163 endpoint based on the message type and routing table. Other
2164 than this small difference, the behaviour is exactly the same
2168 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2170 The send operations in RMr will retry *soft* send failures
2171 until one of three conditions occurs:
2177 The message is sent without error
2182 The underlying transport reports a * hard * failure
2187 The maximum number of retry loops has been attempted
2190 A retry loop consists of approximately 1000 send attemps **
2191 without** any intervening calls to * sleep() * or * usleep().
2192 * The number of retry loops defaults to 1, thus a maximum of
2193 1000 send attempts is performed before returning to the user
2194 application. This value can be set at any point after RMr
2195 initialisation using the * rmr_set_stimeout() * function
2196 allowing the user application to completely disable retires
2197 (set to 0), or to increase the number of retry loops.
2199 Transport Level Blocking
2200 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2202 The underlying transport mechanism used to send messages is
2203 configured in *non-blocking* mode. This means that if a
2204 message cannot be sent immediately the transport mechanism
2205 will **not** pause with the assumption that the inability to
2206 send will clear quickly (within a few milliseconds). This
2207 means that when the retry loop is completely disabled (set to
2208 0), that the failure to accept a message for sending by the
2209 underlying mechanisms (software or hardware) will be reported
2210 immediately to the user application.
2212 It should be noted that depending on the underlying transport
2213 mechanism being used, it is extremly possible that during
2214 normal operations that retry conditions are very likely to
2215 happen. These are completely out of RMr's control, and there
2216 is nothing that RMr can do to avoid or midigate these other
2217 than by allowing RMr to retry the send operation, and even
2218 then it is possible (e.g. during connection reattempts), that
2219 a single retry loop is not enough to guarentee a successful
2223 --------------------------------------------------------------------------------------------
2225 When crafting a response based on a received message, the
2226 user application must take care not to write more bytes to
2227 the message payload than the allocated message has. In the
2228 case of a received message, it is possible that the response
2229 needs to be larger than the payload associated with the
2230 inbound message. In order to use the return to sender
2231 function, the source infomration in the orignal message must
2232 be present in the response; information which cannot be added
2233 to a message buffer allocated through the standard RMR
2234 allocation function. To allocate a buffer with a larger
2235 payload, and which retains the necessary sender data needed
2236 by this function, the *rmr_realloc_payload()* function must
2237 be used to extend the payload to a size suitable for the
2241 --------------------------------------------------------------------------------------------
2243 On success, a new message buffer, with an empty payload, is
2244 returned for the application to use for the next send. The
2245 state in this buffer will reflect the overall send operation
2246 state and should be RMR_OK.
2248 If the state in the returned buffer is anything other than
2249 UT_OK, the user application may need to attempt a
2250 retransmission of the message, or take other action depending
2251 on the setting of errno as described below.
2253 In the event of extreme failure, a NULL pointer is returned.
2254 In this case the value of errno might be of some use, for
2255 documentation, but there will be little that the user
2256 application can do other than to move on.
2259 --------------------------------------------------------------------------------------------
2261 The following values may be passed back in the *state* field
2262 of the returned message buffer.
2268 The message buffer pointer did not refer to a valid
2273 The header in the message buffer was not valid or
2278 The message type in the message buffer did not map to a
2283 The send failed; errno has the possible reason.
2286 The following values may be assigned to errno on failure.
2291 Parameter(s) passed to the function were not valid, or the
2292 underlying message processing environment was unable to
2293 interpret the message.
2298 The header information in the message buffer was invalid.
2303 No known endpoint for the message could be found.
2308 The underlying transport refused to accept the message
2309 because of a size value issue (message was not attempted
2315 The message referenced by the message buffer is corrupt
2316 (NULL pointer or bad internal length).
2321 Internal RMR error; information provided to the message
2322 transport environment was not valid.
2327 Sending was not supported by the underlying message
2333 The device is not in a state that can accept the message.
2338 The device is not able to accept a message for sending.
2339 The user application should attempt to resend.
2344 The operation was interrupted by delivery of a signal
2345 before the message was sent.
2350 The underlying message environment timed out during the
2356 The underlying message environment is in a shutdown state.
2360 --------------------------------------------------------------------------------------------
2364 --------------------------------------------------------------------------------------------
2366 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2367 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
2368 rmr_rcv_specific(3), rmr_ready(3), rmr_fib(3),
2369 rmr_has_str(3), rmr_set_stimeout(3), rmr_tokenise(3),
2370 rmr_mk_ring(3), rmr_ring_free(3)
2374 --------------------------------------------------------------------------------------------
2379 --------------------------------------------------------------------------------------------
2384 #include <rmr/rmr.h>
2385 rmr_mbuf_t* rmr_send_msg( void* vctx, rmr_mbuf_t* msg );
2390 --------------------------------------------------------------------------------------------
2392 The rmr_send_msg function accepts a message buffer from the
2393 user application and attempts to send it. The destination of
2394 the message is selected based on the message type specified
2395 in the message buffer, and the matching information in the
2396 routing tables which are currently in use by the RMR library.
2397 This may actually result in the sending of the message to
2398 multiple destinations which could degrade expected overall
2399 performance of the user application. (Limiting excessive
2400 sending of messages is the responsibility of the
2401 application(s) responsible for building the routing table
2402 used by the RMR library, and not the responsibility of the
2406 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2408 The send operations in RMr will retry *soft* send failures
2409 until one of three conditions occurs:
2415 The message is sent without error
2420 The underlying transport reports a * hard * failure
2425 The maximum number of retry loops has been attempted
2428 A retry loop consists of approximately 1000 send attemps **
2429 without** any intervening calls to * sleep() * or * usleep().
2430 * The number of retry loops defaults to 1, thus a maximum of
2431 1000 send attempts is performed before returning to the user
2432 application. This value can be set at any point after RMr
2433 initialisation using the * rmr_set_stimeout() * function
2434 allowing the user application to completely disable retires
2435 (set to 0), or to increase the number of retry loops.
2437 Transport Level Blocking
2438 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2440 The underlying transport mechanism used to send messages is
2441 configured in *non-blocking* mode. This means that if a
2442 message cannot be sent immediately the transport mechanism
2443 will **not** pause with the assumption that the inability to
2444 send will clear quickly (within a few milliseconds). This
2445 means that when the retry loop is completely disabled (set to
2446 0), that the failure to accept a message for sending by the
2447 underlying mechanisms (software or hardware) will be reported
2448 immediately to the user application.
2450 It should be noted that depending on the underlying transport
2451 mechanism being used, it is extremly possible that during
2452 normal operations that retry conditions are very likely to
2453 happen. These are completely out of RMr's control, and there
2454 is nothing that RMr can do to avoid or midigate these other
2455 than by allowing RMr to retry the send operation, and even
2456 then it is possible (e.g. during connection reattempts), that
2457 a single retry loop is not enough to guarentee a successful
2461 --------------------------------------------------------------------------------------------
2463 On success, a new message buffer, with an empty payload, is
2464 returned for the application to use for the next send. The
2465 state in this buffer will reflect the overall send operation
2466 state and should be RMR_OK.
2468 When the message cannot be successfully sent this function
2469 will return the unsent (original) message buffer with the
2470 state set to indicate the reason for failure. The value of
2471 *errno* may also be set to reflect a more detailed failure
2472 reason if it is known.
2474 In the event of extreme failure, a NULL pointer is returned.
2475 In this case the value of errno might be of some use, for
2476 documentation, but there will be little that the user
2477 application can do other than to move on.
2480 --------------------------------------------------------------------------------------------
2482 The following values may be passed back in the *state* field
2483 of the returned message buffer.
2489 The message could not be sent, but the underlying
2490 transport mechanism indicates that the failure is
2491 temporary. If the send operation is tried again it might
2496 The send operation was not successful and the underlying
2497 transport mechanism indicates a permanent (hard) failure;
2498 retrying the send is not possible.
2502 The message buffer pointer did not refer to a valid
2507 The header in the message buffer was not valid or
2512 The message type in the message buffer did not map to a
2516 The following values may be assigned to errno on failure.
2521 Parameter(s) passed to the function were not valid, or the
2522 underlying message processing environment was unable to
2523 interpret the message.
2528 The header information in the message buffer was invalid.
2533 No known endpoint for the message could be found.
2538 The underlying transport refused to accept the message
2539 because of a size value issue (message was not attempted
2545 The message referenced by the message buffer is corrupt
2546 (NULL pointer or bad internal length).
2551 Internal RMR error; information provided to the message
2552 transport environment was not valid.
2557 Sending was not supported by the underlying message
2563 The device is not in a state that can accept the message.
2568 The device is not able to accept a message for sending.
2569 The user application should attempt to resend.
2574 The operation was interrupted by delivery of a signal
2575 before the message was sent.
2580 The underlying message environment timed out during the
2586 The underlying message environment is in a shutdown state.
2590 --------------------------------------------------------------------------------------------
2592 The following is a simple example of how the rmr_send_msg
2593 function is called. In this example, the send message buffer
2594 is saved between calls and reused eliminating alloc/free
2600 static rmr_mbuf_t* send_msg = NULL; // message to send; reused on each call
2601 msg_t* send_pm; // payload for send
2602 msg_t* pm; // our message format in the received payload
2603 mif( send_msg == NULL ) {
2604 send_msg = rmr_alloc_msg( mr, MAX_SIZE ); r// new buffer to send
2606 // reference payload and fill in message type
2607 pm = (msg_t*) send_msg->payload;
2608 send_msg->mtype = MT_ANSWER;
2609 msg->len = generate_data( pm ); e// something that fills the payload in
2610 msg = rmr_send_msg( mr, send_msg );
2614 m sif( msg->state != RMR_OK ) {
2615 m s m// check for eagain, and resend if needed
2616 m s m// else return error
2625 --------------------------------------------------------------------------------------------
2627 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2628 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
2629 rmr_rts_msg(3), rmr_ready(3), rmr_mk_ring(3),
2630 rmr_ring_free(3), rmr_torcv_rcv(3), rmr_wh_send_msg(3)
2634 --------------------------------------------------------------------------------------------
2639 --------------------------------------------------------------------------------------------
2644 #include <rmr/rmr.h>
2645 rmr_mbuf_t* rmr_set_stimeout( void* vctx, int rloops );
2650 --------------------------------------------------------------------------------------------
2652 The rmr_set_stimeout function sets the configuration for how
2653 RMr will retry message send operations which complete with
2654 either a *timeout* or *again* completion value. (Send
2655 operations include all of the possible message send
2656 functions: *rmr_send_msg(), rmr_call(), rmr_rts_msg()* and
2657 *rmr_wh_send_msg().* The *rloops* parameter sets the maximum
2658 number of retry loops that will be attempted before giving up
2659 and returning the unsuccessful state to the user application.
2660 Each retry loop is approximately 1000 attempts, and RMr does
2661 **not** invoke any sleep function between retries in the
2662 loop; a small, 1 mu-sec, sleep is executed between loop sets
2663 if the *rloops* value is greater than 1.
2667 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2669 By default, the send operations will execute with an *rloop*
2670 setting of 1; each send operation will attempt to resend the
2671 message approximately 1000 times before giving up. If the
2672 user application does not want to have send operations retry
2673 when the underlying transport mechanism indicates *timeout*
2674 or *again,* the application should invoke this function and
2675 pass a value of 0 (zero) for *rloops.* With this setting, all
2676 RMr send operations will attempt a send operation only
2677 **once,** returning immediately to the caller with the state
2678 of that single attempt.
2681 --------------------------------------------------------------------------------------------
2683 This function returns a -1 to indicate that the *rloops*
2684 value could not be set, and the value *RMR_OK* to indicate
2688 --------------------------------------------------------------------------------------------
2690 Currently errno is **not** set by this function; the only
2691 cause of a failure is an invalid context (*vctx*) pointer.
2694 --------------------------------------------------------------------------------------------
2696 The following is a simple example of how the rmr_set_stimeout
2703 char* Oport = "43086"; // port for message router listen
2704 int rmax_size = 4096; // max message size for default allocations
2705 void* mr_context; // message router context
2706 mr_context = rmr_init( port, max_size, NO_FLAGS );
2707 if( mr_context != NULL ) {
2708 rmr_set_stimeout( mr_context, 0 ); // turn off retries
2714 --------------------------------------------------------------------------------------------
2716 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2717 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
2718 rmr_rts_msg(3), rmr_ready(3), rmr_mk_ring(3),
2719 rmr_ring_free(3), rmr_send_msg(3), rmr_torcv_rcv(3),
2724 --------------------------------------------------------------------------------------------
2729 --------------------------------------------------------------------------------------------
2734 #include <rmr/rmr.h>
2735 int rmr_bytes2payload( rmr_mbuf_t* mbuf, unsigned char* data, int len )
2740 --------------------------------------------------------------------------------------------
2742 The rmr_set_trace function will copy len bytes from data into
2743 the trace portion of mbuf. If the trace area of mbuf is not
2744 the correct size, the message buffer will be reallocated to
2745 ensure that enough space is available for the trace data.
2748 --------------------------------------------------------------------------------------------
2750 The rmr_set_trace function returns the number of bytes
2751 successfully copied to the message. If 0 is returned either
2752 the message pointer was nil, or the size in the parameters
2756 --------------------------------------------------------------------------------------------
2758 rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3),
2759 rmr_bytes2payload(3), rmr_call(3), rmr_free_msg(3),
2760 rmr_get_rcvfd(3), rmr_get_meid(3), rmr_get_trace(3),
2761 rmr_get_trlen(3), rmr_init(3), rmr_init_trace(3),
2762 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
2763 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
2764 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
2765 rmr_ring_free(3), rmr_str2meid(3), rmr_str2xact(3),
2766 rmr_wh_open(3), rmr_wh_send_msg(3)
2770 --------------------------------------------------------------------------------------------
2775 --------------------------------------------------------------------------------------------
2780 #include <rmr/rmr.h>
2781 int rmr_str2meid( rmr_mbuf_t* mbuf, unsigned char* src, int len )
2786 --------------------------------------------------------------------------------------------
2788 The rmr_str2meid function will copy the string pointed to by
2789 src to the managed equipment ID (meid) field in the given
2790 message. The field is a fixed length, gated by the constant
2791 RMR_MAX_MEID and if string length is larger than this value,
2792 then **nothing** will be copied. (Note, this differs slightly
2793 from the behaviour of the lrmr_bytes2meid() function.)
2796 --------------------------------------------------------------------------------------------
2798 On success, the value RMR_OK is returned. If the string
2799 cannot be copied to the message, the return value will be one
2800 of the errors listed below.
2803 --------------------------------------------------------------------------------------------
2805 If the return value is not RMR_OK, then it will be set to one
2806 of the values below.
2812 The message, or an internal portion of the message, was
2813 corrupted or the pointer was invalid.
2818 The length passed in was larger than the maximum length of
2819 the field; only a portion of the source bytes were copied.
2823 --------------------------------------------------------------------------------------------
2827 --------------------------------------------------------------------------------------------
2829 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
2830 rmr_get_meid(3), rmr_get_rcvfd(3), rmr_payload_size(3),
2831 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
2832 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
2833 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
2834 rmr_bytes2meid(3), rmr_wh_open(3), rmr_wh_send_msg(3)
2838 --------------------------------------------------------------------------------------------
2843 --------------------------------------------------------------------------------------------
2848 #include <rmr/rmr.h>
2849 int rmr_str2xact( rmr_mbuf_t* mbuf, unsigned char* src, int len )
2854 --------------------------------------------------------------------------------------------
2856 The rmr_str2xact function will copy the string pointed to by
2857 src to the transaction ID (xaction) field in the given
2858 message. The field is a fixed length, gated by the constant
2859 RMR_MAX_XID and if string length is larger than this value,
2860 then **nothing** will be copied. (Note, this differs slightly
2861 from the behaviour of the lrmr_bytes2xact() function.)
2865 --------------------------------------------------------------------------------------------
2867 On success, the value RMR_OK is returned. If the string
2868 cannot be copied to the message, the return value will be
2869 one of the errors listed below.
2872 --------------------------------------------------------------------------------------------
2874 If the return value is not RMR_OK, then it will be set to
2875 one of the values below.
2880 The message, or an internal portion of the message, was
2881 corrupted or the pointer was invalid.
2886 The length passed in was larger than the maximum length of
2887 the field; only a portion of the source bytes were copied.
2891 --------------------------------------------------------------------------------------------
2895 --------------------------------------------------------------------------------------------
2897 rmr_alloc_msg(3), rmr_bytes2meid(3), rmr_bytes2xact(3),
2898 rmr_call(3), rmr_free_msg(3), rmr_get_meid(3),
2899 rmr_get_rcvfd(3), rmr_get_xact(3), rmr_payload_size(3),
2900 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
2901 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
2902 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
2903 rmr_str2meid(3), rmr_wh_open(3), rmr_wh_send_msg(3)
2907 --------------------------------------------------------------------------------------------
2909 RMR support functions
2912 --------------------------------------------------------------------------------------------
2917 #include <rmr/rmr.h>
2918 #include <rmr/ring_inline.h>
2919 char* rmr_fib( char* fname );
2920 int rmr_has_str( char const* buf, char const* str, char sep, int max );
2921 int rmr_tokenise( char* buf, char** tokens, int max, char sep );
2922 void* rmr_mk_ring( int size );
2923 void rmr_ring_free( void* vr );
2924 static inline void* rmr_ring_extract( void* vr )
2925 static inline int rmr_ring_insert( void* vr, void* new_data )
2930 --------------------------------------------------------------------------------------------
2932 These functions support the RMR library, and are made
2933 available to user applications as some (e.g. route table
2934 generators) might need and/or want to make use of them. The
2935 rmr_fib function accepts a file name and reads the entire
2936 file into a single buffer. The intent is to provide an easy
2937 way to load a static route table without a lot of buffered
2940 The rmr_has_str function accepts a *buffer* containing a set
2941 of delimited tokens (e.g. foo,bar,goo) and returns true if
2942 the target string, *str,* matches one of the tokens. The
2943 *sep* parameter provides the separation character in the
2944 buffer (e.g a comma) and *max* indicates the maximum number
2945 of tokens to split the buffer into before checking.
2947 The rmr_tokenise function is a simple tokeniser which splits
2948 *buf* into tokens at each occurrence of *sep*. Multiple
2949 occurrences of the separator character (e.g. a,,b) result in
2950 a nil token. Pointers to the tokens are placed into the
2951 *tokens* array provided by the caller which is assumed to
2952 have at least enough space for *max* entries.
2954 The rmr_mk_ring function creates a buffer ring with *size*
2957 The rmr_ring_free function accepts a pointer to a ring
2958 context and frees the associated memory.
2960 The rmr_ring_insert and rmr_ring_extract functions are
2961 provided as static inline functions via the
2962 *rmr/ring_inline.h* header file. These functions both accept
2963 the ring *context* returned by mk_ring, and either insert a
2964 pointer at the next available slot (tail) or extract the data
2968 --------------------------------------------------------------------------------------------
2970 The following are the return values for each of these
2973 The rmr_fib function returns a pointer to the buffer
2974 containing the contents of the file. The buffer is terminated
2975 with a single nil character (0) making it a legitimate C
2976 string. If the file was empty or nonexistent, a buffer with
2977 an immediate nil character. If it is important to the calling
2978 programme to know if the file was empty or did not exist, the
2979 caller should use the system stat function call to make that
2982 The rmr_has_str function returns 1 if *buf* contains the
2983 token referenced by &ita and false (0) if it does not. On
2984 error, a -1 value is returned and errno is set accordingly.
2986 The rmr_tokenise function returns the actual number of token
2987 pointers placed into *tokens*
2989 The rmr_mk_ring function returns a void pointer which is the
2990 *context* for the ring.
2992 The rmr_ring_insert function returns 1 if the data was
2993 successfully inserted into the ring, and 0 if the ring is
2994 full and the pointer could not be deposited.
2996 The rmr_ring_extract will return the data which is at the
2997 head of the ring, or NULL if the ring is empty.
3000 --------------------------------------------------------------------------------------------
3002 Not many of these functions set the value in errno, however
3003 the value may be one of the following:
3008 Parameter(s) passed to the function were not valid.
3012 --------------------------------------------------------------------------------------------
3016 --------------------------------------------------------------------------------------------
3018 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
3019 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
3020 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
3024 --------------------------------------------------------------------------------------------
3029 --------------------------------------------------------------------------------------------
3034 #include <rmr/rmr.h>
3035 rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to );
3040 --------------------------------------------------------------------------------------------
3042 The rmr_torcv_msg function will pause for *ms_to*
3043 milliseconds waiting for a message to arrive. If a message
3044 arrives before the timeout expires the message buffer
3045 returned will have a status of RMR_OK and the payload will
3046 contain the data received. If the timeout expires before the
3047 message is received, the status will have the value
3048 RMR_ERR_TIMEOUT. When a received message is returned the
3049 message buffer will also contain the message type and length
3050 set by the sender. If messages were queued while waiting for
3051 the response to a previous invocation of rmr_call, the oldest
3052 message is removed from the queue and returned without delay.
3054 The *vctx* pointer is the pointer returned by the rmr_init
3055 function. *Old_msg* is a pointer to a previously used message
3056 buffer or NULL. The ability to reuse message buffers helps to
3057 avoid alloc/free cycles in the user application. When no
3058 buffer is available to supply, the receive function will
3062 --------------------------------------------------------------------------------------------
3064 The function returns a pointer to the rmr_mbuf_t structure
3065 which references the message information (state, length,
3066 payload), or a NULL pointer in the case of an extreme error.
3069 --------------------------------------------------------------------------------------------
3071 The *state* field in the message buffer will be one of the
3078 The message buffer (payload) references the received data.
3083 The first call to this function must initialise an
3084 underlying system notification mechanism. On failure, this
3085 error is returned and errno will have the system error
3086 status set. If this function fails to intialise, the poll
3087 mechansim, it is likely that message receives will never
3093 The timeout expired before a complete message was
3094 received. All other fields in the message buffer are not
3100 A message was received, but it had no payload. All other
3101 fields in the message buffer are not valid.
3108 Parameter(s) passed to the function were not valid.
3113 The underlying message transport is unable to process the
3119 The underlying message transport is unable to process the
3125 The underlying message transport is unable to process the
3131 The underlying message transport is unable to process the
3137 The underlying message transport is unable to process the
3143 The underlying message transport is unable to process the
3149 The underlying message transport is unable to process the
3154 --------------------------------------------------------------------------------------------
3158 --------------------------------------------------------------------------------------------
3160 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
3161 rmr_get_rcvfd(3), rmr_init(3), rmr_payload_size(3),
3162 rmr_rcv_msg(3), rmr_send_msg(3), rmr_rcv_specific(3),
3163 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
3164 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
3168 --------------------------------------------------------------------------------------------
3173 --------------------------------------------------------------------------------------------
3178 #include <rmr/rmr.h>
3179 int rmr_trace_ref( rmr_mbuf_t* mbuf, int* sizeptr )
3184 --------------------------------------------------------------------------------------------
3186 The rmr_trace_ref function return a pointer to the trace area
3187 in the message, and optionally populate the user programme
3188 supplied size integer with the trace area size, if *sizeptr*
3192 --------------------------------------------------------------------------------------------
3194 On success, a void pointer to the trace area of the message
3195 is returned. A nil pointer is returned if the message has no
3196 trace data area allocated, or if the message itself is
3200 --------------------------------------------------------------------------------------------
3202 rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3),
3203 rmr_bytes2meid(3), rmr_call(3), rmr_free_msg(3),
3204 rmr_get_rcvfd(3), rmr_get_trlen(3), rmr_init(3),
3205 rmr_init_trace(3), rmr_payload_size(3), rmr_send_msg(3),
3206 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
3207 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
3208 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
3209 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3),
3214 --------------------------------------------------------------------------------------------
3219 --------------------------------------------------------------------------------------------
3224 #include <rmr/rmr.h>
3225 rmr_mbuf_t* rmr_tralloc_msg( void* vctx, int size,
3226 int trace_size, unsigned const char *tr_data );
3231 --------------------------------------------------------------------------------------------
3233 The rmr_alloc_msg function is used to allocate a buffer which
3234 the user programme can write into and then send through the a
3235 library. The buffer is allocated such that sending it
3236 requires no additional copying from the buffer as it passes
3237 through the underlying transport mechanism.
3239 The *size* parameter is used to set the payload length in the
3240 message and If it is 0, then the default size supplied on the
3241 *rmr_init* call will be used. In addition to allocating the
3242 payload, a space in the buffer is reserved for *trace* data
3243 (tr_size bytes), and the bytes pointed to by *tr_data* are
3244 copied into that portion of the message. The *vctx* parameter
3245 is the void context pointer that was returned by the
3246 *rmr_init* function.
3248 The pointer to the message buffer returned is a structure
3249 which has some user application visible fields; the structure
3250 is described in rmr.h, and is illustrated below.
3259 unsigned char* payload;
3260 unsigned char* xaction;
3269 Is the current buffer state. Following a call to
3270 rmr_send_msg the state indicates whether the buffer was
3271 successfully sent which determines exactly what the
3272 payload points to. If the send failed, the payload
3273 referenced by the buffer is the message that failed to
3274 send (allowing the application to attempt a
3275 retransmission). When the state is a_OK the buffer
3276 represents an empty buffer that the application may fill
3277 in in preparation to send.
3282 When sending a message, the application is expected to set
3283 this field to the appropriate message type value (as
3284 determined by the user programme). Upon send this value
3285 determines how the a library will route the message. For a
3286 buffer which has been received, this field will contain
3287 the message type that was set by the sending application.
3292 The application using a buffer to send a message is
3293 expected to set the length value to the actual number of
3294 bytes that it placed into the message. This is likely less
3295 than the total number of bytes that the message can carry.
3296 For a message buffer that is passed to the application as
3297 the result of a receive call, this will be the value that
3298 the sending application supplied and should indicate the
3299 number of bytes in the payload which are valid.
3304 The payload is a pointer to the actual received data. The
3305 user programme may read and write from/to the memory
3306 referenced by the payload up until the point in time that
3307 the buffer is used on a rmr_send, rmr_call or rmr_reply
3308 function call. Once the buffer has been passed back to a a
3309 library function the user programme should **NOT** make
3310 use of the payload pointer.
3315 The *xaction* field is a pointer to a fixed sized area in
3316 the message into which the user may write a transaction
3317 ID. The ID is optional with the exception of when the user
3318 application uses the rmr_call function to send a message
3319 and wait for the reply; the underlying a processing
3320 expects that the matching reply message will also contain
3321 the same data in the *xaction* field.
3325 --------------------------------------------------------------------------------------------
3327 The function returns a pointer to a rmr_mbuf structure, or
3331 --------------------------------------------------------------------------------------------
3337 Unable to allocate memory.
3341 --------------------------------------------------------------------------------------------
3343 rmr_alloc_msg(3), rmr_mbuf(3) rmr_call(3), rmr_free_msg(3),
3344 rmr_init(3), rmr_init_trace(3), rmr_get_trace(3),
3345 rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
3346 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
3347 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
3348 rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)
3352 --------------------------------------------------------------------------------------------
3357 --------------------------------------------------------------------------------------------
3362 #include <rmr/rmr.h>
3363 void rmr_close( void* vctx, rmr_whid_t whid )
3368 --------------------------------------------------------------------------------------------
3370 The rmr_wh_close function closes the wormhole associated with
3371 the wormhole id passed in. Future calls to rmr_wh_send_msg
3372 with this ID will fail.
3374 The underlying TCP connection to the remote endpoint is
3375 **not** closed as this session may be reqruired for
3376 regularlly routed messages (messages routed based on message
3377 type). There is no way to force a TCP session to be closed at
3381 --------------------------------------------------------------------------------------------
3383 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
3384 rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3),
3385 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
3386 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
3387 rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_open(3),
3392 --------------------------------------------------------------------------------------------
3397 --------------------------------------------------------------------------------------------
3402 #include <rmr/rmr.h>
3403 void* rmr_wh_open( void* vctx, char* target )
3408 --------------------------------------------------------------------------------------------
3410 The rmr_wh_open function creates a direct link for sending, a
3411 wormhole, to another RMr based process. Sending messages
3412 through a wormhole requires that the connection be
3413 established overtly by the user application (via this
3414 function), and that the ID returned by rmr_wh_open be passed
3415 to the rmr_wh_send_msg function.
3417 *Target* is the *name* or *IP-address* combination of the
3418 processess that the wormhole should be connected to. *Vctx*
3419 is the RMr void context pointer that was returned by the
3422 When invoked, this function immediatly attempts to connect to
3423 the target process. If the connection cannot be established,
3424 an error is returned to the caller, and no direct messages
3425 can be sent to the target. Once a wormhole is connected, the
3426 underlying transport mechanism (e.g. NNG) will provide
3427 reconnects should the connection be lost, however the
3428 handling of messages sent when a connection is broken is
3429 undetermined as each underlying transport mechanism may
3430 handle buffering and retries differently.
3433 --------------------------------------------------------------------------------------------
3435 The rmr_wh_open function returns a type rmr_whid_t which must
3436 be passed to the rmr_wh_send_msg function when sending a
3437 message. The id may also be tested to determine success or
3438 failure of the connection by using the RMR_WH_CONNECTED macro
3439 and passing the ID as the parameter; a result of 1 indicates
3440 that the connection was esablished and that the ID is valid.
3443 --------------------------------------------------------------------------------------------
3445 The following error values are specifically set by this RMR
3446 function. In some cases the error message of a system call is
3447 propagated up, and thus this list might be incomplete.
3452 A parameter passed was not valid.
3456 The user applicarion does not have the ability to
3457 establish a wormhole to the indicated target (or maybe any
3462 The connection was refused.
3466 --------------------------------------------------------------------------------------------
3473 rmc = rmr_init( "43086", 4096, 0 ); // init context
3474 wh = rmr_wh_open( rmc, "localhost:6123" );
3475 if( !RMR_WH_CONNECTED( wh ) ) {
3476 f fprintf( stderr, "unable to connect wormhole: %s\\n",
3477 strerror( errno ) );
3483 --------------------------------------------------------------------------------------------
3485 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
3486 rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3),
3487 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
3488 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
3489 rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_send_msg(3),
3494 --------------------------------------------------------------------------------------------
3499 --------------------------------------------------------------------------------------------
3504 #include <rmr/rmr.h>
3505 rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t id, rmr_mbuf_t* msg );
3510 --------------------------------------------------------------------------------------------
3512 The rmr_wh_send_msg function accepts a message buffer from
3513 the user application and attempts to send it using the
3514 wormhole ID provided (id). Unlike *rmr_send_msg,* this
3515 function attempts to send the message directly to a process
3516 at the other end of a wormhole which was created with
3517 *rmr_wh-open().* When sending message via wormholes, the
3518 normal RMr routing based on message type is ignored, and the
3519 caller may leave the message type unspecified in the message
3520 buffer (unless it is needed by the receiving process).
3522 The message buffer (msg) used to send is the same format as
3523 used for regular RMr send and reply to sender operations,
3524 thus any buffer allocated by these means, or calls to
3525 *rmr_rcv_msg()* can be passed to this function.
3528 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3530 The send operations in RMr will retry *soft* send failures
3531 until one of three conditions occurs:
3537 The message is sent without error
3542 The underlying transport reports a * hard * failure
3547 The maximum number of retry loops has been attempted
3550 A retry loop consists of approximately 1000 send attemps **
3551 without** any intervening calls to * sleep() * or * usleep().
3552 * The number of retry loops defaults to 1, thus a maximum of
3553 1000 send attempts is performed before returning to the user
3554 application. This value can be set at any point after RMr
3555 initialisation using the * rmr_set_stimeout() * function
3556 allowing the user application to completely disable retires
3557 (set to 0), or to increase the number of retry loops.
3559 Transport Level Blocking
3560 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3562 The underlying transport mechanism used to send messages is
3563 configured in *non-blocking* mode. This means that if a
3564 message cannot be sent immediately the transport mechanism
3565 will **not** pause with the assumption that the inability to
3566 send will clear quickly (within a few milliseconds). This
3567 means that when the retry loop is completely disabled (set to
3568 0), that the failure to accept a message for sending by the
3569 underlying mechanisms (software or hardware) will be reported
3570 immediately to the user application.
3572 It should be noted that depending on the underlying transport
3573 mechanism being used, it is extremly possible that during
3574 normal operations that retry conditions are very likely to
3575 happen. These are completely out of RMr's control, and there
3576 is nothing that RMr can do to avoid or midigate these other
3577 than by allowing RMr to retry the send operation, and even
3578 then it is possible (e.g. during connection reattempts), that
3579 a single retry loop is not enough to guarentee a successful
3583 --------------------------------------------------------------------------------------------
3585 On success, a new message buffer, with an empty payload, is
3586 returned for the application to use for the next send. The
3587 state in this buffer will reflect the overall send operation
3588 state and should be RMR_OK.
3590 If the state in the returned buffer is anything other than
3591 RMR_OK, the user application may need to attempt a
3592 retransmission of the message, or take other action depending
3593 on the setting of errno as described below.
3595 In the event of extreme failure, a NULL pointer is returned.
3596 In this case the value of errno might be of some use, for
3597 documentation, but there will be little that the user
3598 application can do other than to move on.
3601 --------------------------------------------------------------------------------------------
3603 The following values may be passed back in the *state* field
3604 of the returned message buffer.
3610 The wormhole ID passed in was not associated with an open
3611 wormhole, or was out of range for a valid ID.
3615 No wormholes exist, further attempt to validate the ID are
3620 The message buffer pointer did not refer to a valid
3625 The header in the message buffer was not valid or
3629 The following values may be assigned to errno on failure.
3634 Parameter(s) passed to the function were not valid, or the
3635 underlying message processing environment was unable to
3636 interpret the message.
3641 The header information in the message buffer was invalid.
3646 No known endpoint for the message could be found.
3651 The underlying transport refused to accept the message
3652 because of a size value issue (message was not attempted
3658 The message referenced by the message buffer is corrupt
3659 (NULL pointer or bad internal length).
3664 Internal RMR error; information provided to the message
3665 transport environment was not valid.
3670 Sending was not supported by the underlying message
3676 The device is not in a state that can accept the message.
3681 The device is not able to accept a message for sending.
3682 The user application should attempt to resend.
3687 The operation was interrupted by delivery of a signal
3688 before the message was sent.
3693 The underlying message environment timed out during the
3699 The underlying message environment is in a shutdown state.
3703 --------------------------------------------------------------------------------------------
3705 The following is a simple example of how the a wormhole is
3706 created (rmr_wh_open) and then how rmr_wh_send_msg function
3707 is used to send messages. Some error checking is omitted for
3713 #include <rmr/rmr.h> .// system headers omitted for clarity
3715 rmr_whid_t whid = -1; // wormhole id for sending
3716 void* mrc; //msg router context
3718 rmr_mbuf_t* sbuf; // send buffer
3720 mrc = rmr_init( "43086", RMR_MAX_RCV_BYTES, RMRFL_NONE );
3722 fprintf( stderr, "[FAIL] unable to initialise RMr environment\\n" );
3725 while( ! rmr_ready( mrc ) ) { e i// wait for routing table info
3728 sbuf = rmr_alloc_msg( mrc, 2048 );
3731 whid = rmr_wh_open( mrc, "localhost:6123" ); // open fails if endpoint refuses conn
3732 w if( RMR_WH_CONNECTED( wh ) ) {
3733 snprintf( sbuf->payload, 1024, "periodic update from sender: %d", count++ );
3734 sbuf->len = strlen( sbuf->payload );
3735 sbuf = rmr_wh_send_msg( mrc, whid, sbuf );
3745 --------------------------------------------------------------------------------------------
3747 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
3748 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
3749 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
3750 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
3751 rmr_set_stimeout(3), rmr_wh_open(3), rmr_wh_close(3)