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 entity ID (meid) field in the message.
208 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 entity 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 *max_msg_size* parameter is used
1184 to allocate receive buffers and is the maximum message size
1185 which the application expects to receive. This value is the
1186 sum of **both** the maximum payload size **and** the maximum
1187 trace data size. This value is also used as the default
1188 message size when allocating message buffers. Messages
1189 arriving which are longer than the given maximum will be
1190 dropped without notification to the application. A warning is
1191 written to standard error for the first message which is too
1192 large on each connection.
1194 *Flags* allows for selection of some RMr options at the time
1195 of initialisation. These are set by ORing RMRFL constants
1196 from the RMr header file. Currently the following flags are
1208 The route table collector thread is not to be started.
1209 This should only be used by the route table generator
1210 application if it is based on RMr.
1215 Enable multi-threaded call support.
1217 &ditem Some underlying transport providers (e.g. SI95)
1218 enable locking to be turned off if the user application is
1219 single threaded, or otherwise can guarantee that RMR
1220 functions will not be invoked concurrently from different
1221 threads. Turning off locking can help make message receipt
1222 more efficient. If this flag is set when the underlying
1223 transport does not support disabling locks, it will be
1227 Multi-threaded Calling
1228 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1230 The support for an application to issue a *blocking call* by
1231 the rmr_call() function was limited such that only user
1232 applications which were operating in a single thread could
1233 safely use the function. Further, timeouts were message count
1234 based and not time unit based. Multi-threaded call support
1235 adds the ability for a user application with multiple threads
1236 to invoke a blocking call function with the guarantee that
1237 the correct response message is delivered to the thread. The
1238 additional support is implemented with the *rmr_mt_call()*
1239 and *rmr_mt_rcv()* function calls.
1241 Multi-threaded call support requires the user application to
1242 specifically enable it when RMr is initialised. This is
1243 necessary because a second, dedicated, receiver thread must
1244 be started, and requires all messages to be examined and
1245 queued by this thread. The additional overhead is minimal,
1246 queuing information is all in the RMr message header, but as
1247 an additional process is necessary the user application must
1248 "opt in" to this approach.
1252 --------------------------------------------------------------------------------------------
1254 As a part of the initialisation process rmr_init will look
1255 into the available environment variables to influence it's
1256 setup. The following variables will be used when found.
1262 Assumes this is the filename of the seed route table file
1263 to use. In normal situations, the library will wait for an
1264 update from the route table generator (expected within a
1265 few seconds of initialisation) before being able to send
1266 messages. However, in some situations where a bootstrap
1267 table is necessary, this is the means to supply it to the
1273 The route table generator assumes that RMr is listening on
1274 a well known port (4561) by default, but this environment
1275 variable can be used to change the listening port if
1276 needed. The value of the variable is expected to be just
1281 --------------------------------------------------------------------------------------------
1283 The rmr_init function returns a void pointer (a contex if you
1284 will) that is passed as the first parameter to nearly all
1285 other RMR functions. If rmr_init is unable to properly
1286 initialise the environment, NULL is returned and errno is set
1287 to an appropriate value.
1290 --------------------------------------------------------------------------------------------
1292 The following error values are specifically set by this RMR
1293 function. In some cases the error message of a system call is
1294 propagated up, and thus this list might be incomplete.
1299 Unable to allocate memory.
1303 --------------------------------------------------------------------------------------------
1309 rmr_mbuf* buf = NULL;
1310 uh = rmr_init( "43086", 4096, 0 );
1311 buf = rmr_rcv_msg( uh, buf );
1316 --------------------------------------------------------------------------------------------
1318 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
1319 rmr_get_rcvfd(3), rmr_mt_call(3), rmr_mt_rcv(3),
1320 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
1321 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
1322 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
1327 --------------------------------------------------------------------------------------------
1332 --------------------------------------------------------------------------------------------
1337 #include <rmr/rmr.h>
1338 void* rmr_init_trace( void* ctx )
1343 --------------------------------------------------------------------------------------------
1345 The rmr_init_trace function establishes the default trace
1346 space placed in each message buffer allocated with
1347 rmr_alloc_msg(). If this function is never called, then no
1348 trace space is allocated by default into any message buffer.
1350 Trace space allows the user application to pass some trace
1351 token, or other data with the message, but outside of the
1352 payload. Trace data may be added to any message with
1353 rmr_set_trace(), and may be extracted from a message with
1354 rmr_get_trace(). The number of bytes that a message contains
1355 for/with trace data can be determined by invoking
1358 This function may be safely called at any time during the
1359 life of the user programme to (re)set the default trace space
1360 reserved. If the user programme needs to allocate a message
1361 with trace space of a different size than is allocated by
1362 default, without fear of extra overhead of reallocating a
1363 message later, the rmr_tralloc_msg() function can be used.
1366 --------------------------------------------------------------------------------------------
1368 A value of 1 is returned on success, and 0 on failure. A
1369 failure indicates that the RMr context (a void pointer passed
1370 to this function was not valid.
1373 --------------------------------------------------------------------------------------------
1375 rmr_alloc_msg(3), rmr_tr_alloc_msg(3), rmr_call(3),
1376 rmr_free_msg(3), rmr_get_rcvfd(3), rmr_get_trace(3),
1377 rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
1378 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1379 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
1380 rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)
1384 --------------------------------------------------------------------------------------------
1389 --------------------------------------------------------------------------------------------
1394 #include <rmr/rmr.h>
1395 extern rmr_mbuf_t* rmr_mt_call( void* vctx, rmr_mbuf_t* msg, int id, int timeout );
1400 --------------------------------------------------------------------------------------------
1402 The rmr_mt_call function sends the user application message
1403 to a remote endpoint, and waits for a corresponding response
1404 message before returning control to the user application. The
1405 user application supplies a completed message buffer, as it
1406 would for a rmr_send_msg call, but unlike with a send, the
1407 buffer returned will have the response from the application
1408 that received the message. The thread invoking the
1409 *rmr_mt_call()* will block until a message arrives or until
1410 *timeout* milliseconds has passed; which ever comes first.
1411 Using a timeout value of zero (0) will cause the thread to
1412 block without a timeout.
1414 The *id* supplied as the third parameter is an integer in the
1415 range of 2 through 255 inclusive. This is a caller defined
1416 "thread number" and is used to match the response message
1417 with the correct user application thread. If the ID value is
1418 not in the proper range, the attempt to make the call will
1421 Messages which are received while waiting for the response
1422 are queued on a *normal* receive queue and will be delivered
1423 to the user application with the next invocation of
1424 *rmr_mt_rcv()* or *rmr_rvv_msg().* by RMR, and are returned
1425 to the user application when rmr_rcv_msg is invoked. These
1426 messages are returned in th order received, one per call to
1429 NOTE: Currently the multi-threaded functions are supported
1430 only when the NNG transport mechanism is being used. It will
1431 not be possible to link a programme using the Nanomsg version
1432 of the library when references to this function are present.
1435 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1437 The user application is responsible for setting the value of
1438 the transaction ID field before invoking *rmr_mt_call.* The
1439 transaction ID is a RMR_MAX_XID byte field that is used to
1440 match the response message when it arrives. RMr will compare
1441 **all** of the bytes in the field, so the caller must ensure
1442 that they are set correctly to avoid missing the response
1443 message. (The application which returns the response message
1444 is also expected to ensure that the return buffer has the
1445 matching transaction ID. This can be done transparently if
1446 the application uses the *rmr_rts_msg()* function and does
1447 not adjust the transaction ID.
1450 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1452 The send operations in RMr will retry *soft* send failures
1453 until one of three conditions occurs:
1459 The message is sent without error
1464 The underlying transport reports a * hard * failure
1469 The maximum number of retry loops has been attempted
1472 A retry loop consists of approximately 1000 send attemps **
1473 without** any intervening calls to * sleep() * or * usleep().
1474 * The number of retry loops defaults to 1, thus a maximum of
1475 1000 send attempts is performed before returning to the user
1476 application. This value can be set at any point after RMr
1477 initialisation using the * rmr_set_stimeout() * function
1478 allowing the user application to completely disable retires
1479 (set to 0), or to increase the number of retry loops.
1481 Transport Level Blocking
1482 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1484 The underlying transport mechanism used to send messages is
1485 configured in *non-blocking* mode. This means that if a
1486 message cannot be sent immediately the transport mechanism
1487 will **not** pause with the assumption that the inability to
1488 send will clear quickly (within a few milliseconds). This
1489 means that when the retry loop is completely disabled (set to
1490 0), that the failure to accept a message for sending by the
1491 underlying mechanisms (software or hardware) will be reported
1492 immediately to the user application.
1494 It should be noted that depending on the underlying transport
1495 mechanism being used, it is extremly possible that during
1496 normal operations that retry conditions are very likely to
1497 happen. These are completely out of RMr's control, and there
1498 is nothing that RMr can do to avoid or midigate these other
1499 than by allowing RMr to retry the send operation, and even
1500 then it is possible (e.g. during connection reattempts), that
1501 a single retry loop is not enough to guarentee a successful
1505 --------------------------------------------------------------------------------------------
1507 The rmr_mt_call function returns a pointer to a message
1508 buffer with the state set to reflect the overall state of
1509 call processing. If the state is RMR_OK then the buffer
1510 contains the response message; otherwise the state indicates
1511 the error encountered while attempting to send the message.
1513 If no response message is received when the timeout period
1514 has expired, a nil pointer will be returned (NULL).
1517 --------------------------------------------------------------------------------------------
1519 These values are reflected in the state field of the returned
1526 The call was successful and the message buffer references
1527 the response message.
1532 An argument passed to the function was invalid.
1537 The call failed and the value of *errno,* as described
1538 below, should be checked for the specific reason.
1543 An endpoint associated with the message type could not be
1544 found in the route table.
1549 The underlying transport mechanism was unable to accept
1550 the message for sending. The user application can retry
1551 the call operation if appropriate to do so.
1554 The global "variable" *errno* will be set to one of the
1555 following values if the overall call processing was not
1562 Too many messages were queued before receiving the
1568 The queued message ring is full, messages were dropped
1573 A parameter was not valid
1578 The underlying message system wsa interrupted or the
1579 device was busy; the message was **not** sent, and user
1580 application should call this function with the message
1585 --------------------------------------------------------------------------------------------
1587 The following code bit shows one way of using the rmr_mt_call
1588 function, and illustrates how the transaction ID must be set.
1593 int retries_left = 5; // max retries on dev not available
1594 static rmr_mbuf_t* mbuf = NULL; // response msg
1595 msg_t* pm; // private message (payload)
1596 m// get a send buffer and reference the payload
1597 mbuf = rmr_alloc_msg( mr, RMR_MAX_RCV_BYTES );
1598 pm = (msg_t*) mbuf->payload;
1599 p// generate an xaction ID and fill in payload with data and msg type
1600 rmr_bytes2xact( mbuf, xid, RMR_MAX_XID );
1601 snprintf( pm->req, sizeof( pm->req ), "{ \\"req\\": \\"num users\\"}" );
1602 mbuf->mtype = MT_USR_RESP;
1604 msg = rmr_mt_call( mr, msg, my_id, 100 ); e :// wait up to 100ms
1605 if( ! msg ) { // probably a timeout and no msg received
1606 return NULL; // let errno trickle up
1608 if( mbuf->state != RMR_OK ) {
1609 while( retries_left-- > 0 && // loop as long as eagain
1610 mbuf->state == RMR_ERR_RETRY &&
1611 (msg = rmr_mt_call( mr, msg )) != NULL &&
1612 mbuf->state != RMR_OK ) {
1613 usleep( retry_delay );
1616 if( mbuf == NULL || mbuf->state != RMR_OK ) {
1617 rmr_free_msg( mbuf ); // safe if nil
1621 // do something with mbuf
1626 --------------------------------------------------------------------------------------------
1628 rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3),
1629 rmr_mt_rcv(3), rmr_payload_size(3), rmr_send_msg(3),
1630 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1631 rmr_ready(3), rmr_fib(3), rmr_has_str(3),
1632 rmr_set_stimeout(3), rmr_tokenise(3), rmr_mk_ring(3),
1637 --------------------------------------------------------------------------------------------
1642 --------------------------------------------------------------------------------------------
1647 #include <rmr/rmr.h>
1648 rmr_mbuf_t* rmr_mt_rcv( void* vctx, rmr_mbuf_t* old_msg, int timeout );
1653 --------------------------------------------------------------------------------------------
1655 The rmr_mt_rcv function blocks until a message is received,
1656 or the timeout period (milliseconds) has passed. The result
1657 is an RMr message buffer which references a received message.
1658 In the case of a timeout the state will be reflected in an
1659 "empty buffer" (if old_msg was not nil, or simply with the
1660 return of a nil pointer. If a timeout value of zero (0) is
1661 given, then the function will block until the next message
1664 The *vctx* pointer is the pointer returned by the rmr_init
1665 function. *Old_msg* is a pointer to a previously used message
1666 buffer or NULL. The ability to reuse message buffers helps to
1667 avoid alloc/free cycles in the user application. When no
1668 buffer is available to supply, the receive function will
1671 The *old_msg* parameter allows the user to pass a previously
1672 generated RMr message back to RMr for reuse. Optionally, the
1673 user application may pass a nil pointer if no reusable
1674 message is available. When a timeout occurs, and old_msg was
1675 not nil, the state will be returned by returning a pointer to
1676 the old message with the state set.
1678 It is possible to use the *rmr_rcv_msg()* function instead of
1679 this function. Doing so might be advantagous if the user
1680 programme does not always start the multi-threaded mode and
1681 the use of *rmr_rcv_msg()* would make the flow of the code
1682 more simple. The advantags of using this function are the
1683 ability to set a timeout without using epoll, and a small
1684 performance gain (if multi-threaded mode is enabled, and the
1685 *rmr_rcv_msg()* function is used, it simply invokes this
1686 function without a timeout value, thus there is the small
1687 cost of a second call that results). Similarly, the
1688 *rmr_torcv_msg()* call can be used when in multi-threaded
1689 mode with the same "pass through" overhead to using this
1692 NOTE: Currently the multi-threaded functions are supported
1693 only when the NNG transport mechanism is being used. It will
1694 not be possible to link a programme using the nanomsg version
1695 of the library when references to this function are present.
1698 --------------------------------------------------------------------------------------------
1700 When a message is received before the timeout period expires,
1701 a pointer to the RMr message buffer which describes the
1702 message is returned. This will, with a high probability, be a
1703 different message buffer than *old_msg;* the user application
1704 should not continue to use *old_msg* after it is passed to
1707 In the event of a timeout the return value will be the old
1708 msg with the state set, or a nil pointer if no old message
1712 --------------------------------------------------------------------------------------------
1714 The *state* field in the message buffer will be set to one of
1715 the following values:
1721 The message was received without error.
1726 A parameter passed to the function was not valid (e.g. a
1727 nil pointer). indicate either RMR_OK or RMR_ERR_EMPTY if
1728 an empty message was received.
1733 The message received had no associated data. The length of
1734 the message will be 0.
1739 The multi-threaded option was not enabled when RMr was
1740 initialised. See the man page for *rmr_init()* for
1746 A hard error occurred preventing the receive from
1749 When a nil pointer is returned, or any other state value was
1750 set in the message buffer, errno will be set to one of the
1757 Parameter(s) passed to the function were not valid.
1762 The underlying message transport is unable to process the
1768 The underlying message transport is unable to process the
1774 The underlying message transport is unable to process the
1780 The underlying message transport is unable to process the
1786 The underlying message transport is unable to process the
1792 The underlying message transport is unable to process the
1798 The underlying message transport is unable to process the
1803 --------------------------------------------------------------------------------------------
1809 rmr_mbuf_t* mbuf = NULL; // received msg
1810 msg = rmr_mt_recv( mr, mbuf, 100 ); // wait up to 100ms
1812 switch( msg->state ) {
1814 printf( "got a good message\\n" );
1817 printf( "received timed out\\n" );
1820 printf( "receive error: %d\\n", mbuf->state );
1824 printf( "receive timeout (nil)\\n" );
1830 --------------------------------------------------------------------------------------------
1832 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
1833 rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3),
1834 rmr_mt_call(3), rmr_payload_size(3), rmr_send_msg(3),
1835 rmr_torcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1836 rmr_ready(3), rmr_ring_free(3), rmr_torcv_msg(3)
1840 --------------------------------------------------------------------------------------------
1845 --------------------------------------------------------------------------------------------
1850 #include <rmr/rmr.h>
1851 int rmr_payload_size( rmr_mbuf_t* msg );
1856 --------------------------------------------------------------------------------------------
1858 Given a message buffer, this function returns the amount of
1859 space (bytes) available for the user application to consume
1860 in the message payload. This is different than the message
1861 length available as a field in the message buffer.
1864 --------------------------------------------------------------------------------------------
1866 The number of bytes available in the payload.
1869 --------------------------------------------------------------------------------------------
1875 Parameter(s) passed to the function were not valid.
1879 --------------------------------------------------------------------------------------------
1881 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
1882 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
1883 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
1884 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
1888 --------------------------------------------------------------------------------------------
1893 --------------------------------------------------------------------------------------------
1898 #include <rmr/rmr.h>
1899 rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg );
1904 --------------------------------------------------------------------------------------------
1906 The rmr_rcv_msg function blocks until a message is received,
1907 returning the message to the caller via a pointer to a
1908 rmr_mbuf_t structure type. If messages were queued while
1909 waiting for the response to a previous invocation of
1910 rmr_call, the oldest message is removed from the queue and
1911 returned without delay.
1913 The *vctx* pointer is the pointer returned by the rmr_init
1914 function. *Old_msg* is a pointer to a previously used message
1915 buffer or NULL. The ability to reuse message buffers helps to
1916 avoid alloc/free cycles in the user application. When no
1917 buffer is available to supply, the receive function will
1921 --------------------------------------------------------------------------------------------
1923 The function returns a pointer to the rmr_mbuf_t structure
1924 which references the message information (state, length,
1925 payload), or a NULL pointer in the case of an extreme error.
1928 --------------------------------------------------------------------------------------------
1930 The *state* field in the message buffer will indicate either
1931 RMR_OK or RMR_ERR_EMPTY if an empty message was received. If
1932 a nil pointer is returned, or any other state value was set
1933 in the message buffer, errno will be set to one of the
1940 Parameter(s) passed to the function were not valid.
1945 The underlying message transport is unable to process the
1951 The underlying message transport is unable to process the
1957 The underlying message transport is unable to process the
1963 The underlying message transport is unable to process the
1969 The underlying message transport is unable to process the
1975 The underlying message transport is unable to process the
1981 The underlying message transport is unable to process the
1986 --------------------------------------------------------------------------------------------
1990 --------------------------------------------------------------------------------------------
1992 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
1993 rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3),
1994 rmr_payload_size(3), rmr_send_msg(3), rmr_torcv_msg(3),
1995 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
1996 rmr_ring_free(3), rmr_torcv_msg(3)
2000 --------------------------------------------------------------------------------------------
2005 --------------------------------------------------------------------------------------------
2010 #include <rmr/rmr.h>
2011 int rmr_ready( void* vctx );
2016 --------------------------------------------------------------------------------------------
2018 The rmr_ready function checks to see if a routing table has
2019 been successfully received and installed. The return value
2020 indicates the state of readiness.
2023 --------------------------------------------------------------------------------------------
2025 A return value of 1 (true) indicates that the routing table
2026 is in place and attempts to send messages can be made. When 0
2027 is returned (false) the routing table has not been received
2028 and thus attempts to send messages will fail with *no
2032 --------------------------------------------------------------------------------------------
2034 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2035 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
2036 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_fib(3),
2037 rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
2042 --------------------------------------------------------------------------------------------
2047 --------------------------------------------------------------------------------------------
2052 #include <rmr/rmr.h>
2053 extern rmr_mbuf_t* rmr_realloc_payload( rmr_mbuf_t* msg, int new_len, int copy, int clone );
2058 --------------------------------------------------------------------------------------------
2060 The rmr_realloc_payload function will return a pointer to an
2061 RMR message buffer struct (rmr_mbuf_t) which has a payload
2062 large enough to accomodate *new_len* bytes. If necessary, the
2063 underlying payload is reallocated, and the bytes from the
2064 original payload are copied if the *copy* parameter is true
2065 (1). If the message passed in has a payload large enough,
2066 there is no additional memory allocation and copying.
2068 Cloning The Message Buffer
2069 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2071 This function can also be used to generate a separate copy of
2072 the original message, with the desired payload size, without
2073 destroying the original message buffer or the original
2074 payload. A standalone copy is made only when the *clone*
2075 parameter is true (1). When cloning, the payload is copied to
2076 the cloned message **only** if the *copy* parameter is true.
2078 Message Buffer Metadata
2079 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2081 The metadata in the original message buffer (message type,
2082 subscription ID, and payload length) will be preserved if the
2083 *copy* parameter is true. When this parameter is not true
2084 (0), then these values are set to the uninitialised value
2085 (-1) for type and ID, and the length is set to 0.
2088 --------------------------------------------------------------------------------------------
2090 The rmr_realloc_payload function returns a pointer to the
2091 message buffer with the payload which is large enough to hold
2092 *new_len* bytes. If the *clone* option is true, this will be
2093 a pointer to the newly cloned message buffer; the original
2094 message buffer pointer may still be used to referenced that
2095 message. It is the calling application's responsibility to
2096 free the memory associateed with both messages using the
2097 rmr_free_msg() function.
2099 When the *clone* option is not used, it is still good
2100 practice by the calling application to capture and use this
2101 reference as it is possible that the message buffer, and not
2102 just the payload buffer, was reallocated. In the event of an
2103 error, a nil pointer will be returned and the value of
2104 *errno* will be set to reflect the problem.
2107 --------------------------------------------------------------------------------------------
2109 These value of *errno* will reflect the error condition if a
2110 nil pointer is returned:
2116 Memory allocation of the new payload failed.
2121 The pointer passed in was nil, or refrenced an invalid
2122 message, or the required length was not valid.
2126 --------------------------------------------------------------------------------------------
2128 The following code bit illustrates how this function can be
2129 used to reallocate a buffer for a return to sender
2130 acknowledgement message which is larger than the message
2136 if( rmr_payload_size( msg ) < ack_sz ) { // received message too small for ack
2137 msg = rmr_realloc_payload( msg, ack_sz, 0, 0 ); // reallocate the message with a payload big enough
2139 fprintf( stderr, "[ERR] realloc returned a nil pointer: %s\\n", strerror( errno ) );
2141 } e// populate and send ack message
2148 --------------------------------------------------------------------------------------------
2150 rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3),
2151 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
2152 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
2153 rmr_fib(3), rmr_has_str(3), rmr_set_stimeout(3),
2154 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
2158 --------------------------------------------------------------------------------------------
2163 --------------------------------------------------------------------------------------------
2168 #include <rmr/rmr.h>
2169 rmr_mbuf_t* rmr_rts_msg( void* vctx, rmr_mbuf_t* msg );
2174 --------------------------------------------------------------------------------------------
2176 The rmr_rts_msg function sends a message returning it to the
2177 endpoint which sent the message rather than selecting an
2178 endpoint based on the message type and routing table. Other
2179 than this small difference, the behaviour is exactly the same
2183 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2185 The send operations in RMr will retry *soft* send failures
2186 until one of three conditions occurs:
2192 The message is sent without error
2197 The underlying transport reports a * hard * failure
2202 The maximum number of retry loops has been attempted
2205 A retry loop consists of approximately 1000 send attemps **
2206 without** any intervening calls to * sleep() * or * usleep().
2207 * The number of retry loops defaults to 1, thus a maximum of
2208 1000 send attempts is performed before returning to the user
2209 application. This value can be set at any point after RMr
2210 initialisation using the * rmr_set_stimeout() * function
2211 allowing the user application to completely disable retires
2212 (set to 0), or to increase the number of retry loops.
2214 Transport Level Blocking
2215 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2217 The underlying transport mechanism used to send messages is
2218 configured in *non-blocking* mode. This means that if a
2219 message cannot be sent immediately the transport mechanism
2220 will **not** pause with the assumption that the inability to
2221 send will clear quickly (within a few milliseconds). This
2222 means that when the retry loop is completely disabled (set to
2223 0), that the failure to accept a message for sending by the
2224 underlying mechanisms (software or hardware) will be reported
2225 immediately to the user application.
2227 It should be noted that depending on the underlying transport
2228 mechanism being used, it is extremly possible that during
2229 normal operations that retry conditions are very likely to
2230 happen. These are completely out of RMr's control, and there
2231 is nothing that RMr can do to avoid or midigate these other
2232 than by allowing RMr to retry the send operation, and even
2233 then it is possible (e.g. during connection reattempts), that
2234 a single retry loop is not enough to guarentee a successful
2238 --------------------------------------------------------------------------------------------
2240 When crafting a response based on a received message, the
2241 user application must take care not to write more bytes to
2242 the message payload than the allocated message has. In the
2243 case of a received message, it is possible that the response
2244 needs to be larger than the payload associated with the
2245 inbound message. In order to use the return to sender
2246 function, the source infomration in the orignal message must
2247 be present in the response; information which cannot be added
2248 to a message buffer allocated through the standard RMR
2249 allocation function. To allocate a buffer with a larger
2250 payload, and which retains the necessary sender data needed
2251 by this function, the *rmr_realloc_payload()* function must
2252 be used to extend the payload to a size suitable for the
2256 --------------------------------------------------------------------------------------------
2258 On success, a new message buffer, with an empty payload, is
2259 returned for the application to use for the next send. The
2260 state in this buffer will reflect the overall send operation
2261 state and should be RMR_OK.
2263 If the state in the returned buffer is anything other than
2264 UT_OK, the user application may need to attempt a
2265 retransmission of the message, or take other action depending
2266 on the setting of errno as described below.
2268 In the event of extreme failure, a NULL pointer is returned.
2269 In this case the value of errno might be of some use, for
2270 documentation, but there will be little that the user
2271 application can do other than to move on.
2274 --------------------------------------------------------------------------------------------
2276 The following values may be passed back in the *state* field
2277 of the returned message buffer.
2283 The message buffer pointer did not refer to a valid
2288 The header in the message buffer was not valid or
2293 The message type in the message buffer did not map to a
2298 The send failed; errno has the possible reason.
2301 The following values may be assigned to errno on failure.
2306 Parameter(s) passed to the function were not valid, or the
2307 underlying message processing environment was unable to
2308 interpret the message.
2313 The header information in the message buffer was invalid.
2318 No known endpoint for the message could be found.
2323 The underlying transport refused to accept the message
2324 because of a size value issue (message was not attempted
2330 The message referenced by the message buffer is corrupt
2331 (NULL pointer or bad internal length).
2336 Internal RMR error; information provided to the message
2337 transport environment was not valid.
2342 Sending was not supported by the underlying message
2348 The device is not in a state that can accept the message.
2353 The device is not able to accept a message for sending.
2354 The user application should attempt to resend.
2359 The operation was interrupted by delivery of a signal
2360 before the message was sent.
2365 The underlying message environment timed out during the
2371 The underlying message environment is in a shutdown state.
2375 --------------------------------------------------------------------------------------------
2379 --------------------------------------------------------------------------------------------
2381 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2382 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
2383 rmr_rcv_specific(3), rmr_ready(3), rmr_fib(3),
2384 rmr_has_str(3), rmr_set_stimeout(3), rmr_tokenise(3),
2385 rmr_mk_ring(3), rmr_ring_free(3)
2389 --------------------------------------------------------------------------------------------
2394 --------------------------------------------------------------------------------------------
2399 #include <rmr/rmr.h>
2400 rmr_mbuf_t* rmr_send_msg( void* vctx, rmr_mbuf_t* msg );
2405 --------------------------------------------------------------------------------------------
2407 The rmr_send_msg function accepts a message buffer from the
2408 user application and attempts to send it. The destination of
2409 the message is selected based on the message type specified
2410 in the message buffer, and the matching information in the
2411 routing tables which are currently in use by the RMR library.
2412 This may actually result in the sending of the message to
2413 multiple destinations which could degrade expected overall
2414 performance of the user application. (Limiting excessive
2415 sending of messages is the responsibility of the
2416 application(s) responsible for building the routing table
2417 used by the RMR library, and not the responsibility of the
2421 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2423 The send operations in RMr will retry *soft* send failures
2424 until one of three conditions occurs:
2430 The message is sent without error
2435 The underlying transport reports a * hard * failure
2440 The maximum number of retry loops has been attempted
2443 A retry loop consists of approximately 1000 send attemps **
2444 without** any intervening calls to * sleep() * or * usleep().
2445 * The number of retry loops defaults to 1, thus a maximum of
2446 1000 send attempts is performed before returning to the user
2447 application. This value can be set at any point after RMr
2448 initialisation using the * rmr_set_stimeout() * function
2449 allowing the user application to completely disable retires
2450 (set to 0), or to increase the number of retry loops.
2452 Transport Level Blocking
2453 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2455 The underlying transport mechanism used to send messages is
2456 configured in *non-blocking* mode. This means that if a
2457 message cannot be sent immediately the transport mechanism
2458 will **not** pause with the assumption that the inability to
2459 send will clear quickly (within a few milliseconds). This
2460 means that when the retry loop is completely disabled (set to
2461 0), that the failure to accept a message for sending by the
2462 underlying mechanisms (software or hardware) will be reported
2463 immediately to the user application.
2465 It should be noted that depending on the underlying transport
2466 mechanism being used, it is extremly possible that during
2467 normal operations that retry conditions are very likely to
2468 happen. These are completely out of RMr's control, and there
2469 is nothing that RMr can do to avoid or midigate these other
2470 than by allowing RMr to retry the send operation, and even
2471 then it is possible (e.g. during connection reattempts), that
2472 a single retry loop is not enough to guarentee a successful
2476 --------------------------------------------------------------------------------------------
2478 On success, a new message buffer, with an empty payload, is
2479 returned for the application to use for the next send. The
2480 state in this buffer will reflect the overall send operation
2481 state and will be RMR_OK when the send was successful.
2483 When the message cannot be successfully sent this function
2484 will return the unsent (original) message buffer with the
2485 state set to indicate the reason for failure. The value of
2486 *errno* may also be set to reflect a more detailed failure
2487 reason if it is known.
2489 In the event of extreme failure, a NULL pointer is returned.
2490 In this case the value of errno might be of some use, for
2491 documentation, but there will be little that the user
2492 application can do other than to move on.
2494 **CAUTION:** In some cases it is extremely likely that the
2495 message returned by the send function does **not** reference
2496 the same memory structure. Thus is important for the user
2497 programme to capture the new pointer for future use or to be
2498 passed to rmr_free(). If you are experiencing either double
2499 free errors or segment faults in either rmr_free() or
2500 rmr_send_msg(), ensure that the return value from this
2501 function is being captured and used.
2504 --------------------------------------------------------------------------------------------
2506 The following values may be passed back in the *state* field
2507 of the returned message buffer.
2513 The message could not be sent, but the underlying
2514 transport mechanism indicates that the failure is
2515 temporary. If the send operation is tried again it might
2520 The send operation was not successful and the underlying
2521 transport mechanism indicates a permanent (hard) failure;
2522 retrying the send is not possible.
2526 The message buffer pointer did not refer to a valid
2531 The header in the message buffer was not valid or
2536 The message type in the message buffer did not map to a
2540 The following values may be assigned to errno on failure.
2545 Parameter(s) passed to the function were not valid, or the
2546 underlying message processing environment was unable to
2547 interpret the message.
2552 The header information in the message buffer was invalid.
2557 No known endpoint for the message could be found.
2562 The underlying transport refused to accept the message
2563 because of a size value issue (message was not attempted
2569 The message referenced by the message buffer is corrupt
2570 (NULL pointer or bad internal length).
2575 Internal RMR error; information provided to the message
2576 transport environment was not valid.
2581 Sending was not supported by the underlying message
2587 The device is not in a state that can accept the message.
2592 The device is not able to accept a message for sending.
2593 The user application should attempt to resend.
2598 The operation was interrupted by delivery of a signal
2599 before the message was sent.
2604 The underlying message environment timed out during the
2610 The underlying message environment is in a shutdown state.
2614 --------------------------------------------------------------------------------------------
2616 The following is a simple example of how the rmr_send_msg
2617 function is called. In this example, the send message buffer
2618 is saved between calls and reused eliminating alloc/free
2624 static rmr_mbuf_t* send_msg = NULL; // message to send; reused on each call
2625 msg_t* send_pm; // payload for send
2626 msg_t* pm; // our message format in the received payload
2627 mif( send_msg == NULL ) {
2628 send_msg = rmr_alloc_msg( mr, MAX_SIZE ); r// new buffer to send
2630 // reference payload and fill in message type
2631 pm = (msg_t*) send_msg->payload;
2632 send_msg->mtype = MT_ANSWER;
2633 msg->len = generate_data( pm ); // something that fills the payload in
2634 msg = rmr_send_msg( mr, send_msg ); // ensure new pointer used after send
2638 m sif( msg->state != RMR_OK ) {
2639 m s m// check for RMR_ERR_RETRY, and resend if needed
2640 m s m// else return error
2648 --------------------------------------------------------------------------------------------
2650 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2651 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
2652 rmr_rts_msg(3), rmr_ready(3), rmr_mk_ring(3),
2653 rmr_ring_free(3), rmr_torcv_rcv(3), rmr_wh_send_msg(3)
2657 --------------------------------------------------------------------------------------------
2662 --------------------------------------------------------------------------------------------
2667 #include <rmr/rmr.h>
2668 rmr_mbuf_t* rmr_set_stimeout( void* vctx, int rloops );
2673 --------------------------------------------------------------------------------------------
2675 The rmr_set_stimeout function sets the configuration for how
2676 RMr will retry message send operations which complete with
2677 either a *timeout* or *again* completion value. (Send
2678 operations include all of the possible message send
2679 functions: *rmr_send_msg(), rmr_call(), rmr_rts_msg()* and
2680 *rmr_wh_send_msg().* The *rloops* parameter sets the maximum
2681 number of retry loops that will be attempted before giving up
2682 and returning the unsuccessful state to the user application.
2683 Each retry loop is approximately 1000 attempts, and RMr does
2684 **not** invoke any sleep function between retries in the
2685 loop; a small, 1 mu-sec, sleep is executed between loop sets
2686 if the *rloops* value is greater than 1.
2690 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2692 By default, the send operations will execute with an *rloop*
2693 setting of 1; each send operation will attempt to resend the
2694 message approximately 1000 times before giving up. If the
2695 user application does not want to have send operations retry
2696 when the underlying transport mechanism indicates *timeout*
2697 or *again,* the application should invoke this function and
2698 pass a value of 0 (zero) for *rloops.* With this setting, all
2699 RMr send operations will attempt a send operation only
2700 **once,** returning immediately to the caller with the state
2701 of that single attempt.
2704 --------------------------------------------------------------------------------------------
2706 This function returns a -1 to indicate that the *rloops*
2707 value could not be set, and the value *RMR_OK* to indicate
2711 --------------------------------------------------------------------------------------------
2713 Currently errno is **not** set by this function; the only
2714 cause of a failure is an invalid context (*vctx*) pointer.
2717 --------------------------------------------------------------------------------------------
2719 The following is a simple example of how the rmr_set_stimeout
2726 char* Oport = "43086"; // port for message router listen
2727 int rmax_size = 4096; // max message size for default allocations
2728 void* mr_context; // message router context
2729 mr_context = rmr_init( port, max_size, NO_FLAGS );
2730 if( mr_context != NULL ) {
2731 rmr_set_stimeout( mr_context, 0 ); // turn off retries
2737 --------------------------------------------------------------------------------------------
2739 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2740 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
2741 rmr_rts_msg(3), rmr_ready(3), rmr_mk_ring(3),
2742 rmr_ring_free(3), rmr_send_msg(3), rmr_torcv_rcv(3),
2747 --------------------------------------------------------------------------------------------
2752 --------------------------------------------------------------------------------------------
2757 #include <rmr/rmr.h>
2758 int rmr_bytes2payload( rmr_mbuf_t* mbuf, unsigned char* data, int len )
2763 --------------------------------------------------------------------------------------------
2765 The rmr_set_trace function will copy len bytes from data into
2766 the trace portion of mbuf. If the trace area of mbuf is not
2767 the correct size, the message buffer will be reallocated to
2768 ensure that enough space is available for the trace data.
2771 --------------------------------------------------------------------------------------------
2773 The rmr_set_trace function returns the number of bytes
2774 successfully copied to the message. If 0 is returned either
2775 the message pointer was nil, or the size in the parameters
2779 --------------------------------------------------------------------------------------------
2781 rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3),
2782 rmr_bytes2payload(3), rmr_call(3), rmr_free_msg(3),
2783 rmr_get_rcvfd(3), rmr_get_meid(3), rmr_get_trace(3),
2784 rmr_get_trlen(3), rmr_init(3), rmr_init_trace(3),
2785 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
2786 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
2787 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
2788 rmr_ring_free(3), rmr_str2meid(3), rmr_str2xact(3),
2789 rmr_wh_open(3), rmr_wh_send_msg(3)
2793 --------------------------------------------------------------------------------------------
2798 --------------------------------------------------------------------------------------------
2803 #include <rmr/rmr.h>
2804 int rmr_str2meid( rmr_mbuf_t* mbuf, unsigned char* src, int len )
2809 --------------------------------------------------------------------------------------------
2811 The rmr_str2meid function will copy the string pointed to by
2812 src to the managed entity ID (meid) field in the given
2813 message. The field is a fixed length, gated by the constant
2814 RMR_MAX_MEID and if string length is larger than this value,
2815 then **nothing** will be copied. (Note, this differs slightly
2816 from the behaviour of the lrmr_bytes2meid() function.)
2819 --------------------------------------------------------------------------------------------
2821 On success, the value RMR_OK is returned. If the string
2822 cannot be copied to the message, the return value will be one
2823 of the errors listed below.
2826 --------------------------------------------------------------------------------------------
2828 If the return value is not RMR_OK, then it will be set to one
2829 of the values below.
2835 The message, or an internal portion of the message, was
2836 corrupted or the pointer was invalid.
2841 The length passed in was larger than the maximum length of
2842 the field; only a portion of the source bytes were copied.
2846 --------------------------------------------------------------------------------------------
2850 --------------------------------------------------------------------------------------------
2852 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
2853 rmr_get_meid(3), rmr_get_rcvfd(3), rmr_payload_size(3),
2854 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
2855 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
2856 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
2857 rmr_bytes2meid(3), rmr_wh_open(3), rmr_wh_send_msg(3)
2861 --------------------------------------------------------------------------------------------
2866 --------------------------------------------------------------------------------------------
2871 #include <rmr/rmr.h>
2872 int rmr_str2xact( rmr_mbuf_t* mbuf, unsigned char* src, int len )
2877 --------------------------------------------------------------------------------------------
2879 The rmr_str2xact function will copy the string pointed to by
2880 src to the transaction ID (xaction) field in the given
2881 message. The field is a fixed length, gated by the constant
2882 RMR_MAX_XID and if string length is larger than this value,
2883 then **nothing** will be copied. (Note, this differs slightly
2884 from the behaviour of the lrmr_bytes2xact() function.)
2888 --------------------------------------------------------------------------------------------
2890 On success, the value RMR_OK is returned. If the string
2891 cannot be copied to the message, the return value will be
2892 one of the errors listed below.
2895 --------------------------------------------------------------------------------------------
2897 If the return value is not RMR_OK, then it will be set to
2898 one of the values below.
2903 The message, or an internal portion of the message, was
2904 corrupted or the pointer was invalid.
2909 The length passed in was larger than the maximum length of
2910 the field; only a portion of the source bytes were copied.
2914 --------------------------------------------------------------------------------------------
2918 --------------------------------------------------------------------------------------------
2920 rmr_alloc_msg(3), rmr_bytes2meid(3), rmr_bytes2xact(3),
2921 rmr_call(3), rmr_free_msg(3), rmr_get_meid(3),
2922 rmr_get_rcvfd(3), rmr_get_xact(3), rmr_payload_size(3),
2923 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
2924 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
2925 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
2926 rmr_str2meid(3), rmr_wh_open(3), rmr_wh_send_msg(3)
2930 --------------------------------------------------------------------------------------------
2932 RMR support functions
2935 --------------------------------------------------------------------------------------------
2940 #include <rmr/rmr.h>
2941 #include <rmr/ring_inline.h>
2942 char* rmr_fib( char* fname );
2943 int rmr_has_str( char const* buf, char const* str, char sep, int max );
2944 int rmr_tokenise( char* buf, char** tokens, int max, char sep );
2945 void* rmr_mk_ring( int size );
2946 void rmr_ring_free( void* vr );
2947 static inline void* rmr_ring_extract( void* vr )
2948 static inline int rmr_ring_insert( void* vr, void* new_data )
2953 --------------------------------------------------------------------------------------------
2955 These functions support the RMR library, and are made
2956 available to user applications as some (e.g. route table
2957 generators) might need and/or want to make use of them. The
2958 rmr_fib function accepts a file name and reads the entire
2959 file into a single buffer. The intent is to provide an easy
2960 way to load a static route table without a lot of buffered
2963 The rmr_has_str function accepts a *buffer* containing a set
2964 of delimited tokens (e.g. foo,bar,goo) and returns true if
2965 the target string, *str,* matches one of the tokens. The
2966 *sep* parameter provides the separation character in the
2967 buffer (e.g a comma) and *max* indicates the maximum number
2968 of tokens to split the buffer into before checking.
2970 The rmr_tokenise function is a simple tokeniser which splits
2971 *buf* into tokens at each occurrence of *sep*. Multiple
2972 occurrences of the separator character (e.g. a,,b) result in
2973 a nil token. Pointers to the tokens are placed into the
2974 *tokens* array provided by the caller which is assumed to
2975 have at least enough space for *max* entries.
2977 The rmr_mk_ring function creates a buffer ring with *size*
2980 The rmr_ring_free function accepts a pointer to a ring
2981 context and frees the associated memory.
2983 The rmr_ring_insert and rmr_ring_extract functions are
2984 provided as static inline functions via the
2985 *rmr/ring_inline.h* header file. These functions both accept
2986 the ring *context* returned by mk_ring, and either insert a
2987 pointer at the next available slot (tail) or extract the data
2991 --------------------------------------------------------------------------------------------
2993 The following are the return values for each of these
2996 The rmr_fib function returns a pointer to the buffer
2997 containing the contents of the file. The buffer is terminated
2998 with a single nil character (0) making it a legitimate C
2999 string. If the file was empty or nonexistent, a buffer with
3000 an immediate nil character. If it is important to the calling
3001 programme to know if the file was empty or did not exist, the
3002 caller should use the system stat function call to make that
3005 The rmr_has_str function returns 1 if *buf* contains the
3006 token referenced by &ita and false (0) if it does not. On
3007 error, a -1 value is returned and errno is set accordingly.
3009 The rmr_tokenise function returns the actual number of token
3010 pointers placed into *tokens*
3012 The rmr_mk_ring function returns a void pointer which is the
3013 *context* for the ring.
3015 The rmr_ring_insert function returns 1 if the data was
3016 successfully inserted into the ring, and 0 if the ring is
3017 full and the pointer could not be deposited.
3019 The rmr_ring_extract will return the data which is at the
3020 head of the ring, or NULL if the ring is empty.
3023 --------------------------------------------------------------------------------------------
3025 Not many of these functions set the value in errno, however
3026 the value may be one of the following:
3031 Parameter(s) passed to the function were not valid.
3035 --------------------------------------------------------------------------------------------
3039 --------------------------------------------------------------------------------------------
3041 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
3042 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
3043 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
3047 --------------------------------------------------------------------------------------------
3052 --------------------------------------------------------------------------------------------
3057 #include <rmr/rmr.h>
3058 rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to );
3063 --------------------------------------------------------------------------------------------
3065 The rmr_torcv_msg function will pause for *ms_to*
3066 milliseconds waiting for a message to arrive. If a message
3067 arrives before the timeout expires the message buffer
3068 returned will have a status of RMR_OK and the payload will
3069 contain the data received. If the timeout expires before the
3070 message is received, the status will have the value
3071 RMR_ERR_TIMEOUT. When a received message is returned the
3072 message buffer will also contain the message type and length
3073 set by the sender. If messages were queued while waiting for
3074 the response to a previous invocation of rmr_call, the oldest
3075 message is removed from the queue and returned without delay.
3077 The *vctx* pointer is the pointer returned by the rmr_init
3078 function. *Old_msg* is a pointer to a previously used message
3079 buffer or NULL. The ability to reuse message buffers helps to
3080 avoid alloc/free cycles in the user application. When no
3081 buffer is available to supply, the receive function will
3085 --------------------------------------------------------------------------------------------
3087 The function returns a pointer to the rmr_mbuf_t structure
3088 which references the message information (state, length,
3089 payload), or a NULL pointer in the case of an extreme error.
3092 --------------------------------------------------------------------------------------------
3094 The *state* field in the message buffer will be one of the
3101 The message buffer (payload) references the received data.
3106 The first call to this function must initialise an
3107 underlying system notification mechanism. On failure, this
3108 error is returned and errno will have the system error
3109 status set. If this function fails to intialise, the poll
3110 mechansim, it is likely that message receives will never
3116 The timeout expired before a complete message was
3117 received. All other fields in the message buffer are not
3123 A message was received, but it had no payload. All other
3124 fields in the message buffer are not valid.
3131 Parameter(s) passed to the function were not valid.
3136 The underlying message transport is unable to process the
3142 The underlying message transport is unable to process the
3148 The underlying message transport is unable to process the
3154 The underlying message transport is unable to process the
3160 The underlying message transport is unable to process the
3166 The underlying message transport is unable to process the
3172 The underlying message transport is unable to process the
3177 --------------------------------------------------------------------------------------------
3181 --------------------------------------------------------------------------------------------
3183 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
3184 rmr_get_rcvfd(3), rmr_init(3), rmr_payload_size(3),
3185 rmr_rcv_msg(3), rmr_send_msg(3), rmr_rcv_specific(3),
3186 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
3187 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
3191 --------------------------------------------------------------------------------------------
3196 --------------------------------------------------------------------------------------------
3201 #include <rmr/rmr.h>
3202 int rmr_trace_ref( rmr_mbuf_t* mbuf, int* sizeptr )
3207 --------------------------------------------------------------------------------------------
3209 The rmr_trace_ref function return a pointer to the trace area
3210 in the message, and optionally populate the user programme
3211 supplied size integer with the trace area size, if *sizeptr*
3215 --------------------------------------------------------------------------------------------
3217 On success, a void pointer to the trace area of the message
3218 is returned. A nil pointer is returned if the message has no
3219 trace data area allocated, or if the message itself is
3223 --------------------------------------------------------------------------------------------
3225 rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3),
3226 rmr_bytes2meid(3), rmr_call(3), rmr_free_msg(3),
3227 rmr_get_rcvfd(3), rmr_get_trlen(3), rmr_init(3),
3228 rmr_init_trace(3), rmr_payload_size(3), rmr_send_msg(3),
3229 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
3230 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
3231 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
3232 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3),
3237 --------------------------------------------------------------------------------------------
3242 --------------------------------------------------------------------------------------------
3247 #include <rmr/rmr.h>
3248 rmr_mbuf_t* rmr_tralloc_msg( void* vctx, int size,
3249 int trace_size, unsigned const char *tr_data );
3254 --------------------------------------------------------------------------------------------
3256 The rmr_alloc_msg function is used to allocate a buffer which
3257 the user programme can write into and then send through the a
3258 library. The buffer is allocated such that sending it
3259 requires no additional copying from the buffer as it passes
3260 through the underlying transport mechanism.
3262 The *size* parameter is used to set the payload length in the
3263 message and If it is 0, then the default size supplied on the
3264 *rmr_init* call will be used. In addition to allocating the
3265 payload, a space in the buffer is reserved for *trace* data
3266 (tr_size bytes), and the bytes pointed to by *tr_data* are
3267 copied into that portion of the message. The *vctx* parameter
3268 is the void context pointer that was returned by the
3269 *rmr_init* function.
3271 The pointer to the message buffer returned is a structure
3272 which has some user application visible fields; the structure
3273 is described in rmr.h, and is illustrated below.
3282 unsigned char* payload;
3283 unsigned char* xaction;
3292 Is the current buffer state. Following a call to
3293 rmr_send_msg the state indicates whether the buffer was
3294 successfully sent which determines exactly what the
3295 payload points to. If the send failed, the payload
3296 referenced by the buffer is the message that failed to
3297 send (allowing the application to attempt a
3298 retransmission). When the state is a_OK the buffer
3299 represents an empty buffer that the application may fill
3300 in in preparation to send.
3305 When sending a message, the application is expected to set
3306 this field to the appropriate message type value (as
3307 determined by the user programme). Upon send this value
3308 determines how the a library will route the message. For a
3309 buffer which has been received, this field will contain
3310 the message type that was set by the sending application.
3315 The application using a buffer to send a message is
3316 expected to set the length value to the actual number of
3317 bytes that it placed into the message. This is likely less
3318 than the total number of bytes that the message can carry.
3319 For a message buffer that is passed to the application as
3320 the result of a receive call, this will be the value that
3321 the sending application supplied and should indicate the
3322 number of bytes in the payload which are valid.
3327 The payload is a pointer to the actual received data. The
3328 user programme may read and write from/to the memory
3329 referenced by the payload up until the point in time that
3330 the buffer is used on a rmr_send, rmr_call or rmr_reply
3331 function call. Once the buffer has been passed back to a a
3332 library function the user programme should **NOT** make
3333 use of the payload pointer.
3338 The *xaction* field is a pointer to a fixed sized area in
3339 the message into which the user may write a transaction
3340 ID. The ID is optional with the exception of when the user
3341 application uses the rmr_call function to send a message
3342 and wait for the reply; the underlying a processing
3343 expects that the matching reply message will also contain
3344 the same data in the *xaction* field.
3348 --------------------------------------------------------------------------------------------
3350 The function returns a pointer to a rmr_mbuf structure, or
3354 --------------------------------------------------------------------------------------------
3360 Unable to allocate memory.
3364 --------------------------------------------------------------------------------------------
3366 rmr_alloc_msg(3), rmr_mbuf(3) rmr_call(3), rmr_free_msg(3),
3367 rmr_init(3), rmr_init_trace(3), rmr_get_trace(3),
3368 rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
3369 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
3370 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
3371 rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)
3375 --------------------------------------------------------------------------------------------
3380 --------------------------------------------------------------------------------------------
3385 #include <rmr/rmr.h>
3386 void rmr_close( void* vctx, rmr_whid_t whid )
3391 --------------------------------------------------------------------------------------------
3393 The rmr_wh_close function closes the wormhole associated with
3394 the wormhole id passed in. Future calls to rmr_wh_send_msg
3395 with this ID will fail.
3397 The underlying TCP connection to the remote endpoint is
3398 **not** closed as this session may be reqruired for
3399 regularlly routed messages (messages routed based on message
3400 type). There is no way to force a TCP session to be closed at
3404 --------------------------------------------------------------------------------------------
3406 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
3407 rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3),
3408 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
3409 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
3410 rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_open(3),
3415 --------------------------------------------------------------------------------------------
3420 --------------------------------------------------------------------------------------------
3425 #include <rmr/rmr.h>
3426 void* rmr_wh_open( void* vctx, char* target )
3431 --------------------------------------------------------------------------------------------
3433 The rmr_wh_open function creates a direct link for sending, a
3434 wormhole, to another RMr based process. Sending messages
3435 through a wormhole requires that the connection be
3436 established overtly by the user application (via this
3437 function), and that the ID returned by rmr_wh_open be passed
3438 to the rmr_wh_send_msg function.
3440 *Target* is the *name* or *IP-address* combination of the
3441 processess that the wormhole should be connected to. *Vctx*
3442 is the RMr void context pointer that was returned by the
3445 When invoked, this function immediatly attempts to connect to
3446 the target process. If the connection cannot be established,
3447 an error is returned to the caller, and no direct messages
3448 can be sent to the target. Once a wormhole is connected, the
3449 underlying transport mechanism (e.g. NNG) will provide
3450 reconnects should the connection be lost, however the
3451 handling of messages sent when a connection is broken is
3452 undetermined as each underlying transport mechanism may
3453 handle buffering and retries differently.
3456 --------------------------------------------------------------------------------------------
3458 The rmr_wh_open function returns a type rmr_whid_t which must
3459 be passed to the rmr_wh_send_msg function when sending a
3460 message. The id may also be tested to determine success or
3461 failure of the connection by using the RMR_WH_CONNECTED macro
3462 and passing the ID as the parameter; a result of 1 indicates
3463 that the connection was esablished and that the ID is valid.
3466 --------------------------------------------------------------------------------------------
3468 The following error values are specifically set by this RMR
3469 function. In some cases the error message of a system call is
3470 propagated up, and thus this list might be incomplete.
3475 A parameter passed was not valid.
3479 The user applicarion does not have the ability to
3480 establish a wormhole to the indicated target (or maybe any
3485 The connection was refused.
3489 --------------------------------------------------------------------------------------------
3496 rmc = rmr_init( "43086", 4096, 0 ); // init context
3497 wh = rmr_wh_open( rmc, "localhost:6123" );
3498 if( !RMR_WH_CONNECTED( wh ) ) {
3499 f fprintf( stderr, "unable to connect wormhole: %s\\n",
3500 strerror( errno ) );
3506 --------------------------------------------------------------------------------------------
3508 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
3509 rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3),
3510 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
3511 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
3512 rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_send_msg(3),
3517 --------------------------------------------------------------------------------------------
3522 --------------------------------------------------------------------------------------------
3527 #include <rmr/rmr.h>
3528 rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t id, rmr_mbuf_t* msg );
3533 --------------------------------------------------------------------------------------------
3535 The rmr_wh_send_msg function accepts a message buffer from
3536 the user application and attempts to send it using the
3537 wormhole ID provided (id). Unlike *rmr_send_msg,* this
3538 function attempts to send the message directly to a process
3539 at the other end of a wormhole which was created with
3540 *rmr_wh-open().* When sending message via wormholes, the
3541 normal RMr routing based on message type is ignored, and the
3542 caller may leave the message type unspecified in the message
3543 buffer (unless it is needed by the receiving process).
3545 The message buffer (msg) used to send is the same format as
3546 used for regular RMr send and reply to sender operations,
3547 thus any buffer allocated by these means, or calls to
3548 *rmr_rcv_msg()* can be passed to this function.
3551 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3553 The send operations in RMr will retry *soft* send failures
3554 until one of three conditions occurs:
3560 The message is sent without error
3565 The underlying transport reports a * hard * failure
3570 The maximum number of retry loops has been attempted
3573 A retry loop consists of approximately 1000 send attemps **
3574 without** any intervening calls to * sleep() * or * usleep().
3575 * The number of retry loops defaults to 1, thus a maximum of
3576 1000 send attempts is performed before returning to the user
3577 application. This value can be set at any point after RMr
3578 initialisation using the * rmr_set_stimeout() * function
3579 allowing the user application to completely disable retires
3580 (set to 0), or to increase the number of retry loops.
3582 Transport Level Blocking
3583 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3585 The underlying transport mechanism used to send messages is
3586 configured in *non-blocking* mode. This means that if a
3587 message cannot be sent immediately the transport mechanism
3588 will **not** pause with the assumption that the inability to
3589 send will clear quickly (within a few milliseconds). This
3590 means that when the retry loop is completely disabled (set to
3591 0), that the failure to accept a message for sending by the
3592 underlying mechanisms (software or hardware) will be reported
3593 immediately to the user application.
3595 It should be noted that depending on the underlying transport
3596 mechanism being used, it is extremly possible that during
3597 normal operations that retry conditions are very likely to
3598 happen. These are completely out of RMr's control, and there
3599 is nothing that RMr can do to avoid or midigate these other
3600 than by allowing RMr to retry the send operation, and even
3601 then it is possible (e.g. during connection reattempts), that
3602 a single retry loop is not enough to guarentee a successful
3606 --------------------------------------------------------------------------------------------
3608 On success, a new message buffer, with an empty payload, is
3609 returned for the application to use for the next send. The
3610 state in this buffer will reflect the overall send operation
3611 state and should be RMR_OK.
3613 If the state in the returned buffer is anything other than
3614 RMR_OK, the user application may need to attempt a
3615 retransmission of the message, or take other action depending
3616 on the setting of errno as described below.
3618 In the event of extreme failure, a NULL pointer is returned.
3619 In this case the value of errno might be of some use, for
3620 documentation, but there will be little that the user
3621 application can do other than to move on.
3624 --------------------------------------------------------------------------------------------
3626 The following values may be passed back in the *state* field
3627 of the returned message buffer.
3633 The wormhole ID passed in was not associated with an open
3634 wormhole, or was out of range for a valid ID.
3638 No wormholes exist, further attempt to validate the ID are
3643 The message buffer pointer did not refer to a valid
3648 The header in the message buffer was not valid or
3652 The following values may be assigned to errno on failure.
3657 Parameter(s) passed to the function were not valid, or the
3658 underlying message processing environment was unable to
3659 interpret the message.
3664 The header information in the message buffer was invalid.
3669 No known endpoint for the message could be found.
3674 The underlying transport refused to accept the message
3675 because of a size value issue (message was not attempted
3681 The message referenced by the message buffer is corrupt
3682 (NULL pointer or bad internal length).
3687 Internal RMR error; information provided to the message
3688 transport environment was not valid.
3693 Sending was not supported by the underlying message
3699 The device is not in a state that can accept the message.
3704 The device is not able to accept a message for sending.
3705 The user application should attempt to resend.
3710 The operation was interrupted by delivery of a signal
3711 before the message was sent.
3716 The underlying message environment timed out during the
3722 The underlying message environment is in a shutdown state.
3726 --------------------------------------------------------------------------------------------
3728 The following is a simple example of how the a wormhole is
3729 created (rmr_wh_open) and then how rmr_wh_send_msg function
3730 is used to send messages. Some error checking is omitted for
3736 #include <rmr/rmr.h> .// system headers omitted for clarity
3738 rmr_whid_t whid = -1; // wormhole id for sending
3739 void* mrc; //msg router context
3741 rmr_mbuf_t* sbuf; // send buffer
3743 mrc = rmr_init( "43086", RMR_MAX_RCV_BYTES, RMRFL_NONE );
3745 fprintf( stderr, "[FAIL] unable to initialise RMr environment\\n" );
3748 while( ! rmr_ready( mrc ) ) { e i// wait for routing table info
3751 sbuf = rmr_alloc_msg( mrc, 2048 );
3754 whid = rmr_wh_open( mrc, "localhost:6123" ); // open fails if endpoint refuses conn
3755 w if( RMR_WH_CONNECTED( wh ) ) {
3756 snprintf( sbuf->payload, 1024, "periodic update from sender: %d", count++ );
3757 sbuf->len = strlen( sbuf->payload );
3758 sbuf = rmr_wh_send_msg( mrc, whid, sbuf );
3768 --------------------------------------------------------------------------------------------
3770 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
3771 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
3772 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
3773 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
3774 rmr_set_stimeout(3), rmr_wh_open(3), rmr_wh_close(3)