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 for peer-to-peer
13 communication. Applications use the library to send and
14 receive messages where the message routing and endpoint
15 selection is based on the message type rather than DNS host
16 name-IP port combinations.
18 This document contains information that developers need to
19 know to use the RMR library. Because the primary
20 documentation for the RMR library is a collection of UNIX
21 manpages (included in the development package, and available
22 via the man command when installed), there is no separate
23 "User's Guide." To provide something for the document
24 scrapers to find, this is a collection of the RMR manual
25 pages formatted directly from their source, which might be a
26 bit ragged when combined into a single markup document. Read
32 --------------------------------------------------------------------------------------------
37 --------------------------------------------------------------------------------------------
43 rmr_mbuf_t* rmr_alloc_msg( void* ctx, int size );
48 --------------------------------------------------------------------------------------------
50 The rmr_alloc_msg function is used to allocate a buffer which
51 the user programme can write into and then send through the
52 RMR library. The buffer is allocated such that sending it
53 requires no additional copying out of the buffer. If the
54 value passed in size is 0, then the default size supplied on
55 the *rmr_init* call will be used. The *ctx* parameter is the
56 void context pointer that was returned by the *rmr_init*
59 The pointer to the message buffer returned is a structure
60 which has some user application visible fields; the structure
61 is described in rmr.h, and is illustrated below.
70 unsigned char* payload;
71 unsigned char* xaction;
82 Is the current buffer state. Following a call to
83 rmr_send_msg the state indicates whether the buffer was
84 successfully sent which determines exactly what the
85 payload points to. If the send failed, the payload
86 referenced by the buffer is the message that failed to
87 send (allowing the application to attempt a
88 retransmission). When the state is RMR_OK the buffer
89 represents an empty buffer that the application may fill
90 in in preparation to send.
95 When sending a message, the application is expected to set
96 this field to the appropriate message type value (as
97 determined by the user programme). Upon send this value
98 determines how the RMR library will route the message. For
99 a buffer which has been received, this field will contain
100 the message type that was set by the sending application.
105 The application using a buffer to send a message is
106 expected to set the length value to the actual number of
107 bytes that it placed into the message. This is likely less
108 than the total number of bytes that the message can carry.
109 For a message buffer that is passed to the application as
110 the result of a receive call, this will be the value that
111 the sending application supplied and should indicate the
112 number of bytes in the payload which are valid.
117 The payload is a pointer to the actual received data. The
118 user programme may read and write from/to the memory
119 referenced by the payload up until the point in time that
120 the buffer is used on a rmr_send, rmr_call or rmr_reply
121 function call. Once the buffer has been passed back to a
122 RMR library function the user programme should **NOT**
123 make use of the payload pointer.
128 The *xaction* field is a pointer to a fixed sized area in
129 the message into which the user may write a transaction
130 ID. The ID is optional with the exception of when the user
131 application uses the rmr_call function to send a message
132 and wait for the reply; the underlying RMR processing
133 expects that the matching reply message will also contain
134 the same data in the *xaction* field.
139 This value is the subscription ID. It, in combination with
140 the message type is used by rmr to determine the target
141 endpoint when sending a message. If the application to
142 application protocol does not warrant the use of a
143 subscription ID, the RMR constant RMR_VOID_SUBID should be
144 placed in this field. When an application is forwarding or
145 returning a buffer to the sender, it is the application's
146 responsibility to set/reset this value.
151 For C applications making use of RMR, the state of a
152 transport based failure will often be available via errno.
153 However, some wrapper environments may not have direct
154 access to the C-lib errno value. RMR send and receive
155 operations will place the current value of errno into this
156 field which should make it available to wrapper functions.
157 User applications are strongly cautioned against relying
158 on the value of errno as some transport mechanisms may not
159 set this value on all calls. This value should also be
160 ignored any time the message status is RMR_OK.
164 --------------------------------------------------------------------------------------------
166 The function returns a pointer to a rmr_mbuf structure, or
170 --------------------------------------------------------------------------------------------
176 Unable to allocate memory.
180 --------------------------------------------------------------------------------------------
182 rmr_tralloc_msg(3), rmr_call(3), rmr_free_msg(3),
183 rmr_init(3), rmr_init_trace(3), rmr_get_trace(3),
184 rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
185 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
186 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
187 rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)
191 --------------------------------------------------------------------------------------------
196 --------------------------------------------------------------------------------------------
202 int rmr_bytes2meid( rmr_mbuf_t* mbuf, unsigned char* src, int len )
207 --------------------------------------------------------------------------------------------
209 The rmr_bytes2meid function will copy up to *len* butes from
210 *src* to the managed entity ID (meid) field in the message.
211 The field is a fixed length, gated by the constant
212 RMR_MAX_MEID and if len is larger than this value, only
213 RMR_MAX_MEID bytes will actually be copied.
216 --------------------------------------------------------------------------------------------
218 On success, the actual number of bytes copied is returned, or
219 -1 to indicate a hard error. If the length is less than 0, or
220 not the same as length passed in, errno is set to one of the
221 errors described in the *Errors* section.
224 --------------------------------------------------------------------------------------------
226 If the returned length does not match the length passed in,
227 errno will be set to one of the following constants with the
228 meaning listed below.
234 The message, or an internal portion of the message, was
235 corrupted or the pointer was invalid.
240 The length passed in was larger than the maximum length of
241 the field; only a portion of the source bytes were copied.
245 --------------------------------------------------------------------------------------------
249 --------------------------------------------------------------------------------------------
251 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_call(3),
252 rmr_free_msg(3), rmr_get_rcvfd(3), rmr_get_meid(3),
253 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
254 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
255 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
256 rmr_ring_free(3), rmr_str2meid(3), rmr_str2xact(3),
257 rmr_wh_open(3), rmr_wh_send_msg(3)
261 --------------------------------------------------------------------------------------------
266 --------------------------------------------------------------------------------------------
272 void rmr_bytes2payload( rmr_mbuf_t* mbuf, unsigned char* src, int len )
277 --------------------------------------------------------------------------------------------
279 This is a convenience function as some wrapper languages
280 might not have the ability to directly copy into the payload
281 buffer. The bytes from *src* for the length given are copied
282 to the payload. It is the caller's responsibility to ensure
283 that the payload is large enough. Upon successfully copy, the
284 len field in the message buffer is updated to reflect the
285 number of bytes copied.
287 There is little error checking, and no error reporting.
290 --------------------------------------------------------------------------------------------
295 --------------------------------------------------------------------------------------------
299 --------------------------------------------------------------------------------------------
301 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2payload(3),
302 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
303 rmr_get_meid(3), rmr_payload_size(3), rmr_send_msg(3),
304 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
305 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
306 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
307 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
311 --------------------------------------------------------------------------------------------
316 --------------------------------------------------------------------------------------------
322 int rmr_bytes2xact( rmr_mbuf_t* mbuf, unsigned char* src, int len )
327 --------------------------------------------------------------------------------------------
329 The rmr_bytes2xact function will copy up to *len* butes from
330 *src* to the transaction ID (xaction) field in the message.
331 The field is a fixed length, gated by the constant
332 RMR_MAX_XID and if len is larger than this value, only
333 RMR_MAX_XID bytes will actually be copied.
337 --------------------------------------------------------------------------------------------
339 On success, the actual number of bytes copied is returned,
340 or -1 to indicate a hard error. If the length is less than
341 0, or not the same as length passed in, errno is set to
342 one of the errors described in the *Errors* section.
345 --------------------------------------------------------------------------------------------
347 If the returned length does not match the length passed
348 in, errno will be set to one of the following constants
349 with the meaning listed below.
354 The message, or an internal portion of the message, was
355 corrupted or the pointer was invalid.
360 The length passed in was larger than the maximum length of
361 the field; only a portion of the source bytes were copied.
365 --------------------------------------------------------------------------------------------
369 --------------------------------------------------------------------------------------------
371 rmr_alloc_msg(3), rmr_bytes2meid(3), rmr_call(3),
372 rmr_free_msg(3), rmr_get_meid(3), rmr_get_rcvfd(3),
373 rmr_get_xact(3), rmr_payload_size(3), rmr_send_msg(3),
374 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
375 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
376 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
377 rmr_wh_open(3), rmr_wh_send_msg(3)
381 --------------------------------------------------------------------------------------------
386 --------------------------------------------------------------------------------------------
392 extern rmr_mbuf_t* rmr_call( void* vctx, rmr_mbuf_t* msg );
397 --------------------------------------------------------------------------------------------
399 The rmr_call function sends the user application message to a
400 remote endpoint, and waits for a corresponding response
401 message before returning control to the user application. The
402 user application supplies a completed message buffer, as it
403 would for a rmr_send call, but unlike with the send, the
404 buffer returned will have the response from the application
405 that received the message.
407 Messages which are received while waiting for the response
408 are queued internally by RMR, and are returned to the user
409 application when rmr_rcv_msg is invoked. These messages are
410 returned in th order received, one per call to rmr_rcv_msg.
413 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
415 The rmr_call function implements a timeout failsafe to
416 prevent, in most cases, the function from blocking forever.
417 The timeout period is **not** based on time (calls to clock
418 are deemed too expensive for a low latency system level
419 library, but instead the period is based on the number of
420 received messages which are not the response. Using a
421 non-time mechanism for *timeout* prevents the async queue
422 from filling (which would lead to message drops) in an
423 environment where there is heavy message traffic.
425 When the threshold number of messages have been queued
426 without receiving a response message, control is returned to
427 the user application and a NULL pointer is returned to
428 indicate that no message was received to process. Currently
429 the threshold is fixed at 20 messages, though in future
430 versions of the library this might be extended to be a
431 parameter which the user application may set.
434 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
436 The send operations in RMr will retry *soft* send failures
437 until one of three conditions occurs:
443 The message is sent without error
448 The underlying transport reports a * hard * failure
453 The maximum number of retry loops has been attempted
456 A retry loop consists of approximately 1000 send attemps **
457 without** any intervening calls to * sleep() * or * usleep().
458 * The number of retry loops defaults to 1, thus a maximum of
459 1000 send attempts is performed before returning to the user
460 application. This value can be set at any point after RMr
461 initialisation using the * rmr_set_stimeout() * function
462 allowing the user application to completely disable retires
463 (set to 0), or to increase the number of retry loops.
465 Transport Level Blocking
466 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
468 The underlying transport mechanism used to send messages is
469 configured in *non-blocking* mode. This means that if a
470 message cannot be sent immediately the transport mechanism
471 will **not** pause with the assumption that the inability to
472 send will clear quickly (within a few milliseconds). This
473 means that when the retry loop is completely disabled (set to
474 0), that the failure to accept a message for sending by the
475 underlying mechanisms (software or hardware) will be reported
476 immediately to the user application.
478 It should be noted that depending on the underlying transport
479 mechanism being used, it is extremly possible that during
480 normal operations that retry conditions are very likely to
481 happen. These are completely out of RMr's control, and there
482 is nothing that RMr can do to avoid or midigate these other
483 than by allowing RMr to retry the send operation, and even
484 then it is possible (e.g. during connection reattempts), that
485 a single retry loop is not enough to guarentee a successful
489 --------------------------------------------------------------------------------------------
491 The rmr_call function returns a pointer to a message buffer
492 with the state set to reflect the overall state of call
493 processing (see Errors below). In some cases a NULL pointer
494 will be returned; when this is the case only *errno* will be
495 available to describe the reason for failure.
498 --------------------------------------------------------------------------------------------
500 These values are reflected in the state field of the returned
507 The call was successful and the message buffer references
508 the response message.
513 The call failed and the value of *errno,* as described
514 below, should be checked for the specific reason.
517 The global "variable" *errno* will be set to one of the
518 following values if the overall call processing was not
525 Too many messages were queued before receiving the
531 The queued message ring is full, messages were dropped
536 A parameter was not valid
541 The underlying message system wsa interrupted or the
542 device was busy; the message was **not** sent, and user
543 application should call this function with the message
548 --------------------------------------------------------------------------------------------
550 The following code bit shows one way of using the rmr_call
551 function, and illustrates how the transaction ID must be set.
556 int retries_left = 5; // max retries on dev not available
557 int retry_delay = 50000; // retry delay (usec)
558 static rmr_mbuf_t* mbuf = NULL; // response msg
559 msg_t* pm; // private message (payload)
560 m// get a send buffer and reference the payload
561 mbuf = rmr_alloc_msg( mr, RMR_MAX_RCV_BYTES );
562 pm = (msg_t*) mbuf->payload;
563 p// generate an xaction ID and fill in payload with data and msg type
564 snprintf( mbuf->xaction, RMR_MAX_XID, "%s", gen_xaction() );
565 snprintf( pm->req, sizeof( pm->req ), "{ \\"req\\": \\"num users\\"}" );
566 mbuf->mtype = MT_REQ;
568 msg = rmr_call( mr, msg );
569 if( ! msg ) { // probably a timeout and no msg received
570 return NULL; // let errno trickle up
572 if( mbuf->state != RMR_OK ) {
573 while( retries_left-- > 0 && // loop as long as eagain
575 (msg = rmr_call( mr, msg )) != NULL &&
576 mbuf->state != RMR_OK ) {
577 usleep( retry_delay );
580 if( mbuf == NULL || mbuf->state != RMR_OK ) {
581 rmr_free_msg( mbuf ); // safe if nil
585 // do something with mbuf
590 --------------------------------------------------------------------------------------------
592 rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3),
593 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
594 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
595 rmr_fib(3), rmr_has_str(3), rmr_set_stimeout(3),
596 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
600 --------------------------------------------------------------------------------------------
605 --------------------------------------------------------------------------------------------
611 void rmr_close( void* vctx )
616 --------------------------------------------------------------------------------------------
618 The rmr_close function closes the listen socket effectively
619 cutting the application off. The route table listener is also
620 stopped. Calls to rmr_rcv_msg() will fail with unpredictable
621 error codes, and calls to rmr_send_msg(), rmr_call(), and
622 rmr_rts_msg() will have unknown results.
626 --------------------------------------------------------------------------------------------
628 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
629 rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3),
630 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
631 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
632 rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_open(3),
637 --------------------------------------------------------------------------------------------
642 --------------------------------------------------------------------------------------------
648 void rmr_free_msg( rmr_mbuf_t* mbuf );
653 --------------------------------------------------------------------------------------------
655 The message buffer is returned to the pool, or the associated
656 memory is released depending on the needs of the underlying
657 messaging system. This allows the user application to release
658 a buffer that is not going to be used. It is safe to pass a
659 nil pointer to this function, and doing so does not result in
660 a change to the value of errrno.
662 After calling, the user application should **not** use any of
663 the pointers (transaction ID, or payload) which were
667 --------------------------------------------------------------------------------------------
669 rmr_alloc_msg(3), rmr_call(3), rmr_init(3),
670 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
671 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
672 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
677 --------------------------------------------------------------------------------------------
682 --------------------------------------------------------------------------------------------
688 char* rmr_get_meid( rmr_mbuf_t* mbuf, unsigned char* dest )
693 --------------------------------------------------------------------------------------------
695 The rmr_get_meid function will copy the managed entity ID
696 (meid) field from the message into the *dest* buffer provided
697 by the user. The buffer referenced by *dest* is assumed to be
698 at least RMR_MAX_MEID bytes in length. If *dest* is NULL,
699 then a buffer is allocated (the calling application is
700 expected to free when the buffer is no longer needed).
703 --------------------------------------------------------------------------------------------
705 On success, a pointer to the extracted string is returned. If
706 *dest* was supplied, then this is just a pointer to the
707 caller's buffer. If *dest* was NULL, this is a pointer to the
708 allocated buffer. If an error occurs, a nil pointer is
709 returned and errno is set as described below.
712 --------------------------------------------------------------------------------------------
714 If an error occurs, the value of the global variable errno
715 will be set to one of the following with the indicated
722 The message, or an internal portion of the message, was
723 corrupted or the pointer was invalid.
728 A nil pointer was passed for *dest,* however it was not
729 possible to allocate a buffer using malloc().
733 --------------------------------------------------------------------------------------------
735 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3),
736 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
737 rmr_get_xact(3), rmr_payload_size(3), rmr_send_msg(3),
738 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
739 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
740 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
741 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
745 --------------------------------------------------------------------------------------------
750 --------------------------------------------------------------------------------------------
756 void* rmr_get_rcvfd( void* ctx )
761 --------------------------------------------------------------------------------------------
763 The rmr_get_rcvfd function returns a file descriptor which
764 may be given to epoll_wait() by an application that wishes to
765 use event poll in a single thread rather than block on the
766 arrival of a message via calls to rmr_rcv_msg(). When
767 epoll_wait() indicates that this file descriptor is ready, a
768 call to rmr_rcv_msg() will not block as at least one message
771 The context (ctx) pointer passed in is the pointer returned
772 by the call to rmr_init().
774 **NOTE:** There is no support for epoll in Nanomsg, thus his
775 function is only supported when linking with the NNG version
776 of RMr and the file descriptor returned when using the
777 Nanomsg verfsion will always return an error.
780 --------------------------------------------------------------------------------------------
782 The rmr_get_rcvfd function returns a file descriptor greater
783 or equal to 0 on success and -1 on error. If this function is
784 called from a user application linked against the Nanomsg RMr
785 library, calls will always return -1 with errno set to
789 --------------------------------------------------------------------------------------------
791 The following error values are specifically set by this RMR
792 function. In some cases the error message of a system call is
793 propagated up, and thus this list might be incomplete.
798 The use of this function is invalid in this environment.
802 --------------------------------------------------------------------------------------------
804 The following short code bit illustrates the use of this
805 function. Error checking has been omitted for clarity.
812 #include <sys/epoll.h>
815 int rcv_fd; // pollable fd
816 void* mrc; //msg router context
817 struct epoll_event events[10]; // support 10 events to poll
818 struct epoll_event epe; // event definition for event to listen to
820 rmr_mbuf_t* msg = NULL;
824 mrc = rmr_init( "43086", RMR_MAX_RCV_BYTES, RMRFL_NONE );
825 rcv_fd = rmr_get_rcvfd( mrc );
827 rep_fd = epoll_create1( 0 ); _ B ,// initialise epoll environment
828 epe.events = EPOLLIN;
829 epe.data.fd = rcv_fd;
830 epoll_ctl( ep_fd, EPOLL_CTL_ADD, rcv_fd, &epe ); // add our info to the mix
833 nready = epoll_wait( ep_fd, events, 10, -1 ); // -1 == block forever (no timeout)
834 for( i = 0; i < nready && i < 10; i++ ) { // loop through to find what is ready
835 if( events[i].data.fd == rcv_fd ) { // RMr has something
836 msg = rmr_rcv_msg( mrc, msg );
838 // do something with msg
842 // check for other ready fds....
850 --------------------------------------------------------------------------------------------
852 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
853 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
854 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
855 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
860 --------------------------------------------------------------------------------------------
865 --------------------------------------------------------------------------------------------
871 unsigned char* rmr_get_src( rmr_mbuf_t* mbuf, unsigned char* dest )
876 --------------------------------------------------------------------------------------------
878 The rmr_get_src function will copy the *source* information
879 from the message to a buffer (dest) supplied by the user. In
880 an RMr message, the source is the sender's information that
881 is used for return to sender function calls, and is generally
882 the hostname and port in the form *name*. The source might be
883 an IP address port combination; the data is populated by the
884 sending process and the only requirement is that it be
885 capable of being used to start a TCP session with the sender.
887 The maximum size allowed by RMr is 64 bytes (including the
888 nil string terminator), so the user must ensure that the
889 destination buffer given is at least 64 bytes.
892 --------------------------------------------------------------------------------------------
894 On success, a pointer to the destination buffer is given as a
895 convenience to the user programme. On failure, a nil pointer
896 is returned and the value of errno is set.
899 --------------------------------------------------------------------------------------------
901 If an error occurs, the value of the global variable errno
902 will be set to one of the following with the indicated
909 The message, or an internal portion of the message, was
910 corrupted or the pointer was invalid.
914 --------------------------------------------------------------------------------------------
916 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3),
917 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
918 rmr_get_srcip(3), rmr_payload_size(3), rmr_send_msg(3),
919 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
920 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
921 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
922 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
926 --------------------------------------------------------------------------------------------
931 --------------------------------------------------------------------------------------------
937 unsigned char* rmr_get_srcip( rmr_mbuf_t* mbuf, unsigned char* dest )
942 --------------------------------------------------------------------------------------------
944 The rmr_get_srcip function will copy the *source IP address*
945 from the message to a buffer (dest) supplied by the user. In
946 an RMr message, the source IP address is the sender's
947 information that is used for return to sender function calls;
948 this function makes it available to the user application. The
949 address is maintained as IP:port where *IP* could be either
950 an IPv6 or IPv4 address depending on what was provided by the
953 The maximum size allowed by RMr is 64 bytes (including the
954 nil string terminator), so the user must ensure that the
955 destination buffer given is at least 64 bytes. The user
956 application should use the RMr constant RMR_MAX_SRC to ensure
957 that the buffer supplied is large enough, and to protect
958 against future RMr enhancements which might increase the
959 address buffer size requirement.
962 --------------------------------------------------------------------------------------------
964 On success, a pointer to the destination buffer is given as a
965 convenience to the user programme. On failure, a nil pointer
966 is returned and the value of errno is set.
969 --------------------------------------------------------------------------------------------
971 If an error occurs, the value of the global variable errno
972 will be set to one of the following with the indicated
979 The message, or an internal portion of the message, was
980 corrupted or the pointer was invalid.
984 --------------------------------------------------------------------------------------------
986 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3),
987 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
988 rmr_get_src(3), rmr_payload_size(3), rmr_send_msg(3),
989 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
990 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
991 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
992 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
996 --------------------------------------------------------------------------------------------
1001 --------------------------------------------------------------------------------------------
1006 #include <rmr/rmr.h>
1007 int rmr_get_trace( rmr_mbuf_t* mbuf, unsigned char* dest, int size )
1012 --------------------------------------------------------------------------------------------
1014 The rmr_get_trace function will copy the trace information
1015 from the message into the user's allocated memory referenced
1016 by dest. The size parameter is assumed to be the maximum
1017 number of bytes which can be copied (size of the destination
1021 --------------------------------------------------------------------------------------------
1023 On success, the number of bytes actually copied is returned.
1024 If the return value is 0, no bytes copied, then the reason
1025 could be that the message pointer was nil, or the size
1029 --------------------------------------------------------------------------------------------
1031 rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3),
1032 rmr_bytes2meid(3), rmr_call(3), rmr_free_msg(3),
1033 rmr_get_rcvfd(3), rmr_get_trlen(3), rmr_init(3),
1034 rmr_init_trace(3), rmr_payload_size(3), rmr_send_msg(3),
1035 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1036 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
1037 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
1038 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3),
1039 rmr_set_trace(3), rmr_trace_ref(3)
1043 --------------------------------------------------------------------------------------------
1048 --------------------------------------------------------------------------------------------
1053 #include <rmr/rmr.h>
1054 int rmr_get_trlen( rmr_mbuf_t* msg );
1059 --------------------------------------------------------------------------------------------
1061 Given a message buffer, this function returns the amount of
1062 space (bytes) that have been allocated for trace data. If no
1063 trace data has been allocated, then 0 is returned.
1066 --------------------------------------------------------------------------------------------
1068 The number of bytes allocated for trace information in the
1072 --------------------------------------------------------------------------------------------
1078 Parameter(s) passed to the function were not valid.
1082 --------------------------------------------------------------------------------------------
1084 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
1085 rmr_get_trace(3), rmr_init(3), rmr_init_trace(3),
1086 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
1087 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
1088 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
1089 rmr_set_trace(3), rmr_tralloc_msg(3)
1093 --------------------------------------------------------------------------------------------
1098 --------------------------------------------------------------------------------------------
1103 #include <rmr/rmr.h>
1104 char* rmr_get_xact( rmr_mbuf_t* mbuf, unsigned char* dest )
1109 --------------------------------------------------------------------------------------------
1111 The rmr_get_xact function will copy the transaction field
1112 from the message into the *dest* buffer provided by the user.
1113 The buffer referenced by *dest* is assumed to be at least
1114 RMR_MAX_XID bytes in length. If *dest* is NULL, then a buffer
1115 is allocated (the calling application is expected to free
1116 when the buffer is no longer needed).
1119 --------------------------------------------------------------------------------------------
1121 On success, a pointer to the extracted string is returned. If
1122 *dest* was supplied, then this is just a pointer to the
1123 caller's buffer. If *dest* was NULL, this is a pointer to the
1124 allocated buffer. If an error occurs, a nil pointer is
1125 returned and errno is set as described below.
1128 --------------------------------------------------------------------------------------------
1130 If an error occurs, the value of the global variable errno
1131 will be set to one of the following with the indicated
1138 The message, or an internal portion of the message, was
1139 corrupted or the pointer was invalid.
1144 A nil pointer was passed for *dest,* however it was not
1145 possible to allocate a buffer using malloc().
1149 --------------------------------------------------------------------------------------------
1151 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3),
1152 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
1153 rmr_get_meid(3), rmr_payload_size(3), rmr_send_msg(3),
1154 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1155 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
1156 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
1157 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
1161 --------------------------------------------------------------------------------------------
1166 --------------------------------------------------------------------------------------------
1171 #include <rmr/rmr.h>
1172 void* rmr_init( char* proto_port, int max_msg_size, int flags );
1177 --------------------------------------------------------------------------------------------
1179 The rmr_init function prepares the environment for sending
1180 and receiving messages. It does so by establishing a worker
1181 thread (pthread) which subscribes to a route table generator
1182 which provides the necessary routing information for the RMR
1183 library to send messages.
1185 *Port* is used to listen for connection requests from other
1186 RMR based applications. The *max_msg_size* parameter is used
1187 to allocate receive buffers and is the maximum message size
1188 which the application expects to receive. This value is the
1189 sum of **both** the maximum payload size **and** the maximum
1190 trace data size. This value is also used as the default
1191 message size when allocating message buffers. Messages
1192 arriving which are longer than the given maximum will be
1193 dropped without notification to the application. A warning is
1194 written to standard error for the first message which is too
1195 large on each connection.
1197 *Flags* allows for selection of some RMr options at the time
1198 of initialisation. These are set by ORing RMRFL constants
1199 from the RMr header file. Currently the following flags are
1211 The route table collector thread is not to be started.
1212 This should only be used by the route table generator
1213 application if it is based on RMr.
1218 Enable multi-threaded call support.
1223 Some underlying transport providers (e.g. SI95) enable
1224 locking to be turned off if the user application is single
1225 threaded, or otherwise can guarantee that RMR functions
1226 will not be invoked concurrently from different threads.
1227 Turning off locking can help make message receipt more
1228 efficient. If this flag is set when the underlying
1229 transport does not support disabling locks, it will be
1233 Multi-threaded Calling
1234 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1236 The support for an application to issue a *blocking call* by
1237 the rmr_call() function was limited such that only user
1238 applications which were operating in a single thread could
1239 safely use the function. Further, timeouts were message count
1240 based and not time unit based. Multi-threaded call support
1241 adds the ability for a user application with multiple threads
1242 to invoke a blocking call function with the guarantee that
1243 the correct response message is delivered to the thread. The
1244 additional support is implemented with the *rmr_mt_call()*
1245 and *rmr_mt_rcv()* function calls.
1247 Multi-threaded call support requires the user application to
1248 specifically enable it when RMr is initialised. This is
1249 necessary because a second, dedicated, receiver thread must
1250 be started, and requires all messages to be examined and
1251 queued by this thread. The additional overhead is minimal,
1252 queuing information is all in the RMr message header, but as
1253 an additional process is necessary the user application must
1254 "opt in" to this approach.
1258 --------------------------------------------------------------------------------------------
1260 As a part of the initialisation process rmr_init will look
1261 into the available environment variables to influence it's
1262 setup. The following variables will be used when found.
1268 Allows the async connection mode to be turned off (by
1269 setting the value to 0. When set to 1, or missing from the
1270 environment, RMR will invoke the connection interface in
1271 the transport mechanism using the non-blocking (async)
1272 mode. This will likely result in many "soft failures"
1273 (retry) until the connection is established, but allows
1274 the application to continue unimpeeded should the
1275 connection be slow to set up.
1280 This provides the interface that RMR will bind listen
1281 ports to allowing for a single interface to be used rather
1282 than listening across all interfaces. This should be the
1283 IP address assigned to the interface that RMR should
1284 listen on, and if not defined RMR will listen on all
1290 This variable defines the port that RMR should open for
1291 communications with Route Manager, and other RMR control
1292 applications. If not defined, the port 4561 is assumed.
1294 Previously, the RMR_RTG_SVC (route table generator service
1295 port) was used to define this port. However, a future
1296 version of Route Manager will require RMR to connect and
1297 request tables, thus that variable is now used to supply
1298 the Route Manager well known address and port.
1300 To maintain backwards compatablibility with the older
1301 Route Manager versions, the presence of this variable in
1302 the environment will shift RMR's behaviour with respect to
1303 the default value used when RMR_RTG_SVC is **not**
1306 When RMR_CTL_PORT is **defined:** RMR assumes that Route
1307 Manager requires RMR to connect and request table updates
1308 is made, and the default well known address for Route
1309 manager is used (routemgr:4561).
1311 When RMR_CTL_PORT is **undefined:** RMR assumes that Route
1312 Manager will connect and push table updates, thus the
1313 default listen port (4561) is used.
1315 To avoid any possible misinterpretation and/or incorrect
1316 assumptions on the part of RMR, it is recommended that
1317 both the RMR_CTL_PORT and RMR_RTG_SVC be defined. In the
1318 case where both variables are defined, RMR will behave
1319 exactly as is communicated with the variable's values.
1324 The value of this variable depends on the Route Manager in
1327 When the Route Manager is expecting to connect to an xAPP
1328 and push route tables, this variable must indicate the
1329 port which RMR should use to listen for these connections.
1331 When the Route Manager is expecting RMR to connect and
1332 request a table update during initialisation, the variable
1333 should be the host of the Route Manager process.
1335 The RMR_CTL_PORT variable (added with the support of
1336 sending table update requests to Route manager), controls
1337 the behaviour if this variable is not set. See the
1338 description of that variable for details.
1343 By default RMR writes messages to standard error
1344 (incorrectly referred to as log messages) in human
1345 readable format. If this environment variable is set to 0,
1346 the format of standard error messages might be written in
1347 some format not easily read by humans. If missing, a value
1353 This is a numeric value which corresponds to the verbosity
1354 level used to limit messages written to standard error.
1355 The lower the number the less chatty RMR functions are
1356 during execution. The following is the current
1357 relationship between the value set on this variable and
1358 the messages written:
1363 Off; no messages of any sort are written.
1368 Only critical messages are written (default if this
1369 variable does not exist)
1374 Errors and all messages written with a lower value.
1379 Warnings and all messages written with a lower value.
1384 Informational and all messages written with a lower
1390 Debugging mode -- all messages written, however this
1391 requires RMR to have been compiled with debugging
1398 **Deprecated.** Should be set to 1 if the route table
1399 generator is sending "plain" messages (not using RMR to
1400 send messages, 0 if the rtg is using RMR to send. The
1401 default is 1 as we don't expect the rtg to use RMR.
1403 This variable is only recognised when using the NNG
1404 transport library as it is not possible to support NNG
1405 "raw" communications with other transport libraries. It is
1406 also necessary to match the value of this variable with
1407 the capabilities of the Route Manager; at some point in
1408 the future RMR will assume that all Route Manager messages
1409 will arrive via an RMR connection and will ignore this
1414 This is used to supply a static route table which can be
1415 used for debugging, testing, or if no route table
1416 generator process is being used to supply the route table.
1417 If not defined, no static table is used and RMR will not
1418 report *ready* until a table is received. The static route
1419 table may contain both the route table (between newrt
1420 start and end records), and the MEID map (between meid_map
1421 start and end records)
1425 This is either the name or IP address which is placed into
1426 outbound messages as the message source. This will used
1427 when an RMR based application uses the rmr_rts_msg()
1428 function to return a response to the sender. If not
1429 supplied RMR will use the hostname which in some container
1430 environments might not be routable.
1432 The value of this variable is also used for Route Manager
1433 messages which are sent via an RMR connection.
1437 This supplies the name of a verbosity control file. The
1438 core RMR functions do not produce messages unless there is
1439 a critical failure. However, the route table collection
1440 thread, not a part of the main message processing
1441 component, can write additional messages to standard
1442 error. If this variable is set, RMR will extract the
1443 verbosity level for these messages (0 is silent) from the
1444 first line of the file. Changes to the file are detected
1445 and thus the level can be changed dynamically, however RMR
1446 will only suss out this variable during initialisation, so
1447 it is impossible to enable verbosity after startup.
1451 If set to 1, RMR will write some warnings which are
1452 non-performance impacting. If the variable is not defined,
1453 or set to 0, RMR will not write these additional warnings.
1457 --------------------------------------------------------------------------------------------
1459 The rmr_init function returns a void pointer (a contex if you
1460 will) that is passed as the first parameter to nearly all
1461 other RMR functions. If rmr_init is unable to properly
1462 initialise the environment, NULL is returned and errno is set
1463 to an appropriate value.
1466 --------------------------------------------------------------------------------------------
1468 The following error values are specifically set by this RMR
1469 function. In some cases the error message of a system call is
1470 propagated up, and thus this list might be incomplete.
1475 Unable to allocate memory.
1479 --------------------------------------------------------------------------------------------
1485 rmr_mbuf* buf = NULL;
1486 uh = rmr_init( "43086", 4096, 0 );
1487 buf = rmr_rcv_msg( uh, buf );
1492 --------------------------------------------------------------------------------------------
1494 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
1495 rmr_get_rcvfd(3), rmr_mt_call(3), rmr_mt_rcv(3),
1496 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
1497 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
1498 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
1503 --------------------------------------------------------------------------------------------
1508 --------------------------------------------------------------------------------------------
1513 #include <rmr/rmr.h>
1514 void* rmr_init_trace( void* ctx )
1519 --------------------------------------------------------------------------------------------
1521 The rmr_init_trace function establishes the default trace
1522 space placed in each message buffer allocated with
1523 rmr_alloc_msg(). If this function is never called, then no
1524 trace space is allocated by default into any message buffer.
1526 Trace space allows the user application to pass some trace
1527 token, or other data with the message, but outside of the
1528 payload. Trace data may be added to any message with
1529 rmr_set_trace(), and may be extracted from a message with
1530 rmr_get_trace(). The number of bytes that a message contains
1531 for/with trace data can be determined by invoking
1534 This function may be safely called at any time during the
1535 life of the user programme to (re)set the default trace space
1536 reserved. If the user programme needs to allocate a message
1537 with trace space of a different size than is allocated by
1538 default, without fear of extra overhead of reallocating a
1539 message later, the rmr_tralloc_msg() function can be used.
1542 --------------------------------------------------------------------------------------------
1544 A value of 1 is returned on success, and 0 on failure. A
1545 failure indicates that the RMr context (a void pointer passed
1546 to this function was not valid.
1549 --------------------------------------------------------------------------------------------
1551 rmr_alloc_msg(3), rmr_tr_alloc_msg(3), rmr_call(3),
1552 rmr_free_msg(3), rmr_get_rcvfd(3), rmr_get_trace(3),
1553 rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
1554 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1555 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
1556 rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)
1560 --------------------------------------------------------------------------------------------
1565 --------------------------------------------------------------------------------------------
1570 #include <rmr/rmr.h>
1571 extern rmr_mbuf_t* rmr_mt_call( void* vctx, rmr_mbuf_t* msg, int id, int timeout );
1576 --------------------------------------------------------------------------------------------
1578 The rmr_mt_call function sends the user application message
1579 to a remote endpoint, and waits for a corresponding response
1580 message before returning control to the user application. The
1581 user application supplies a completed message buffer, as it
1582 would for a rmr_send_msg call, but unlike with a send, the
1583 buffer returned will have the response from the application
1584 that received the message. The thread invoking the
1585 *rmr_mt_call()* will block until a message arrives or until
1586 *timeout* milliseconds has passed; which ever comes first.
1587 Using a timeout value of zero (0) will cause the thread to
1588 block without a timeout.
1590 The *id* supplied as the third parameter is an integer in the
1591 range of 2 through 255 inclusive. This is a caller defined
1592 "thread number" and is used to match the response message
1593 with the correct user application thread. If the ID value is
1594 not in the proper range, the attempt to make the call will
1597 Messages which are received while waiting for the response
1598 are queued on a *normal* receive queue and will be delivered
1599 to the user application with the next invocation of
1600 *rmr_mt_rcv()* or *rmr_rvv_msg().* by RMR, and are returned
1601 to the user application when rmr_rcv_msg is invoked. These
1602 messages are returned in th order received, one per call to
1605 NOTE: Currently the multi-threaded functions are supported
1606 only when the NNG transport mechanism is being used. It will
1607 not be possible to link a programme using the Nanomsg version
1608 of the library when references to this function are present.
1611 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1613 The user application is responsible for setting the value of
1614 the transaction ID field before invoking *rmr_mt_call.* The
1615 transaction ID is a RMR_MAX_XID byte field that is used to
1616 match the response message when it arrives. RMr will compare
1617 **all** of the bytes in the field, so the caller must ensure
1618 that they are set correctly to avoid missing the response
1619 message. (The application which returns the response message
1620 is also expected to ensure that the return buffer has the
1621 matching transaction ID. This can be done transparently if
1622 the application uses the *rmr_rts_msg()* function and does
1623 not adjust the transaction ID.
1626 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1628 The send operations in RMr will retry *soft* send failures
1629 until one of three conditions occurs:
1635 The message is sent without error
1640 The underlying transport reports a * hard * failure
1645 The maximum number of retry loops has been attempted
1648 A retry loop consists of approximately 1000 send attemps **
1649 without** any intervening calls to * sleep() * or * usleep().
1650 * The number of retry loops defaults to 1, thus a maximum of
1651 1000 send attempts is performed before returning to the user
1652 application. This value can be set at any point after RMr
1653 initialisation using the * rmr_set_stimeout() * function
1654 allowing the user application to completely disable retires
1655 (set to 0), or to increase the number of retry loops.
1657 Transport Level Blocking
1658 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1660 The underlying transport mechanism used to send messages is
1661 configured in *non-blocking* mode. This means that if a
1662 message cannot be sent immediately the transport mechanism
1663 will **not** pause with the assumption that the inability to
1664 send will clear quickly (within a few milliseconds). This
1665 means that when the retry loop is completely disabled (set to
1666 0), that the failure to accept a message for sending by the
1667 underlying mechanisms (software or hardware) will be reported
1668 immediately to the user application.
1670 It should be noted that depending on the underlying transport
1671 mechanism being used, it is extremly possible that during
1672 normal operations that retry conditions are very likely to
1673 happen. These are completely out of RMr's control, and there
1674 is nothing that RMr can do to avoid or midigate these other
1675 than by allowing RMr to retry the send operation, and even
1676 then it is possible (e.g. during connection reattempts), that
1677 a single retry loop is not enough to guarentee a successful
1681 --------------------------------------------------------------------------------------------
1683 The rmr_mt_call function returns a pointer to a message
1684 buffer with the state set to reflect the overall state of
1685 call processing. If the state is RMR_OK then the buffer
1686 contains the response message; otherwise the state indicates
1687 the error encountered while attempting to send the message.
1689 If no response message is received when the timeout period
1690 has expired, a nil pointer will be returned (NULL).
1693 --------------------------------------------------------------------------------------------
1695 These values are reflected in the state field of the returned
1702 The call was successful and the message buffer references
1703 the response message.
1708 An argument passed to the function was invalid.
1713 The call failed and the value of *errno,* as described
1714 below, should be checked for the specific reason.
1719 An endpoint associated with the message type could not be
1720 found in the route table.
1725 The underlying transport mechanism was unable to accept
1726 the message for sending. The user application can retry
1727 the call operation if appropriate to do so.
1730 The global "variable" *errno* will be set to one of the
1731 following values if the overall call processing was not
1738 Too many messages were queued before receiving the
1744 The queued message ring is full, messages were dropped
1749 A parameter was not valid
1754 The underlying message system wsa interrupted or the
1755 device was busy; the message was **not** sent, and user
1756 application should call this function with the message
1761 --------------------------------------------------------------------------------------------
1763 The following code bit shows one way of using the rmr_mt_call
1764 function, and illustrates how the transaction ID must be set.
1769 int retries_left = 5; // max retries on dev not available
1770 static rmr_mbuf_t* mbuf = NULL; // response msg
1771 msg_t* pm; // private message (payload)
1772 m// get a send buffer and reference the payload
1773 mbuf = rmr_alloc_msg( mr, RMR_MAX_RCV_BYTES );
1774 pm = (msg_t*) mbuf->payload;
1775 p// generate an xaction ID and fill in payload with data and msg type
1776 rmr_bytes2xact( mbuf, xid, RMR_MAX_XID );
1777 snprintf( pm->req, sizeof( pm->req ), "{ \\"req\\": \\"num users\\"}" );
1778 mbuf->mtype = MT_USR_RESP;
1780 msg = rmr_mt_call( mr, msg, my_id, 100 ); e :// wait up to 100ms
1781 if( ! msg ) { // probably a timeout and no msg received
1782 return NULL; // let errno trickle up
1784 if( mbuf->state != RMR_OK ) {
1785 while( retries_left-- > 0 && // loop as long as eagain
1786 mbuf->state == RMR_ERR_RETRY &&
1787 (msg = rmr_mt_call( mr, msg )) != NULL &&
1788 mbuf->state != RMR_OK ) {
1789 usleep( retry_delay );
1792 if( mbuf == NULL || mbuf->state != RMR_OK ) {
1793 rmr_free_msg( mbuf ); // safe if nil
1797 // do something with mbuf
1802 --------------------------------------------------------------------------------------------
1804 rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3),
1805 rmr_mt_rcv(3), rmr_payload_size(3), rmr_send_msg(3),
1806 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1807 rmr_ready(3), rmr_fib(3), rmr_has_str(3),
1808 rmr_set_stimeout(3), rmr_tokenise(3), rmr_mk_ring(3),
1813 --------------------------------------------------------------------------------------------
1818 --------------------------------------------------------------------------------------------
1823 #include <rmr/rmr.h>
1824 rmr_mbuf_t* rmr_mt_rcv( void* vctx, rmr_mbuf_t* old_msg, int timeout );
1829 --------------------------------------------------------------------------------------------
1831 The rmr_mt_rcv function blocks until a message is received,
1832 or the timeout period (milliseconds) has passed. The result
1833 is an RMr message buffer which references a received message.
1834 In the case of a timeout the state will be reflected in an
1835 "empty buffer" (if old_msg was not nil, or simply with the
1836 return of a nil pointer. If a timeout value of zero (0) is
1837 given, then the function will block until the next message
1840 The *vctx* pointer is the pointer returned by the rmr_init
1841 function. *Old_msg* is a pointer to a previously used message
1842 buffer or NULL. The ability to reuse message buffers helps to
1843 avoid alloc/free cycles in the user application. When no
1844 buffer is available to supply, the receive function will
1847 The *old_msg* parameter allows the user to pass a previously
1848 generated RMr message back to RMr for reuse. Optionally, the
1849 user application may pass a nil pointer if no reusable
1850 message is available. When a timeout occurs, and old_msg was
1851 not nil, the state will be returned by returning a pointer to
1852 the old message with the state set.
1854 It is possible to use the *rmr_rcv_msg()* function instead of
1855 this function. Doing so might be advantagous if the user
1856 programme does not always start the multi-threaded mode and
1857 the use of *rmr_rcv_msg()* would make the flow of the code
1858 more simple. The advantags of using this function are the
1859 ability to set a timeout without using epoll, and a small
1860 performance gain (if multi-threaded mode is enabled, and the
1861 *rmr_rcv_msg()* function is used, it simply invokes this
1862 function without a timeout value, thus there is the small
1863 cost of a second call that results). Similarly, the
1864 *rmr_torcv_msg()* call can be used when in multi-threaded
1865 mode with the same "pass through" overhead to using this
1868 NOTE: Currently the multi-threaded functions are supported
1869 only when the NNG transport mechanism is being used. It will
1870 not be possible to link a programme using the nanomsg version
1871 of the library when references to this function are present.
1874 --------------------------------------------------------------------------------------------
1876 When a message is received before the timeout period expires,
1877 a pointer to the RMr message buffer which describes the
1878 message is returned. This will, with a high probability, be a
1879 different message buffer than *old_msg;* the user application
1880 should not continue to use *old_msg* after it is passed to
1883 In the event of a timeout the return value will be the old
1884 msg with the state set, or a nil pointer if no old message
1888 --------------------------------------------------------------------------------------------
1890 The *state* field in the message buffer will be set to one of
1891 the following values:
1897 The message was received without error.
1902 A parameter passed to the function was not valid (e.g. a
1903 nil pointer). indicate either RMR_OK or RMR_ERR_EMPTY if
1904 an empty message was received.
1909 The message received had no associated data. The length of
1910 the message will be 0.
1915 The multi-threaded option was not enabled when RMr was
1916 initialised. See the man page for *rmr_init()* for
1922 A hard error occurred preventing the receive from
1925 When a nil pointer is returned, or any other state value was
1926 set in the message buffer, errno will be set to one of the
1933 Parameter(s) passed to the function were not valid.
1938 The underlying message transport is unable to process the
1944 The underlying message transport is unable to process the
1950 The underlying message transport is unable to process the
1956 The underlying message transport is unable to process the
1962 The underlying message transport is unable to process the
1968 The underlying message transport is unable to process the
1974 The underlying message transport is unable to process the
1979 --------------------------------------------------------------------------------------------
1985 rmr_mbuf_t* mbuf = NULL; // received msg
1986 msg = rmr_mt_recv( mr, mbuf, 100 ); // wait up to 100ms
1988 switch( msg->state ) {
1990 printf( "got a good message\\n" );
1993 printf( "received timed out\\n" );
1996 printf( "receive error: %d\\n", mbuf->state );
2000 printf( "receive timeout (nil)\\n" );
2006 --------------------------------------------------------------------------------------------
2008 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
2009 rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3),
2010 rmr_mt_call(3), rmr_payload_size(3), rmr_send_msg(3),
2011 rmr_torcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
2012 rmr_ready(3), rmr_ring_free(3), rmr_torcv_msg(3)
2016 --------------------------------------------------------------------------------------------
2021 --------------------------------------------------------------------------------------------
2026 #include <rmr/rmr.h>
2027 int rmr_payload_size( rmr_mbuf_t* msg );
2032 --------------------------------------------------------------------------------------------
2034 Given a message buffer, this function returns the amount of
2035 space (bytes) available for the user application to consume
2036 in the message payload. This is different than the message
2037 length available as a field in the message buffer.
2040 --------------------------------------------------------------------------------------------
2042 The number of bytes available in the payload.
2045 --------------------------------------------------------------------------------------------
2051 Parameter(s) passed to the function were not valid.
2055 --------------------------------------------------------------------------------------------
2057 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2058 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
2059 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
2060 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
2064 --------------------------------------------------------------------------------------------
2069 --------------------------------------------------------------------------------------------
2074 #include <rmr/rmr.h>
2075 rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg );
2080 --------------------------------------------------------------------------------------------
2082 The rmr_rcv_msg function blocks until a message is received,
2083 returning the message to the caller via a pointer to a
2084 rmr_mbuf_t structure type. If messages were queued while
2085 waiting for the response to a previous invocation of
2086 rmr_call, the oldest message is removed from the queue and
2087 returned without delay.
2089 The *vctx* pointer is the pointer returned by the rmr_init
2090 function. *Old_msg* is a pointer to a previously used message
2091 buffer or NULL. The ability to reuse message buffers helps to
2092 avoid alloc/free cycles in the user application. When no
2093 buffer is available to supply, the receive function will
2097 --------------------------------------------------------------------------------------------
2099 The function returns a pointer to the rmr_mbuf_t structure
2100 which references the message information (state, length,
2101 payload), or a NULL pointer in the case of an extreme error.
2104 --------------------------------------------------------------------------------------------
2106 The *state* field in the message buffer will indicate either
2107 RMR_OK when the message receive process was successful and
2108 the message can be used by the caller. Depending on the
2109 underlying transport mechanism, one of the following RMR
2110 error stats may be returned:
2116 The message received had no payload, or was completely
2122 For some transport mechanisms, or if reading the receive
2123 queue from multiple threads, it is possible for one thread
2124 to find no data waiting when it queries the queue. When
2125 this state is reported, the message buffer does not
2126 contain message data and the user application should
2127 reinvoke the receive function.
2130 When an RMR error state is reported, the underlying errno
2131 value might provide more information. The following is a list
2132 of possible values that might accompany the states listed
2135 RMR_ERR_EMPTY if an empty message was received. If a nil
2136 pointer is returned, or any other state value was set in the
2137 message buffer, errno will be set to one of the following:
2143 Parameter(s) passed to the function were not valid.
2148 The underlying message transport is unable to process the
2154 The underlying message transport is unable to process the
2160 The underlying message transport is unable to process the
2166 The underlying message transport is unable to process the
2172 The underlying message transport is unable to process the
2178 The underlying message transport is unable to process the
2184 The underlying message transport is unable to process the
2189 --------------------------------------------------------------------------------------------
2193 --------------------------------------------------------------------------------------------
2195 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
2196 rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3),
2197 rmr_payload_size(3), rmr_send_msg(3), rmr_torcv_msg(3),
2198 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
2199 rmr_ring_free(3), rmr_torcv_msg(3)
2203 --------------------------------------------------------------------------------------------
2208 --------------------------------------------------------------------------------------------
2213 #include <rmr/rmr.h>
2214 int rmr_ready( void* vctx );
2219 --------------------------------------------------------------------------------------------
2221 The rmr_ready function checks to see if a routing table has
2222 been successfully received and installed. The return value
2223 indicates the state of readiness.
2226 --------------------------------------------------------------------------------------------
2228 A return value of 1 (true) indicates that the routing table
2229 is in place and attempts to send messages can be made. When 0
2230 is returned (false) the routing table has not been received
2231 and thus attempts to send messages will fail with *no
2235 --------------------------------------------------------------------------------------------
2237 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2238 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
2239 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_fib(3),
2240 rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
2245 --------------------------------------------------------------------------------------------
2250 --------------------------------------------------------------------------------------------
2255 #include <rmr/rmr.h>
2256 extern rmr_mbuf_t* rmr_realloc_payload( rmr_mbuf_t* msg, int new_len, int copy, int clone );
2261 --------------------------------------------------------------------------------------------
2263 The rmr_realloc_payload function will return a pointer to an
2264 RMR message buffer struct (rmr_mbuf_t) which has a payload
2265 large enough to accomodate *new_len* bytes. If necessary, the
2266 underlying payload is reallocated, and the bytes from the
2267 original payload are copied if the *copy* parameter is true
2268 (1). If the message passed in has a payload large enough,
2269 there is no additional memory allocation and copying.
2271 Cloning The Message Buffer
2272 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2274 This function can also be used to generate a separate copy of
2275 the original message, with the desired payload size, without
2276 destroying the original message buffer or the original
2277 payload. A standalone copy is made only when the *clone*
2278 parameter is true (1). When cloning, the payload is copied to
2279 the cloned message **only** if the *copy* parameter is true.
2281 Message Buffer Metadata
2282 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2284 The metadata in the original message buffer (message type,
2285 subscription ID, and payload length) will be preserved if the
2286 *copy* parameter is true. When this parameter is not true
2287 (0), then these values are set to the uninitialised value
2288 (-1) for type and ID, and the length is set to 0.
2291 --------------------------------------------------------------------------------------------
2293 The rmr_realloc_payload function returns a pointer to the
2294 message buffer with the payload which is large enough to hold
2295 *new_len* bytes. If the *clone* option is true, this will be
2296 a pointer to the newly cloned message buffer; the original
2297 message buffer pointer may still be used to referenced that
2298 message. It is the calling application's responsibility to
2299 free the memory associateed with both messages using the
2300 rmr_free_msg() function.
2302 When the *clone* option is not used, it is still good
2303 practice by the calling application to capture and use this
2304 reference as it is possible that the message buffer, and not
2305 just the payload buffer, was reallocated. In the event of an
2306 error, a nil pointer will be returned and the value of
2307 *errno* will be set to reflect the problem.
2310 --------------------------------------------------------------------------------------------
2312 These value of *errno* will reflect the error condition if a
2313 nil pointer is returned:
2319 Memory allocation of the new payload failed.
2324 The pointer passed in was nil, or refrenced an invalid
2325 message, or the required length was not valid.
2329 --------------------------------------------------------------------------------------------
2331 The following code bit illustrates how this function can be
2332 used to reallocate a buffer for a return to sender
2333 acknowledgement message which is larger than the message
2339 if( rmr_payload_size( msg ) < ack_sz ) { // received message too small for ack
2340 msg = rmr_realloc_payload( msg, ack_sz, 0, 0 ); // reallocate the message with a payload big enough
2342 fprintf( stderr, "[ERR] realloc returned a nil pointer: %s\\n", strerror( errno ) );
2344 } e// populate and send ack message
2351 --------------------------------------------------------------------------------------------
2353 rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3),
2354 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
2355 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
2356 rmr_fib(3), rmr_has_str(3), rmr_set_stimeout(3),
2357 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
2361 --------------------------------------------------------------------------------------------
2366 --------------------------------------------------------------------------------------------
2371 #include <rmr/rmr.h>
2372 rmr_mbuf_t* rmr_rts_msg( void* vctx, rmr_mbuf_t* msg );
2377 --------------------------------------------------------------------------------------------
2379 The rmr_rts_msg function sends a message returning it to the
2380 endpoint which sent the message rather than selecting an
2381 endpoint based on the message type and routing table. Other
2382 than this small difference, the behaviour is exactly the same
2386 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2388 The send operations in RMr will retry *soft* send failures
2389 until one of three conditions occurs:
2395 The message is sent without error
2400 The underlying transport reports a * hard * failure
2405 The maximum number of retry loops has been attempted
2408 A retry loop consists of approximately 1000 send attemps **
2409 without** any intervening calls to * sleep() * or * usleep().
2410 * The number of retry loops defaults to 1, thus a maximum of
2411 1000 send attempts is performed before returning to the user
2412 application. This value can be set at any point after RMr
2413 initialisation using the * rmr_set_stimeout() * function
2414 allowing the user application to completely disable retires
2415 (set to 0), or to increase the number of retry loops.
2417 Transport Level Blocking
2418 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2420 The underlying transport mechanism used to send messages is
2421 configured in *non-blocking* mode. This means that if a
2422 message cannot be sent immediately the transport mechanism
2423 will **not** pause with the assumption that the inability to
2424 send will clear quickly (within a few milliseconds). This
2425 means that when the retry loop is completely disabled (set to
2426 0), that the failure to accept a message for sending by the
2427 underlying mechanisms (software or hardware) will be reported
2428 immediately to the user application.
2430 It should be noted that depending on the underlying transport
2431 mechanism being used, it is extremly possible that during
2432 normal operations that retry conditions are very likely to
2433 happen. These are completely out of RMr's control, and there
2434 is nothing that RMr can do to avoid or midigate these other
2435 than by allowing RMr to retry the send operation, and even
2436 then it is possible (e.g. during connection reattempts), that
2437 a single retry loop is not enough to guarentee a successful
2441 --------------------------------------------------------------------------------------------
2443 When crafting a response based on a received message, the
2444 user application must take care not to write more bytes to
2445 the message payload than the allocated message has. In the
2446 case of a received message, it is possible that the response
2447 needs to be larger than the payload associated with the
2448 inbound message. In order to use the return to sender
2449 function, the source infomration in the orignal message must
2450 be present in the response; information which cannot be added
2451 to a message buffer allocated through the standard RMR
2452 allocation function. To allocate a buffer with a larger
2453 payload, and which retains the necessary sender data needed
2454 by this function, the *rmr_realloc_payload()* function must
2455 be used to extend the payload to a size suitable for the
2459 --------------------------------------------------------------------------------------------
2461 On success, a new message buffer, with an empty payload, is
2462 returned for the application to use for the next send. The
2463 state in this buffer will reflect the overall send operation
2464 state and should be RMR_OK.
2466 If the state in the returned buffer is anything other than
2467 UT_OK, the user application may need to attempt a
2468 retransmission of the message, or take other action depending
2469 on the setting of errno as described below.
2471 In the event of extreme failure, a NULL pointer is returned.
2472 In this case the value of errno might be of some use, for
2473 documentation, but there will be little that the user
2474 application can do other than to move on.
2477 --------------------------------------------------------------------------------------------
2479 The following values may be passed back in the *state* field
2480 of the returned message buffer.
2486 The message buffer pointer did not refer to a valid
2491 The header in the message buffer was not valid or
2496 The message type in the message buffer did not map to a
2501 The send failed; errno has the possible reason.
2504 The following values may be assigned to errno on failure.
2509 Parameter(s) passed to the function were not valid, or the
2510 underlying message processing environment was unable to
2511 interpret the message.
2516 The header information in the message buffer was invalid.
2521 No known endpoint for the message could be found.
2526 The underlying transport refused to accept the message
2527 because of a size value issue (message was not attempted
2533 The message referenced by the message buffer is corrupt
2534 (NULL pointer or bad internal length).
2539 Internal RMR error; information provided to the message
2540 transport environment was not valid.
2545 Sending was not supported by the underlying message
2551 The device is not in a state that can accept the message.
2556 The device is not able to accept a message for sending.
2557 The user application should attempt to resend.
2562 The operation was interrupted by delivery of a signal
2563 before the message was sent.
2568 The underlying message environment timed out during the
2574 The underlying message environment is in a shutdown state.
2578 --------------------------------------------------------------------------------------------
2582 --------------------------------------------------------------------------------------------
2584 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2585 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
2586 rmr_rcv_specific(3), rmr_ready(3), rmr_fib(3),
2587 rmr_has_str(3), rmr_set_stimeout(3), rmr_tokenise(3),
2588 rmr_mk_ring(3), rmr_ring_free(3)
2592 --------------------------------------------------------------------------------------------
2597 --------------------------------------------------------------------------------------------
2602 #include <rmr/rmr.h>
2603 rmr_mbuf_t* rmr_send_msg( void* vctx, rmr_mbuf_t* msg );
2608 --------------------------------------------------------------------------------------------
2610 The rmr_send_msg function accepts a message buffer from the
2611 user application and attempts to send it. The destination of
2612 the message is selected based on the message type specified
2613 in the message buffer, and the matching information in the
2614 routing tables which are currently in use by the RMR library.
2615 This may actually result in the sending of the message to
2616 multiple destinations which could degrade expected overall
2617 performance of the user application. (Limiting excessive
2618 sending of messages is the responsibility of the
2619 application(s) responsible for building the routing table
2620 used by the RMR library, and not the responsibility of the
2624 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2626 The send operations in RMr will retry *soft* send failures
2627 until one of three conditions occurs:
2633 The message is sent without error
2638 The underlying transport reports a * hard * failure
2643 The maximum number of retry loops has been attempted
2646 A retry loop consists of approximately 1000 send attemps **
2647 without** any intervening calls to * sleep() * or * usleep().
2648 * The number of retry loops defaults to 1, thus a maximum of
2649 1000 send attempts is performed before returning to the user
2650 application. This value can be set at any point after RMr
2651 initialisation using the * rmr_set_stimeout() * function
2652 allowing the user application to completely disable retires
2653 (set to 0), or to increase the number of retry loops.
2655 Transport Level Blocking
2656 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2658 The underlying transport mechanism used to send messages is
2659 configured in *non-blocking* mode. This means that if a
2660 message cannot be sent immediately the transport mechanism
2661 will **not** pause with the assumption that the inability to
2662 send will clear quickly (within a few milliseconds). This
2663 means that when the retry loop is completely disabled (set to
2664 0), that the failure to accept a message for sending by the
2665 underlying mechanisms (software or hardware) will be reported
2666 immediately to the user application.
2668 It should be noted that depending on the underlying transport
2669 mechanism being used, it is extremly possible that during
2670 normal operations that retry conditions are very likely to
2671 happen. These are completely out of RMr's control, and there
2672 is nothing that RMr can do to avoid or midigate these other
2673 than by allowing RMr to retry the send operation, and even
2674 then it is possible (e.g. during connection reattempts), that
2675 a single retry loop is not enough to guarentee a successful
2679 --------------------------------------------------------------------------------------------
2681 On success, a new message buffer, with an empty payload, is
2682 returned for the application to use for the next send. The
2683 state in this buffer will reflect the overall send operation
2684 state and will be RMR_OK when the send was successful.
2686 When the message cannot be successfully sent this function
2687 will return the unsent (original) message buffer with the
2688 state set to indicate the reason for failure. The value of
2689 *errno* may also be set to reflect a more detailed failure
2690 reason if it is known.
2692 In the event of extreme failure, a NULL pointer is returned.
2693 In this case the value of errno might be of some use, for
2694 documentation, but there will be little that the user
2695 application can do other than to move on.
2697 **CAUTION:** In some cases it is extremely likely that the
2698 message returned by the send function does **not** reference
2699 the same memory structure. Thus is important for the user
2700 programme to capture the new pointer for future use or to be
2701 passed to rmr_free(). If you are experiencing either double
2702 free errors or segment faults in either rmr_free() or
2703 rmr_send_msg(), ensure that the return value from this
2704 function is being captured and used.
2707 --------------------------------------------------------------------------------------------
2709 The following values may be passed back in the *state* field
2710 of the returned message buffer.
2716 The message could not be sent, but the underlying
2717 transport mechanism indicates that the failure is
2718 temporary. If the send operation is tried again it might
2723 The send operation was not successful and the underlying
2724 transport mechanism indicates a permanent (hard) failure;
2725 retrying the send is not possible.
2729 The message buffer pointer did not refer to a valid
2734 The header in the message buffer was not valid or
2739 The message type in the message buffer did not map to a
2743 The following values may be assigned to errno on failure.
2748 Parameter(s) passed to the function were not valid, or the
2749 underlying message processing environment was unable to
2750 interpret the message.
2755 The header information in the message buffer was invalid.
2760 No known endpoint for the message could be found.
2765 The underlying transport refused to accept the message
2766 because of a size value issue (message was not attempted
2772 The message referenced by the message buffer is corrupt
2773 (NULL pointer or bad internal length).
2778 Internal RMR error; information provided to the message
2779 transport environment was not valid.
2784 Sending was not supported by the underlying message
2790 The device is not in a state that can accept the message.
2795 The device is not able to accept a message for sending.
2796 The user application should attempt to resend.
2801 The operation was interrupted by delivery of a signal
2802 before the message was sent.
2807 The underlying message environment timed out during the
2813 The underlying message environment is in a shutdown state.
2817 --------------------------------------------------------------------------------------------
2819 The following is a simple example of how the rmr_send_msg
2820 function is called. In this example, the send message buffer
2821 is saved between calls and reused eliminating alloc/free
2827 static rmr_mbuf_t* send_msg = NULL; // message to send; reused on each call
2828 msg_t* send_pm; // payload for send
2829 msg_t* pm; // our message format in the received payload
2830 mif( send_msg == NULL ) {
2831 send_msg = rmr_alloc_msg( mr, MAX_SIZE ); r// new buffer to send
2833 // reference payload and fill in message type
2834 pm = (msg_t*) send_msg->payload;
2835 send_msg->mtype = MT_ANSWER;
2836 msg->len = generate_data( pm ); // something that fills the payload in
2837 msg = rmr_send_msg( mr, send_msg ); // ensure new pointer used after send
2841 m sif( msg->state != RMR_OK ) {
2842 m s m// check for RMR_ERR_RETRY, and resend if needed
2843 m s m// else return error
2851 --------------------------------------------------------------------------------------------
2853 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2854 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
2855 rmr_rts_msg(3), rmr_ready(3), rmr_mk_ring(3),
2856 rmr_ring_free(3), rmr_torcv_rcv(3), rmr_wh_send_msg(3)
2860 --------------------------------------------------------------------------------------------
2865 --------------------------------------------------------------------------------------------
2870 #include <rmr/rmr.h>
2871 void rmr_set_fack( void* vctx );
2876 --------------------------------------------------------------------------------------------
2878 The rmr_set_fack function enables *fast TCP acknowledgements*
2879 if the underlying transport library supports it. This might
2880 be useful for applications which must send messages as a
2884 --------------------------------------------------------------------------------------------
2886 There is no return value.
2889 --------------------------------------------------------------------------------------------
2891 This function does not generate any errors.
2894 --------------------------------------------------------------------------------------------
2900 --------------------------------------------------------------------------------------------
2905 --------------------------------------------------------------------------------------------
2910 #include <rmr/rmr.h>
2911 rmr_mbuf_t* rmr_set_stimeout( void* vctx, int rloops );
2916 --------------------------------------------------------------------------------------------
2918 The rmr_set_stimeout function sets the configuration for how
2919 RMr will retry message send operations which complete with
2920 either a *timeout* or *again* completion value. (Send
2921 operations include all of the possible message send
2922 functions: *rmr_send_msg(), rmr_call(), rmr_rts_msg()* and
2923 *rmr_wh_send_msg().* The *rloops* parameter sets the maximum
2924 number of retry loops that will be attempted before giving up
2925 and returning the unsuccessful state to the user application.
2926 Each retry loop is approximately 1000 attempts, and RMr does
2927 **not** invoke any sleep function between retries in the
2928 loop; a small, 1 mu-sec, sleep is executed between loop sets
2929 if the *rloops* value is greater than 1.
2933 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2935 By default, the send operations will execute with an *rloop*
2936 setting of 1; each send operation will attempt to resend the
2937 message approximately 1000 times before giving up. If the
2938 user application does not want to have send operations retry
2939 when the underlying transport mechanism indicates *timeout*
2940 or *again,* the application should invoke this function and
2941 pass a value of 0 (zero) for *rloops.* With this setting, all
2942 RMr send operations will attempt a send operation only
2943 **once,** returning immediately to the caller with the state
2944 of that single attempt.
2947 --------------------------------------------------------------------------------------------
2949 This function returns a -1 to indicate that the *rloops*
2950 value could not be set, and the value *RMR_OK* to indicate
2954 --------------------------------------------------------------------------------------------
2956 Currently errno is **not** set by this function; the only
2957 cause of a failure is an invalid context (*vctx*) pointer.
2960 --------------------------------------------------------------------------------------------
2962 The following is a simple example of how the rmr_set_stimeout
2969 char* Oport = "43086"; // port for message router listen
2970 int rmax_size = 4096; // max message size for default allocations
2971 void* mr_context; // message router context
2972 mr_context = rmr_init( port, max_size, NO_FLAGS );
2973 if( mr_context != NULL ) {
2974 rmr_set_stimeout( mr_context, 0 ); // turn off retries
2980 --------------------------------------------------------------------------------------------
2982 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2983 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
2984 rmr_rts_msg(3), rmr_ready(3), rmr_mk_ring(3),
2985 rmr_ring_free(3), rmr_send_msg(3), rmr_torcv_rcv(3),
2990 --------------------------------------------------------------------------------------------
2995 --------------------------------------------------------------------------------------------
3000 #include <rmr/rmr.h>
3001 int rmr_set_trace( rmr_mbuf_t* mbuf, unsigned char* data, int len )
3006 --------------------------------------------------------------------------------------------
3008 The rmr_set_trace function will copy len bytes from data into
3009 the trace portion of mbuf. If the trace area of mbuf is not
3010 the correct size, the message buffer will be reallocated to
3011 ensure that enough space is available for the trace data.
3014 --------------------------------------------------------------------------------------------
3016 The rmr_set_trace function returns the number of bytes
3017 successfully copied to the message. If 0 is returned either
3018 the message pointer was nil, or the size in the parameters
3022 --------------------------------------------------------------------------------------------
3024 rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3),
3025 rmr_bytes2payload(3), rmr_call(3), rmr_free_msg(3),
3026 rmr_get_rcvfd(3), rmr_get_meid(3), rmr_get_trace(3),
3027 rmr_get_trlen(3), rmr_init(3), rmr_init_trace(3),
3028 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
3029 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
3030 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
3031 rmr_ring_free(3), rmr_str2meid(3), rmr_str2xact(3),
3032 rmr_wh_open(3), rmr_wh_send_msg(3)
3036 --------------------------------------------------------------------------------------------
3041 --------------------------------------------------------------------------------------------
3046 #include <rmr/rmr.h>
3047 #include <rmr/rmr_logging.h>
3048 void rmr_set_vlevel( int new_level )
3053 --------------------------------------------------------------------------------------------
3055 The rmr_set_vlevel allows the user programme to set the
3056 verbosity level which is used to determine the messages RMR
3057 writes to standard error. The new_vlevel value must be one of
3058 the following constants which have the indicated meanings:
3063 Turns off all message writing. This includes the stats and
3064 debugging messages generated by the route collector thread
3065 which are normally affected only by the externally managed
3066 verbose level file (and related environment variable).
3071 Write only messages of critical importance. From the point
3072 of view of RMR, when a critical proper behaviour of the
3073 library cannot be expected or guaranteed.
3077 Include error messages in the output. An error is an event
3078 from which RMR has no means to recover. Continued proper
3079 execution is likely except where the affected connection
3080 and/or component mentioned in the error is concerned.
3084 Include warning messages in the output. A warning
3085 indicates an event which is not considered to be normal,
3086 but is expected and continued acceptable behaviour of the
3091 Include informational messagees in the output.
3092 Informational messages include some diagnostic information
3093 which explain the activities of RMR.
3097 Include all debugging messages in the output. Debugging
3098 must have also been enabled during the build as a
3099 precaution to accidentally enabling this level of output
3100 as it can grossly affect performance.
3103 generally RMR does not write messages to the standard error
3104 device from *critical path* functions, therefore it is
3105 usually not harmful to enable a verbosity level of either
3106 RMR_VL_CRIT, or RMR_VL_ERR.
3108 Messages written from the route table collection thread are
3109 still governed by the value placed into the verbose level
3110 control file (see the man page for rmr_init()); those
3111 messages are affected only when logging is completely
3112 disabled by passing RMR_VL_OFF to this function.
3114 The verbosity level can also be set via an environment
3115 variable prior to the start of the RMR based application. The
3116 environment variable is read only during initialisation; if
3117 the programme must change the value during execution, this
3118 function must be used. The default value, if this function is
3119 never called, and the environment variable is not present, is
3123 --------------------------------------------------------------------------------------------
3129 --------------------------------------------------------------------------------------------
3134 --------------------------------------------------------------------------------------------
3139 #include <rmr/rmr.h>
3140 int rmr_str2meid( rmr_mbuf_t* mbuf, unsigned char* src, int len )
3145 --------------------------------------------------------------------------------------------
3147 The rmr_str2meid function will copy the string pointed to by
3148 src to the managed entity ID (meid) field in the given
3149 message. The field is a fixed length, gated by the constant
3150 RMR_MAX_MEID and if string length is larger than this value,
3151 then **nothing** will be copied. (Note, this differs slightly
3152 from the behaviour of the lrmr_bytes2meid() function.)
3155 --------------------------------------------------------------------------------------------
3157 On success, the value RMR_OK is returned. If the string
3158 cannot be copied to the message, the return value will be one
3159 of the errors listed below.
3162 --------------------------------------------------------------------------------------------
3164 If the return value is not RMR_OK, then it will be set to one
3165 of the values below.
3171 The message, or an internal portion of the message, was
3172 corrupted or the pointer was invalid.
3177 The length passed in was larger than the maximum length of
3178 the field; only a portion of the source bytes were copied.
3182 --------------------------------------------------------------------------------------------
3186 --------------------------------------------------------------------------------------------
3188 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
3189 rmr_get_meid(3), rmr_get_rcvfd(3), rmr_payload_size(3),
3190 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
3191 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
3192 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
3193 rmr_bytes2meid(3), rmr_wh_open(3), rmr_wh_send_msg(3)
3197 --------------------------------------------------------------------------------------------
3202 --------------------------------------------------------------------------------------------
3207 #include <rmr/rmr.h>
3208 int rmr_str2xact( rmr_mbuf_t* mbuf, unsigned char* src, int len )
3213 --------------------------------------------------------------------------------------------
3215 The rmr_str2xact function will copy the string pointed to by
3216 src to the transaction ID (xaction) field in the given
3217 message. The field is a fixed length, gated by the constant
3218 RMR_MAX_XID and if string length is larger than this value,
3219 then **nothing** will be copied. (Note, this differs slightly
3220 from the behaviour of the lrmr_bytes2xact() function.)
3224 --------------------------------------------------------------------------------------------
3226 On success, the value RMR_OK is returned. If the string
3227 cannot be copied to the message, the return value will be
3228 one of the errors listed below.
3231 --------------------------------------------------------------------------------------------
3233 If the return value is not RMR_OK, then it will be set to
3234 one of the values below.
3239 The message, or an internal portion of the message, was
3240 corrupted or the pointer was invalid.
3245 The length passed in was larger than the maximum length of
3246 the field; only a portion of the source bytes were copied.
3250 --------------------------------------------------------------------------------------------
3254 --------------------------------------------------------------------------------------------
3256 rmr_alloc_msg(3), rmr_bytes2meid(3), rmr_bytes2xact(3),
3257 rmr_call(3), rmr_free_msg(3), rmr_get_meid(3),
3258 rmr_get_rcvfd(3), rmr_get_xact(3), rmr_payload_size(3),
3259 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
3260 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
3261 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
3262 rmr_str2meid(3), rmr_wh_open(3), rmr_wh_send_msg(3)
3266 --------------------------------------------------------------------------------------------
3268 RMR support functions
3271 --------------------------------------------------------------------------------------------
3276 #include <rmr/rmr.h>
3277 #include <rmr/ring_inline.h>
3278 char* rmr_fib( char* fname );
3279 int rmr_has_str( char const* buf, char const* str, char sep, int max );
3280 int rmr_tokenise( char* buf, char** tokens, int max, char sep );
3281 void* rmr_mk_ring( int size );
3282 void rmr_ring_free( void* vr );
3283 static inline void* rmr_ring_extract( void* vr )
3284 static inline int rmr_ring_insert( void* vr, void* new_data )
3289 --------------------------------------------------------------------------------------------
3291 These functions support the RMR library, and are made
3292 available to user applications as some (e.g. route table
3293 generators) might need and/or want to make use of them. The
3294 rmr_fib function accepts a file name and reads the entire
3295 file into a single buffer. The intent is to provide an easy
3296 way to load a static route table without a lot of buffered
3299 The rmr_has_str function accepts a *buffer* containing a set
3300 of delimited tokens (e.g. foo,bar,goo) and returns true if
3301 the target string, *str,* matches one of the tokens. The
3302 *sep* parameter provides the separation character in the
3303 buffer (e.g a comma) and *max* indicates the maximum number
3304 of tokens to split the buffer into before checking.
3306 The rmr_tokenise function is a simple tokeniser which splits
3307 *buf* into tokens at each occurrence of *sep*. Multiple
3308 occurrences of the separator character (e.g. a,,b) result in
3309 a nil token. Pointers to the tokens are placed into the
3310 *tokens* array provided by the caller which is assumed to
3311 have at least enough space for *max* entries.
3313 The rmr_mk_ring function creates a buffer ring with *size*
3316 The rmr_ring_free function accepts a pointer to a ring
3317 context and frees the associated memory.
3319 The rmr_ring_insert and rmr_ring_extract functions are
3320 provided as static inline functions via the
3321 *rmr/ring_inline.h* header file. These functions both accept
3322 the ring *context* returned by mk_ring, and either insert a
3323 pointer at the next available slot (tail) or extract the data
3327 --------------------------------------------------------------------------------------------
3329 The following are the return values for each of these
3332 The rmr_fib function returns a pointer to the buffer
3333 containing the contents of the file. The buffer is terminated
3334 with a single nil character (0) making it a legitimate C
3335 string. If the file was empty or nonexistent, a buffer with
3336 an immediate nil character. If it is important to the calling
3337 programme to know if the file was empty or did not exist, the
3338 caller should use the system stat function call to make that
3341 The rmr_has_str function returns 1 if *buf* contains the
3342 token referenced by &ita and false (0) if it does not. On
3343 error, a -1 value is returned and errno is set accordingly.
3345 The rmr_tokenise function returns the actual number of token
3346 pointers placed into *tokens*
3348 The rmr_mk_ring function returns a void pointer which is the
3349 *context* for the ring.
3351 The rmr_ring_insert function returns 1 if the data was
3352 successfully inserted into the ring, and 0 if the ring is
3353 full and the pointer could not be deposited.
3355 The rmr_ring_extract will return the data which is at the
3356 head of the ring, or NULL if the ring is empty.
3359 --------------------------------------------------------------------------------------------
3361 Not many of these functions set the value in errno, however
3362 the value may be one of the following:
3367 Parameter(s) passed to the function were not valid.
3371 --------------------------------------------------------------------------------------------
3375 --------------------------------------------------------------------------------------------
3377 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
3378 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
3379 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
3383 --------------------------------------------------------------------------------------------
3388 --------------------------------------------------------------------------------------------
3393 #include <rmr/rmr.h>
3394 rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to );
3399 --------------------------------------------------------------------------------------------
3401 The rmr_torcv_msg function will pause for *ms_to*
3402 milliseconds waiting for a message to arrive. If a message
3403 arrives before the timeout expires the message buffer
3404 returned will have a status of RMR_OK and the payload will
3405 contain the data received. If the timeout expires before the
3406 message is received, the status will have the value
3407 RMR_ERR_TIMEOUT. When a received message is returned the
3408 message buffer will also contain the message type and length
3409 set by the sender. If messages were queued while waiting for
3410 the response to a previous invocation of rmr_call, the oldest
3411 message is removed from the queue and returned without delay.
3413 The *vctx* pointer is the pointer returned by the rmr_init
3414 function. *Old_msg* is a pointer to a previously used message
3415 buffer or NULL. The ability to reuse message buffers helps to
3416 avoid alloc/free cycles in the user application. When no
3417 buffer is available to supply, the receive function will
3421 --------------------------------------------------------------------------------------------
3423 The function returns a pointer to the rmr_mbuf_t structure
3424 which references the message information (state, length,
3425 payload), or a NULL pointer in the case of an extreme error.
3428 --------------------------------------------------------------------------------------------
3430 The *state* field in the message buffer will be one of the
3437 The message buffer (payload) references the received data.
3442 The first call to this function must initialise an
3443 underlying system notification mechanism. On failure, this
3444 error is returned and errno will have the system error
3445 status set. If this function fails to intialise, the poll
3446 mechansim, it is likely that message receives will never
3452 The timeout expired before a complete message was
3453 received. All other fields in the message buffer are not
3459 A message was received, but it had no payload. All other
3460 fields in the message buffer are not valid.
3467 Parameter(s) passed to the function were not valid.
3472 The underlying message transport is unable to process the
3478 The underlying message transport is unable to process the
3484 The underlying message transport is unable to process the
3490 The underlying message transport is unable to process the
3496 The underlying message transport is unable to process the
3502 The underlying message transport is unable to process the
3508 The underlying message transport is unable to process the
3513 --------------------------------------------------------------------------------------------
3517 --------------------------------------------------------------------------------------------
3519 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
3520 rmr_get_rcvfd(3), rmr_init(3), rmr_payload_size(3),
3521 rmr_rcv_msg(3), rmr_send_msg(3), rmr_rcv_specific(3),
3522 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
3523 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
3527 --------------------------------------------------------------------------------------------
3532 --------------------------------------------------------------------------------------------
3537 #include <rmr/rmr.h>
3538 int rmr_trace_ref( rmr_mbuf_t* mbuf, int* sizeptr )
3543 --------------------------------------------------------------------------------------------
3545 The rmr_trace_ref function return a pointer to the trace area
3546 in the message, and optionally populate the user programme
3547 supplied size integer with the trace area size, if *sizeptr*
3551 --------------------------------------------------------------------------------------------
3553 On success, a void pointer to the trace area of the message
3554 is returned. A nil pointer is returned if the message has no
3555 trace data area allocated, or if the message itself is
3559 --------------------------------------------------------------------------------------------
3561 rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3),
3562 rmr_bytes2meid(3), rmr_call(3), rmr_free_msg(3),
3563 rmr_get_rcvfd(3), rmr_get_trlen(3), rmr_init(3),
3564 rmr_init_trace(3), rmr_payload_size(3), rmr_send_msg(3),
3565 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
3566 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
3567 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
3568 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3),
3573 --------------------------------------------------------------------------------------------
3578 --------------------------------------------------------------------------------------------
3583 #include <rmr/rmr.h>
3584 rmr_mbuf_t* rmr_tralloc_msg( void* vctx, int size,
3585 int trace_size, unsigned const char *tr_data );
3590 --------------------------------------------------------------------------------------------
3592 The rmr_alloc_msg function is used to allocate a buffer which
3593 the user programme can write into and then send through the a
3594 library. The buffer is allocated such that sending it
3595 requires no additional copying from the buffer as it passes
3596 through the underlying transport mechanism.
3598 The *size* parameter is used to set the payload length in the
3599 message and If it is 0, then the default size supplied on the
3600 *rmr_init* call will be used. In addition to allocating the
3601 payload, a space in the buffer is reserved for *trace* data
3602 (tr_size bytes), and the bytes pointed to by *tr_data* are
3603 copied into that portion of the message. The *vctx* parameter
3604 is the void context pointer that was returned by the
3605 *rmr_init* function.
3607 The pointer to the message buffer returned is a structure
3608 which has some user application visible fields; the structure
3609 is described in rmr.h, and is illustrated below.
3618 unsigned char* payload;
3619 unsigned char* xaction;
3628 Is the current buffer state. Following a call to
3629 rmr_send_msg the state indicates whether the buffer was
3630 successfully sent which determines exactly what the
3631 payload points to. If the send failed, the payload
3632 referenced by the buffer is the message that failed to
3633 send (allowing the application to attempt a
3634 retransmission). When the state is a_OK the buffer
3635 represents an empty buffer that the application may fill
3636 in in preparation to send.
3641 When sending a message, the application is expected to set
3642 this field to the appropriate message type value (as
3643 determined by the user programme). Upon send this value
3644 determines how the a library will route the message. For a
3645 buffer which has been received, this field will contain
3646 the message type that was set by the sending application.
3651 The application using a buffer to send a message is
3652 expected to set the length value to the actual number of
3653 bytes that it placed into the message. This is likely less
3654 than the total number of bytes that the message can carry.
3655 For a message buffer that is passed to the application as
3656 the result of a receive call, this will be the value that
3657 the sending application supplied and should indicate the
3658 number of bytes in the payload which are valid.
3663 The payload is a pointer to the actual received data. The
3664 user programme may read and write from/to the memory
3665 referenced by the payload up until the point in time that
3666 the buffer is used on a rmr_send, rmr_call or rmr_reply
3667 function call. Once the buffer has been passed back to a a
3668 library function the user programme should **NOT** make
3669 use of the payload pointer.
3674 The *xaction* field is a pointer to a fixed sized area in
3675 the message into which the user may write a transaction
3676 ID. The ID is optional with the exception of when the user
3677 application uses the rmr_call function to send a message
3678 and wait for the reply; the underlying a processing
3679 expects that the matching reply message will also contain
3680 the same data in the *xaction* field.
3684 --------------------------------------------------------------------------------------------
3686 The function returns a pointer to a rmr_mbuf structure, or
3690 --------------------------------------------------------------------------------------------
3696 Unable to allocate memory.
3700 --------------------------------------------------------------------------------------------
3702 rmr_alloc_msg(3), rmr_mbuf(3) rmr_call(3), rmr_free_msg(3),
3703 rmr_init(3), rmr_init_trace(3), rmr_get_trace(3),
3704 rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
3705 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
3706 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
3707 rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)
3711 --------------------------------------------------------------------------------------------
3716 --------------------------------------------------------------------------------------------
3721 #include <rmr/rmr.h>
3722 rmr_mbuf_t* rmr_wh_call( void* vctx, rmr_whid_t whid, rmr_mbuf_t* msg, int call_id, int max_wait )
3727 --------------------------------------------------------------------------------------------
3729 The rmr_wh_call function accepts a message buffer (msg) from
3730 the user application and attempts to send it using the
3731 wormhole ID provided (whid). If the send is successful, the
3732 call will block until either a response message is received,
3733 or the max_wait number of milliseconds has passed. In order
3734 for the response to be recognised as a response, the remote
3735 process **must** use rmr_rts_msg() to send their response.
3737 Like *rmr_wh_send_msg,* this function attempts to send the
3738 message directly to a process at the other end of a wormhole
3739 which was created with *rmr_wh-open().* When sending message
3740 via wormholes, the normal RMr routing based on message type
3741 is ignored, and the caller may leave the message type
3742 unspecified in the message buffer (unless it is needed by the
3743 receiving process). The call_id parameter is a number in the
3744 range of 2 through 255 and is used to identify the calling
3745 thread in order to properly match a response message when it
3746 arrives. Providing this value, and ensuring the proper
3747 uniqueness, is the responsibility of the user application and
3748 as such the ability to use the rmr_wh_call() function from
3749 potentially non-threaded concurrent applications (such as
3750 Go's goroutines) is possible.
3753 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3755 The send operations in RMr will retry *soft* send failures
3756 until one of three conditions occurs:
3762 The message is sent without error
3767 The underlying transport reports a * hard * failure
3772 The maximum number of retry loops has been attempted
3775 A retry loop consists of approximately 1000 send attemps **
3776 without** any intervening calls to * sleep() * or * usleep().
3777 * The number of retry loops defaults to 1, thus a maximum of
3778 1000 send attempts is performed before returning to the user
3779 application. This value can be set at any point after RMr
3780 initialisation using the * rmr_set_stimeout() * function
3781 allowing the user application to completely disable retires
3782 (set to 0), or to increase the number of retry loops.
3784 Transport Level Blocking
3785 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3787 The underlying transport mechanism used to send messages is
3788 configured in *non-blocking* mode. This means that if a
3789 message cannot be sent immediately the transport mechanism
3790 will **not** pause with the assumption that the inability to
3791 send will clear quickly (within a few milliseconds). This
3792 means that when the retry loop is completely disabled (set to
3793 0), that the failure to accept a message for sending by the
3794 underlying mechanisms (software or hardware) will be reported
3795 immediately to the user application.
3797 It should be noted that depending on the underlying transport
3798 mechanism being used, it is extremly possible that during
3799 normal operations that retry conditions are very likely to
3800 happen. These are completely out of RMr's control, and there
3801 is nothing that RMr can do to avoid or midigate these other
3802 than by allowing RMr to retry the send operation, and even
3803 then it is possible (e.g. during connection reattempts), that
3804 a single retry loop is not enough to guarentee a successful
3808 --------------------------------------------------------------------------------------------
3810 On success, new message buffer, with the payload containing
3811 the response from the remote endpoint is returned. The state
3812 in this buffer will reflect the overall send operation state
3813 and should be RMR_OK.
3815 If a message is returned with a state which is anything other
3816 than RMR_OK, the indication is that the send was not
3817 successful. The user application must check the state and
3818 determine the course of action. If the return value is NULL,
3819 no message, the indication is that there was no response
3820 received within the timeout (max_wait) period of time.
3823 --------------------------------------------------------------------------------------------
3825 The following values may be passed back in the *state* field
3826 of the returned message buffer.
3832 The wormhole ID passed in was not associated with an open
3833 wormhole, or was out of range for a valid ID.
3837 No wormholes exist, further attempt to validate the ID are
3842 The message buffer pointer did not refer to a valid
3847 The header in the message buffer was not valid or
3852 --------------------------------------------------------------------------------------------
3854 The following is a simple example of how the a wormhole is
3855 created (rmr_wh_open) and then how rmr_wh_send_msg function
3856 is used to send messages. Some error checking is omitted for
3862 #include <rmr/rmr.h> .// system headers omitted for clarity
3864 rmr_whid_t whid = -1; // wormhole id for sending
3865 void* mrc; //msg router context
3867 rmr_mbuf_t* sbuf; // send buffer
3869 mrc = rmr_init( "43086", RMR_MAX_RCV_BYTES, RMRFL_NONE );
3871 fprintf( stderr, "[FAIL] unable to initialise RMr environment\\n" );
3874 while( ! rmr_ready( mrc ) ) { e i// wait for routing table info
3877 sbuf = rmr_alloc_msg( mrc, 2048 );
3880 whid = rmr_wh_open( mrc, "localhost:6123" ); // open fails if endpoint refuses conn
3881 w if( RMR_WH_CONNECTED( wh ) ) {
3882 snprintf( sbuf->payload, 1024, "periodic update from sender: %d", count++ );
3883 sbuf->len = strlen( sbuf->payload );
3884 sbuf = rmr_wh_call( mrc, whid, sbuf, 1000 ); f s// expect a response in 1s or less
3885 if( sbuf != NULL && sbuf->state = RMR_OK ) {
3886 sprintf( stderr, "response: %s\\n", sbuf->payload ); x// assume they sent a string
3888 sprintf( stderr, "response not received, or send error\\n" );
3899 --------------------------------------------------------------------------------------------
3901 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
3902 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
3903 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
3904 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
3905 rmr_set_stimeout(3), rmr_wh_open(3), rmr_wh_close(3),
3910 --------------------------------------------------------------------------------------------
3915 --------------------------------------------------------------------------------------------
3920 #include <rmr/rmr.h>
3921 void rmr_close( void* vctx, rmr_whid_t whid )
3926 --------------------------------------------------------------------------------------------
3928 The rmr_wh_close function closes the wormhole associated with
3929 the wormhole id passed in. Future calls to rmr_wh_send_msg
3930 with this ID will fail.
3932 The underlying TCP connection to the remote endpoint is
3933 **not** closed as this session may be reqruired for
3934 regularlly routed messages (messages routed based on message
3935 type). There is no way to force a TCP session to be closed at
3939 --------------------------------------------------------------------------------------------
3941 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
3942 rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3),
3943 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
3944 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
3945 rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_open(3),
3950 --------------------------------------------------------------------------------------------
3955 --------------------------------------------------------------------------------------------
3960 #include <rmr/rmr.h>
3961 void* rmr_wh_open( void* vctx, char* target )
3966 --------------------------------------------------------------------------------------------
3968 The rmr_wh_open function creates a direct link for sending, a
3969 wormhole, to another RMr based process. Sending messages
3970 through a wormhole requires that the connection be
3971 established overtly by the user application (via this
3972 function), and that the ID returned by rmr_wh_open be passed
3973 to the rmr_wh_send_msg function.
3975 *Target* is the *name* or *IP-address* combination of the
3976 processess that the wormhole should be connected to. *Vctx*
3977 is the RMr void context pointer that was returned by the
3980 When invoked, this function immediatly attempts to connect to
3981 the target process. If the connection cannot be established,
3982 an error is returned to the caller, and no direct messages
3983 can be sent to the target. Once a wormhole is connected, the
3984 underlying transport mechanism (e.g. NNG) will provide
3985 reconnects should the connection be lost, however the
3986 handling of messages sent when a connection is broken is
3987 undetermined as each underlying transport mechanism may
3988 handle buffering and retries differently.
3991 --------------------------------------------------------------------------------------------
3993 The rmr_wh_open function returns a type rmr_whid_t which must
3994 be passed to the rmr_wh_send_msg function when sending a
3995 message. The id may also be tested to determine success or
3996 failure of the connection by using the RMR_WH_CONNECTED macro
3997 and passing the ID as the parameter; a result of 1 indicates
3998 that the connection was esablished and that the ID is valid.
4001 --------------------------------------------------------------------------------------------
4003 The following error values are specifically set by this RMR
4004 function. In some cases the error message of a system call is
4005 propagated up, and thus this list might be incomplete.
4010 A parameter passed was not valid.
4014 The user applicarion does not have the ability to
4015 establish a wormhole to the indicated target (or maybe any
4020 The connection was refused.
4024 --------------------------------------------------------------------------------------------
4031 rmc = rmr_init( "43086", 4096, 0 ); // init context
4032 wh = rmr_wh_open( rmc, "localhost:6123" );
4033 if( !RMR_WH_CONNECTED( wh ) ) {
4034 f fprintf( stderr, "unable to connect wormhole: %s\\n",
4035 strerror( errno ) );
4041 --------------------------------------------------------------------------------------------
4043 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
4044 rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3),
4045 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
4046 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
4047 rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_close(3),
4048 rmr_wh_send_msg(3), rmr_wh_state(3)
4052 --------------------------------------------------------------------------------------------
4057 --------------------------------------------------------------------------------------------
4062 #include <rmr/rmr.h>
4063 rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t id, rmr_mbuf_t* msg );
4068 --------------------------------------------------------------------------------------------
4070 The rmr_wh_send_msg function accepts a message buffer from
4071 the user application and attempts to send it using the
4072 wormhole ID provided (id). Unlike *rmr_send_msg,* this
4073 function attempts to send the message directly to a process
4074 at the other end of a wormhole which was created with
4075 *rmr_wh-open().* When sending message via wormholes, the
4076 normal RMr routing based on message type is ignored, and the
4077 caller may leave the message type unspecified in the message
4078 buffer (unless it is needed by the receiving process).
4080 The message buffer (msg) used to send is the same format as
4081 used for regular RMr send and reply to sender operations,
4082 thus any buffer allocated by these means, or calls to
4083 *rmr_rcv_msg()* can be passed to this function.
4086 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4088 The send operations in RMr will retry *soft* send failures
4089 until one of three conditions occurs:
4095 The message is sent without error
4100 The underlying transport reports a * hard * failure
4105 The maximum number of retry loops has been attempted
4108 A retry loop consists of approximately 1000 send attemps **
4109 without** any intervening calls to * sleep() * or * usleep().
4110 * The number of retry loops defaults to 1, thus a maximum of
4111 1000 send attempts is performed before returning to the user
4112 application. This value can be set at any point after RMr
4113 initialisation using the * rmr_set_stimeout() * function
4114 allowing the user application to completely disable retires
4115 (set to 0), or to increase the number of retry loops.
4117 Transport Level Blocking
4118 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4120 The underlying transport mechanism used to send messages is
4121 configured in *non-blocking* mode. This means that if a
4122 message cannot be sent immediately the transport mechanism
4123 will **not** pause with the assumption that the inability to
4124 send will clear quickly (within a few milliseconds). This
4125 means that when the retry loop is completely disabled (set to
4126 0), that the failure to accept a message for sending by the
4127 underlying mechanisms (software or hardware) will be reported
4128 immediately to the user application.
4130 It should be noted that depending on the underlying transport
4131 mechanism being used, it is extremly possible that during
4132 normal operations that retry conditions are very likely to
4133 happen. These are completely out of RMr's control, and there
4134 is nothing that RMr can do to avoid or midigate these other
4135 than by allowing RMr to retry the send operation, and even
4136 then it is possible (e.g. during connection reattempts), that
4137 a single retry loop is not enough to guarentee a successful
4141 --------------------------------------------------------------------------------------------
4143 On success, a new message buffer, with an empty payload, is
4144 returned for the application to use for the next send. The
4145 state in this buffer will reflect the overall send operation
4146 state and should be RMR_OK.
4148 If the state in the returned buffer is anything other than
4149 RMR_OK, the user application may need to attempt a
4150 retransmission of the message, or take other action depending
4151 on the setting of errno as described below.
4153 In the event of extreme failure, a NULL pointer is returned.
4154 In this case the value of errno might be of some use, for
4155 documentation, but there will be little that the user
4156 application can do other than to move on.
4159 --------------------------------------------------------------------------------------------
4161 The following values may be passed back in the *state* field
4162 of the returned message buffer.
4168 The wormhole ID passed in was not associated with an open
4169 wormhole, or was out of range for a valid ID.
4173 No wormholes exist, further attempt to validate the ID are
4178 The message buffer pointer did not refer to a valid
4183 The header in the message buffer was not valid or
4187 The following values may be assigned to errno on failure.
4192 Parameter(s) passed to the function were not valid, or the
4193 underlying message processing environment was unable to
4194 interpret the message.
4199 The header information in the message buffer was invalid.
4204 No known endpoint for the message could be found.
4209 The underlying transport refused to accept the message
4210 because of a size value issue (message was not attempted
4216 The message referenced by the message buffer is corrupt
4217 (NULL pointer or bad internal length).
4222 Internal RMR error; information provided to the message
4223 transport environment was not valid.
4228 Sending was not supported by the underlying message
4234 The device is not in a state that can accept the message.
4239 The device is not able to accept a message for sending.
4240 The user application should attempt to resend.
4245 The operation was interrupted by delivery of a signal
4246 before the message was sent.
4251 The underlying message environment timed out during the
4257 The underlying message environment is in a shutdown state.
4261 --------------------------------------------------------------------------------------------
4263 The following is a simple example of how the a wormhole is
4264 created (rmr_wh_open) and then how rmr_wh_send_msg function
4265 is used to send messages. Some error checking is omitted for
4271 #include <rmr/rmr.h> .// system headers omitted for clarity
4273 rmr_whid_t whid = -1; // wormhole id for sending
4274 void* mrc; //msg router context
4276 rmr_mbuf_t* sbuf; // send buffer
4278 mrc = rmr_init( "43086", RMR_MAX_RCV_BYTES, RMRFL_NONE );
4280 fprintf( stderr, "[FAIL] unable to initialise RMr environment\\n" );
4283 while( ! rmr_ready( mrc ) ) { e i// wait for routing table info
4286 sbuf = rmr_alloc_msg( mrc, 2048 );
4289 whid = rmr_wh_open( mrc, "localhost:6123" ); // open fails if endpoint refuses conn
4290 w if( RMR_WH_CONNECTED( wh ) ) {
4291 snprintf( sbuf->payload, 1024, "periodic update from sender: %d", count++ );
4292 sbuf->len = strlen( sbuf->payload );
4293 sbuf = rmr_wh_send_msg( mrc, whid, sbuf );
4303 --------------------------------------------------------------------------------------------
4305 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
4306 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
4307 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
4308 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
4309 rmr_set_stimeout(3), rmr_wh_open(3), rmr_wh_close(3),
4314 --------------------------------------------------------------------------------------------
4319 --------------------------------------------------------------------------------------------
4324 #include <rmr/rmr.h>
4325 int rmr_wh_state( void* vctx, rmr_whid_t whid )
4330 --------------------------------------------------------------------------------------------
4332 The rmr_wh_state function will return the current state of
4333 the connection associated with the given wormhole (whid). The
4334 return value indicates whether the connection is open
4335 (RMR_OK), or closed (any other return value).
4337 When using some transport mechanisms (e.g. NNG), it may not
4338 be possible for RMR to know the actual state and the
4339 connection may always be reported as "open."
4342 --------------------------------------------------------------------------------------------
4344 The following values are potential return values.
4350 The wormhole ID is valid and the connection is "open."
4355 THe wormhole ID passed into the function was not valid.
4360 The wormhole is not open (not connected).
4365 The context passed to the function was nil or invalid.
4370 Wormholes have not been initialised (no wormhole open call
4376 --------------------------------------------------------------------------------------------
4378 rmr_wh_open(3), rmr_wh_send_msg(3), rmr_wh_close(3)