2 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
3 .. SPDX-License-Identifier: CC-BY-4.0
4 .. CAUTION: this document is generated from source in doc/src/rtd.
5 .. To make changes edit the source and recompile the document.
6 .. Do NOT make changes directly to .rst or .md files.
10 ============================================================================================
12 The RIC Message Router (RMR) is a library which applications
13 use to send and receive messages where the message routing,
14 endpoint selection, is based on the message type rather than
15 on traditional DNS names or IP addresses. Because the user
16 documentation for RMR is a collection of UNIX manpages
17 (included in the development package, and available via the
18 man command when installed), there is no separate "User's
19 Guide." To provide something for the document scrapers to
20 find, this is a collection of the RMR manual pages formatted
21 directly from their source which might be a bit ragged when
22 combined into a single markup document. Read the manual pages
28 --------------------------------------------------------------------------------------------
33 --------------------------------------------------------------------------------------------
39 rmr_mbuf_t* rmr_alloc_msg( void* ctx, int size );
44 --------------------------------------------------------------------------------------------
46 The rmr_alloc_msg function is used to allocate a buffer which
47 the user programme can write into and then send through the
48 RMR library. The buffer is allocated such that sending it
49 requires no additional copying out of the buffer. If the
50 value passed in size is 0, then the default size supplied on
51 the *rmr_init* call will be used. The *ctx* parameter is the
52 void context pointer that was returned by the *rmr_init*
55 The pointer to the message buffer returned is a structure
56 which has some user application visible fields; the structure
57 is described in rmr.h, and is illustrated below.
66 unsigned char* payload;
67 unsigned char* xaction;
78 Is the current buffer state. Following a call to
79 rmr_send_msg the state indicates whether the buffer was
80 successfully sent which determines exactly what the
81 payload points to. If the send failed, the payload
82 referenced by the buffer is the message that failed to
83 send (allowing the application to attempt a
84 retransmission). When the state is RMR_OK the buffer
85 represents an empty buffer that the application may fill
86 in in preparation to send.
91 When sending a message, the application is expected to set
92 this field to the appropriate message type value (as
93 determined by the user programme). Upon send this value
94 determines how the RMR library will route the message. For
95 a buffer which has been received, this field will contain
96 the message type that was set by the sending application.
101 The application using a buffer to send a message is
102 expected to set the length value to the actual number of
103 bytes that it placed into the message. This is likely less
104 than the total number of bytes that the message can carry.
105 For a message buffer that is passed to the application as
106 the result of a receive call, this will be the value that
107 the sending application supplied and should indicate the
108 number of bytes in the payload which are valid.
113 The payload is a pointer to the actual received data. The
114 user programme may read and write from/to the memory
115 referenced by the payload up until the point in time that
116 the buffer is used on a rmr_send, rmr_call or rmr_reply
117 function call. Once the buffer has been passed back to a
118 RMR library function the user programme should **NOT**
119 make use of the payload pointer.
124 The *xaction* field is a pointer to a fixed sized area in
125 the message into which the user may write a transaction
126 ID. The ID is optional with the exception of when the user
127 application uses the rmr_call function to send a message
128 and wait for the reply; the underlying RMR processing
129 expects that the matching reply message will also contain
130 the same data in the *xaction* field.
135 This value is the subscription ID. It, in combination with
136 the message type is used by rmr to determine the target
137 endpoint when sending a message. If the application to
138 application protocol does not warrant the use of a
139 subscription ID, the RMR constant RMR_VOID_SUBID should be
140 placed in this field. When an application is forwarding or
141 returning a buffer to the sender, it is the application's
142 responsibility to set/reset this value.
147 For C applications making use of RMR, the state of a
148 transport based failure will often be available via errno.
149 However, some wrapper environments may not have direct
150 access to the C-lib errno value. RMR send and receive
151 operations will place the current value of errno into this
152 field which should make it available to wrapper functions.
153 User applications are strongly cautioned against relying
154 on the value of errno as some transport mechanisms may not
155 set this value on all calls. This value should also be
156 ignored any time the message status is RMR_OK.
160 --------------------------------------------------------------------------------------------
162 The function returns a pointer to a rmr_mbuf structure, or
166 --------------------------------------------------------------------------------------------
172 Unable to allocate memory.
176 --------------------------------------------------------------------------------------------
178 rmr_tralloc_msg(3), rmr_call(3), rmr_free_msg(3),
179 rmr_init(3), rmr_init_trace(3), rmr_get_trace(3),
180 rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
181 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
182 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
183 rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)
187 --------------------------------------------------------------------------------------------
192 --------------------------------------------------------------------------------------------
198 int rmr_bytes2meid( rmr_mbuf_t* mbuf, unsigned char* src, int len )
203 --------------------------------------------------------------------------------------------
205 The rmr_bytes2meid function will copy up to *len* butes from
206 *src* to the managed entity ID (meid) field in the message.
207 The field is a fixed length, gated by the constant
208 RMR_MAX_MEID and if len is larger than this value, only
209 RMR_MAX_MEID bytes will actually be copied.
212 --------------------------------------------------------------------------------------------
214 On success, the actual number of bytes copied is returned, or
215 -1 to indicate a hard error. If the length is less than 0, or
216 not the same as length passed in, errno is set to one of the
217 errors described in the *Errors* section.
220 --------------------------------------------------------------------------------------------
222 If the returned length does not match the length passed in,
223 errno will be set to one of the following constants with the
224 meaning listed below.
230 The message, or an internal portion of the message, was
231 corrupted or the pointer was invalid.
236 The length passed in was larger than the maximum length of
237 the field; only a portion of the source bytes were copied.
241 --------------------------------------------------------------------------------------------
245 --------------------------------------------------------------------------------------------
247 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_call(3),
248 rmr_free_msg(3), rmr_get_rcvfd(3), rmr_get_meid(3),
249 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
250 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
251 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
252 rmr_ring_free(3), rmr_str2meid(3), rmr_str2xact(3),
253 rmr_wh_open(3), rmr_wh_send_msg(3)
257 --------------------------------------------------------------------------------------------
262 --------------------------------------------------------------------------------------------
268 void rmr_bytes2payload( rmr_mbuf_t* mbuf, unsigned char* src, int len )
273 --------------------------------------------------------------------------------------------
275 This is a convenience function as some wrapper languages
276 might not have the ability to directly copy into the payload
277 buffer. The bytes from *src* for the length given are copied
278 to the payload. It is the caller's responsibility to ensure
279 that the payload is large enough. Upon successfully copy, the
280 len field in the message buffer is updated to reflect the
281 number of bytes copied.
283 There is little error checking, and no error reporting.
286 --------------------------------------------------------------------------------------------
291 --------------------------------------------------------------------------------------------
295 --------------------------------------------------------------------------------------------
297 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2payload(3),
298 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
299 rmr_get_meid(3), rmr_payload_size(3), rmr_send_msg(3),
300 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
301 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
302 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
303 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
307 --------------------------------------------------------------------------------------------
312 --------------------------------------------------------------------------------------------
318 int rmr_bytes2xact( rmr_mbuf_t* mbuf, unsigned char* src, int len )
323 --------------------------------------------------------------------------------------------
325 The rmr_bytes2xact function will copy up to *len* butes from
326 *src* to the transaction ID (xaction) field in the message.
327 The field is a fixed length, gated by the constant
328 RMR_MAX_XID and if len is larger than this value, only
329 RMR_MAX_XID bytes will actually be copied.
333 --------------------------------------------------------------------------------------------
335 On success, the actual number of bytes copied is returned,
336 or -1 to indicate a hard error. If the length is less than
337 0, or not the same as length passed in, errno is set to
338 one of the errors described in the *Errors* section.
341 --------------------------------------------------------------------------------------------
343 If the returned length does not match the length passed
344 in, errno will be set to one of the following constants
345 with the meaning listed below.
350 The message, or an internal portion of the message, was
351 corrupted or the pointer was invalid.
356 The length passed in was larger than the maximum length of
357 the field; only a portion of the source bytes were copied.
361 --------------------------------------------------------------------------------------------
365 --------------------------------------------------------------------------------------------
367 rmr_alloc_msg(3), rmr_bytes2meid(3), rmr_call(3),
368 rmr_free_msg(3), rmr_get_meid(3), rmr_get_rcvfd(3),
369 rmr_get_xact(3), rmr_payload_size(3), rmr_send_msg(3),
370 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
371 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
372 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
373 rmr_wh_open(3), rmr_wh_send_msg(3)
377 --------------------------------------------------------------------------------------------
382 --------------------------------------------------------------------------------------------
388 extern rmr_mbuf_t* rmr_call( void* vctx, rmr_mbuf_t* msg );
393 --------------------------------------------------------------------------------------------
395 The rmr_call function sends the user application message to a
396 remote endpoint, and waits for a corresponding response
397 message before returning control to the user application. The
398 user application supplies a completed message buffer, as it
399 would for a rmr_send call, but unlike with the send, the
400 buffer returned will have the response from the application
401 that received the message.
403 Messages which are received while waiting for the response
404 are queued internally by RMR, and are returned to the user
405 application when rmr_rcv_msg is invoked. These messages are
406 returned in th order received, one per call to rmr_rcv_msg.
409 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
411 The rmr_call function implements a timeout failsafe to
412 prevent, in most cases, the function from blocking forever.
413 The timeout period is **not** based on time (calls to clock
414 are deemed too expensive for a low latency system level
415 library, but instead the period is based on the number of
416 received messages which are not the response. Using a
417 non-time mechanism for *timeout* prevents the async queue
418 from filling (which would lead to message drops) in an
419 environment where there is heavy message traffic.
421 When the threshold number of messages have been queued
422 without receiving a response message, control is returned to
423 the user application and a NULL pointer is returned to
424 indicate that no message was received to process. Currently
425 the threshold is fixed at 20 messages, though in future
426 versions of the library this might be extended to be a
427 parameter which the user application may set.
430 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
432 The send operations in RMr will retry *soft* send failures
433 until one of three conditions occurs:
439 The message is sent without error
444 The underlying transport reports a * hard * failure
449 The maximum number of retry loops has been attempted
452 A retry loop consists of approximately 1000 send attemps **
453 without** any intervening calls to * sleep() * or * usleep().
454 * The number of retry loops defaults to 1, thus a maximum of
455 1000 send attempts is performed before returning to the user
456 application. This value can be set at any point after RMr
457 initialisation using the * rmr_set_stimeout() * function
458 allowing the user application to completely disable retires
459 (set to 0), or to increase the number of retry loops.
461 Transport Level Blocking
462 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
464 The underlying transport mechanism used to send messages is
465 configured in *non-blocking* mode. This means that if a
466 message cannot be sent immediately the transport mechanism
467 will **not** pause with the assumption that the inability to
468 send will clear quickly (within a few milliseconds). This
469 means that when the retry loop is completely disabled (set to
470 0), that the failure to accept a message for sending by the
471 underlying mechanisms (software or hardware) will be reported
472 immediately to the user application.
474 It should be noted that depending on the underlying transport
475 mechanism being used, it is extremly possible that during
476 normal operations that retry conditions are very likely to
477 happen. These are completely out of RMr's control, and there
478 is nothing that RMr can do to avoid or midigate these other
479 than by allowing RMr to retry the send operation, and even
480 then it is possible (e.g. during connection reattempts), that
481 a single retry loop is not enough to guarentee a successful
485 --------------------------------------------------------------------------------------------
487 The rmr_call function returns a pointer to a message buffer
488 with the state set to reflect the overall state of call
489 processing (see Errors below). In some cases a NULL pointer
490 will be returned; when this is the case only *errno* will be
491 available to describe the reason for failure.
494 --------------------------------------------------------------------------------------------
496 These values are reflected in the state field of the returned
503 The call was successful and the message buffer references
504 the response message.
509 The call failed and the value of *errno,* as described
510 below, should be checked for the specific reason.
513 The global "variable" *errno* will be set to one of the
514 following values if the overall call processing was not
521 Too many messages were queued before receiving the
527 The queued message ring is full, messages were dropped
532 A parameter was not valid
537 The underlying message system wsa interrupted or the
538 device was busy; the message was **not** sent, and user
539 application should call this function with the message
544 --------------------------------------------------------------------------------------------
546 The following code bit shows one way of using the rmr_call
547 function, and illustrates how the transaction ID must be set.
552 int retries_left = 5; // max retries on dev not available
553 int retry_delay = 50000; // retry delay (usec)
554 static rmr_mbuf_t* mbuf = NULL; // response msg
555 msg_t* pm; // private message (payload)
556 m// get a send buffer and reference the payload
557 mbuf = rmr_alloc_msg( mr, RMR_MAX_RCV_BYTES );
558 pm = (msg_t*) mbuf->payload;
559 p// generate an xaction ID and fill in payload with data and msg type
560 snprintf( mbuf->xaction, RMR_MAX_XID, "%s", gen_xaction() );
561 snprintf( pm->req, sizeof( pm->req ), "{ \\"req\\": \\"num users\\"}" );
562 mbuf->mtype = MT_REQ;
564 msg = rmr_call( mr, msg );
565 if( ! msg ) { // probably a timeout and no msg received
566 return NULL; // let errno trickle up
568 if( mbuf->state != RMR_OK ) {
569 while( retries_left-- > 0 && // loop as long as eagain
571 (msg = rmr_call( mr, msg )) != NULL &&
572 mbuf->state != RMR_OK ) {
573 usleep( retry_delay );
576 if( mbuf == NULL || mbuf->state != RMR_OK ) {
577 rmr_free_msg( mbuf ); // safe if nil
581 // do something with mbuf
586 --------------------------------------------------------------------------------------------
588 rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3),
589 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
590 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
591 rmr_fib(3), rmr_has_str(3), rmr_set_stimeout(3),
592 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
596 --------------------------------------------------------------------------------------------
601 --------------------------------------------------------------------------------------------
607 void rmr_close( void* vctx )
612 --------------------------------------------------------------------------------------------
614 The rmr_close function closes the listen socket effectively
615 cutting the application off. The route table listener is also
616 stopped. Calls to rmr_rcv_msg() will fail with unpredictable
617 error codes, and calls to rmr_send_msg(), rmr_call(), and
618 rmr_rts_msg() will have unknown results.
622 --------------------------------------------------------------------------------------------
624 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
625 rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3),
626 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
627 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
628 rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_open(3),
633 --------------------------------------------------------------------------------------------
638 --------------------------------------------------------------------------------------------
644 void rmr_free_msg( rmr_mbuf_t* mbuf );
649 --------------------------------------------------------------------------------------------
651 The message buffer is returned to the pool, or the associated
652 memory is released depending on the needs of the underlying
653 messaging system. This allows the user application to release
654 a buffer that is not going to be used. It is safe to pass a
655 nil pointer to this function, and doing so does not result in
656 a change to the value of errrno.
658 After calling, the user application should **not** use any of
659 the pointers (transaction ID, or payload) which were
663 --------------------------------------------------------------------------------------------
665 rmr_alloc_msg(3), rmr_call(3), rmr_init(3),
666 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
667 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
668 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
673 --------------------------------------------------------------------------------------------
678 --------------------------------------------------------------------------------------------
684 char* rmr_get_meid( rmr_mbuf_t* mbuf, unsigned char* dest )
689 --------------------------------------------------------------------------------------------
691 The rmr_get_meid function will copy the managed entity ID
692 (meid) field from the message into the *dest* buffer provided
693 by the user. The buffer referenced by *dest* is assumed to be
694 at least RMR_MAX_MEID bytes in length. If *dest* is NULL,
695 then a buffer is allocated (the calling application is
696 expected to free when the buffer is no longer needed).
699 --------------------------------------------------------------------------------------------
701 On success, a pointer to the extracted string is returned. If
702 *dest* was supplied, then this is just a pointer to the
703 caller's buffer. If *dest* was NULL, this is a pointer to the
704 allocated buffer. If an error occurs, a nil pointer is
705 returned and errno is set as described below.
708 --------------------------------------------------------------------------------------------
710 If an error occurs, the value of the global variable errno
711 will be set to one of the following with the indicated
718 The message, or an internal portion of the message, was
719 corrupted or the pointer was invalid.
724 A nil pointer was passed for *dest,* however it was not
725 possible to allocate a buffer using malloc().
729 --------------------------------------------------------------------------------------------
731 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3),
732 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
733 rmr_get_xact(3), rmr_payload_size(3), rmr_send_msg(3),
734 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
735 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
736 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
737 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
741 --------------------------------------------------------------------------------------------
746 --------------------------------------------------------------------------------------------
752 void* rmr_get_rcvfd( void* ctx )
757 --------------------------------------------------------------------------------------------
759 The rmr_get_rcvfd function returns a file descriptor which
760 may be given to epoll_wait() by an application that wishes to
761 use event poll in a single thread rather than block on the
762 arrival of a message via calls to rmr_rcv_msg(). When
763 epoll_wait() indicates that this file descriptor is ready, a
764 call to rmr_rcv_msg() will not block as at least one message
767 The context (ctx) pointer passed in is the pointer returned
768 by the call to rmr_init().
770 **NOTE:** There is no support for epoll in Nanomsg, thus his
771 function is only supported when linking with the NNG version
772 of RMr and the file descriptor returned when using the
773 Nanomsg verfsion will always return an error.
776 --------------------------------------------------------------------------------------------
778 The rmr_get_rcvfd function returns a file descriptor greater
779 or equal to 0 on success and -1 on error. If this function is
780 called from a user application linked against the Nanomsg RMr
781 library, calls will always return -1 with errno set to
785 --------------------------------------------------------------------------------------------
787 The following error values are specifically set by this RMR
788 function. In some cases the error message of a system call is
789 propagated up, and thus this list might be incomplete.
794 The use of this function is invalid in this environment.
798 --------------------------------------------------------------------------------------------
800 The following short code bit illustrates the use of this
801 function. Error checking has been omitted for clarity.
808 #include <sys/epoll.h>
811 int rcv_fd; // pollable fd
812 void* mrc; //msg router context
813 struct epoll_event events[10]; // support 10 events to poll
814 struct epoll_event epe; // event definition for event to listen to
816 rmr_mbuf_t* msg = NULL;
820 mrc = rmr_init( "43086", RMR_MAX_RCV_BYTES, RMRFL_NONE );
821 rcv_fd = rmr_get_rcvfd( mrc );
823 rep_fd = epoll_create1( 0 ); _ B ,// initialise epoll environment
824 epe.events = EPOLLIN;
825 epe.data.fd = rcv_fd;
826 epoll_ctl( ep_fd, EPOLL_CTL_ADD, rcv_fd, &epe ); // add our info to the mix
829 nready = epoll_wait( ep_fd, events, 10, -1 ); // -1 == block forever (no timeout)
830 for( i = 0; i < nready && i < 10; i++ ) { // loop through to find what is ready
831 if( events[i].data.fd == rcv_fd ) { // RMr has something
832 msg = rmr_rcv_msg( mrc, msg );
834 // do something with msg
838 // check for other ready fds....
846 --------------------------------------------------------------------------------------------
848 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
849 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
850 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
851 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
856 --------------------------------------------------------------------------------------------
861 --------------------------------------------------------------------------------------------
867 unsigned char* rmr_get_src( rmr_mbuf_t* mbuf, unsigned char* dest )
872 --------------------------------------------------------------------------------------------
874 The rmr_get_src function will copy the *source* information
875 from the message to a buffer (dest) supplied by the user. In
876 an RMr message, the source is the sender's information that
877 is used for return to sender function calls, and is generally
878 the hostname and port in the form *name*. The source might be
879 an IP address port combination; the data is populated by the
880 sending process and the only requirement is that it be
881 capable of being used to start a TCP session with the sender.
883 The maximum size allowed by RMr is 64 bytes (including the
884 nil string terminator), so the user must ensure that the
885 destination buffer given is at least 64 bytes.
888 --------------------------------------------------------------------------------------------
890 On success, a pointer to the destination buffer is given as a
891 convenience to the user programme. On failure, a nil pointer
892 is returned and the value of errno is set.
895 --------------------------------------------------------------------------------------------
897 If an error occurs, the value of the global variable errno
898 will be set to one of the following with the indicated
905 The message, or an internal portion of the message, was
906 corrupted or the pointer was invalid.
910 --------------------------------------------------------------------------------------------
912 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3),
913 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
914 rmr_get_srcip(3), rmr_payload_size(3), rmr_send_msg(3),
915 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
916 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
917 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
918 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
922 --------------------------------------------------------------------------------------------
927 --------------------------------------------------------------------------------------------
933 unsigned char* rmr_get_srcip( rmr_mbuf_t* mbuf, unsigned char* dest )
938 --------------------------------------------------------------------------------------------
940 The rmr_get_srcip function will copy the *source IP address*
941 from the message to a buffer (dest) supplied by the user. In
942 an RMr message, the source IP address is the sender's
943 information that is used for return to sender function calls;
944 this function makes it available to the user application. The
945 address is maintained as IP:port where *IP* could be either
946 an IPv6 or IPv4 address depending on what was provided by the
949 The maximum size allowed by RMr is 64 bytes (including the
950 nil string terminator), so the user must ensure that the
951 destination buffer given is at least 64 bytes. The user
952 application should use the RMr constant RMR_MAX_SRC to ensure
953 that the buffer supplied is large enough, and to protect
954 against future RMr enhancements which might increase the
955 address buffer size requirement.
958 --------------------------------------------------------------------------------------------
960 On success, a pointer to the destination buffer is given as a
961 convenience to the user programme. On failure, a nil pointer
962 is returned and the value of errno is set.
965 --------------------------------------------------------------------------------------------
967 If an error occurs, the value of the global variable errno
968 will be set to one of the following with the indicated
975 The message, or an internal portion of the message, was
976 corrupted or the pointer was invalid.
980 --------------------------------------------------------------------------------------------
982 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3),
983 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
984 rmr_get_src(3), rmr_payload_size(3), rmr_send_msg(3),
985 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
986 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
987 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
988 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
992 --------------------------------------------------------------------------------------------
997 --------------------------------------------------------------------------------------------
1002 #include <rmr/rmr.h>
1003 int rmr_get_trace( rmr_mbuf_t* mbuf, unsigned char* dest, int size )
1008 --------------------------------------------------------------------------------------------
1010 The rmr_get_trace function will copy the trace information
1011 from the message into the user's allocated memory referenced
1012 by dest. The size parameter is assumed to be the maximum
1013 number of bytes which can be copied (size of the destination
1017 --------------------------------------------------------------------------------------------
1019 On success, the number of bytes actually copied is returned.
1020 If the return value is 0, no bytes copied, then the reason
1021 could be that the message pointer was nil, or the size
1025 --------------------------------------------------------------------------------------------
1027 rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3),
1028 rmr_bytes2meid(3), rmr_call(3), rmr_free_msg(3),
1029 rmr_get_rcvfd(3), rmr_get_trlen(3), rmr_init(3),
1030 rmr_init_trace(3), rmr_payload_size(3), rmr_send_msg(3),
1031 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1032 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
1033 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
1034 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3),
1035 rmr_set_trace(3), rmr_trace_ref(3)
1039 --------------------------------------------------------------------------------------------
1044 --------------------------------------------------------------------------------------------
1049 #include <rmr/rmr.h>
1050 int rmr_get_trlen( rmr_mbuf_t* msg );
1055 --------------------------------------------------------------------------------------------
1057 Given a message buffer, this function returns the amount of
1058 space (bytes) that have been allocated for trace data. If no
1059 trace data has been allocated, then 0 is returned.
1062 --------------------------------------------------------------------------------------------
1064 The number of bytes allocated for trace information in the
1068 --------------------------------------------------------------------------------------------
1074 Parameter(s) passed to the function were not valid.
1078 --------------------------------------------------------------------------------------------
1080 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
1081 rmr_get_trace(3), rmr_init(3), rmr_init_trace(3),
1082 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
1083 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
1084 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
1085 rmr_set_trace(3), rmr_tralloc_msg(3)
1089 --------------------------------------------------------------------------------------------
1094 --------------------------------------------------------------------------------------------
1099 #include <rmr/rmr.h>
1100 char* rmr_get_xact( rmr_mbuf_t* mbuf, unsigned char* dest )
1105 --------------------------------------------------------------------------------------------
1107 The rmr_get_xact function will copy the transaction field
1108 from the message into the *dest* buffer provided by the user.
1109 The buffer referenced by *dest* is assumed to be at least
1110 RMR_MAX_XID bytes in length. If *dest* is NULL, then a buffer
1111 is allocated (the calling application is expected to free
1112 when the buffer is no longer needed).
1115 --------------------------------------------------------------------------------------------
1117 On success, a pointer to the extracted string is returned. If
1118 *dest* was supplied, then this is just a pointer to the
1119 caller's buffer. If *dest* was NULL, this is a pointer to the
1120 allocated buffer. If an error occurs, a nil pointer is
1121 returned and errno is set as described below.
1124 --------------------------------------------------------------------------------------------
1126 If an error occurs, the value of the global variable errno
1127 will be set to one of the following with the indicated
1134 The message, or an internal portion of the message, was
1135 corrupted or the pointer was invalid.
1140 A nil pointer was passed for *dest,* however it was not
1141 possible to allocate a buffer using malloc().
1145 --------------------------------------------------------------------------------------------
1147 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3),
1148 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
1149 rmr_get_meid(3), rmr_payload_size(3), rmr_send_msg(3),
1150 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1151 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
1152 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
1153 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
1157 --------------------------------------------------------------------------------------------
1162 --------------------------------------------------------------------------------------------
1167 #include <rmr/rmr.h>
1168 void* rmr_init( char* proto_port, int max_msg_size, int flags );
1173 --------------------------------------------------------------------------------------------
1175 The rmr_init function prepares the environment for sending
1176 and receiving messages. It does so by establishing a worker
1177 thread (pthread) which subscribes to a route table generator
1178 which provides the necessary routing information for the RMR
1179 library to send messages.
1181 *Port* is used to listen for connection requests from other
1182 RMR based applications. The *max_msg_size* parameter is used
1183 to allocate receive buffers and is the maximum message size
1184 which the application expects to receive. This value is the
1185 sum of **both** the maximum payload size **and** the maximum
1186 trace data size. This value is also used as the default
1187 message size when allocating message buffers. Messages
1188 arriving which are longer than the given maximum will be
1189 dropped without notification to the application. A warning is
1190 written to standard error for the first message which is too
1191 large on each connection.
1193 *Flags* allows for selection of some RMr options at the time
1194 of initialisation. These are set by ORing RMRFL constants
1195 from the RMr header file. Currently the following flags are
1207 The route table collector thread is not to be started.
1208 This should only be used by the route table generator
1209 application if it is based on RMr.
1214 Enable multi-threaded call support.
1219 Some underlying transport providers (e.g. SI95) enable
1220 locking to be turned off if the user application is single
1221 threaded, or otherwise can guarantee that RMR functions
1222 will not be invoked concurrently from different threads.
1223 Turning off locking can help make message receipt more
1224 efficient. If this flag is set when the underlying
1225 transport does not support disabling locks, it will be
1229 Multi-threaded Calling
1230 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1232 The support for an application to issue a *blocking call* by
1233 the rmr_call() function was limited such that only user
1234 applications which were operating in a single thread could
1235 safely use the function. Further, timeouts were message count
1236 based and not time unit based. Multi-threaded call support
1237 adds the ability for a user application with multiple threads
1238 to invoke a blocking call function with the guarantee that
1239 the correct response message is delivered to the thread. The
1240 additional support is implemented with the *rmr_mt_call()*
1241 and *rmr_mt_rcv()* function calls.
1243 Multi-threaded call support requires the user application to
1244 specifically enable it when RMr is initialised. This is
1245 necessary because a second, dedicated, receiver thread must
1246 be started, and requires all messages to be examined and
1247 queued by this thread. The additional overhead is minimal,
1248 queuing information is all in the RMr message header, but as
1249 an additional process is necessary the user application must
1250 "opt in" to this approach.
1254 --------------------------------------------------------------------------------------------
1256 As a part of the initialisation process rmr_init will look
1257 into the available environment variables to influence it's
1258 setup. The following variables will be used when found.
1264 Allows the async connection mode to be turned off (by
1265 setting the value to 0. When set to 1, or missing from the
1266 environment, RMR will invoke the connection interface in
1267 the transport mechanism using the non-blocking (async)
1268 mode. This will likely result in many "soft failures"
1269 (retry) until the connection is established, but allows
1270 the application to continue unimpeeded should the
1271 connection be slow to set up.
1276 This provides the interface that RMR will bind listen
1277 ports to allowing for a single interface to be used rather
1278 than listening across all interfaces. This should be the
1279 IP address assigned to the interface that RMR should
1280 listen on, and if not defined RMR will listen on all
1286 This variable defines the port that RMR should open for
1287 communications with Route Manager, and other RMR control
1288 applications. If not defined, the port 4561 is assumed.
1290 Previously, the RMR_RTG_SVC (route table generator service
1291 port) was used to define this port. However, a future
1292 version of Route Manager will require RMR to connect and
1293 request tables, thus that variable is now used to supply
1294 the Route Manager well known address and port.
1296 To maintain backwards compatablibility with the older
1297 Route Manager versions, the presence of this variable in
1298 the environment will shift RMR's behaviour with respect to
1299 the default value used when RMR_RTG_SVC is **not**
1302 When RMR_CTL_PORT is **defined:** RMR assumes that Route
1303 Manager requires RMR to connect and request table updates
1304 is made, and the default well known address for Route
1305 manager is used (routemgr:4561).
1307 When RMR_CTL_PORT is **undefined:** RMR assumes that Route
1308 Manager will connect and push table updates, thus the
1309 default listen port (4561) is used.
1311 To avoid any possible misinterpretation and/or incorrect
1312 assumptions on the part of RMR, it is recommended that
1313 both the RMR_CTL_PORT and RMR_RTG_SVC be defined. In the
1314 case where both variables are defined, RMR will behave
1315 exactly as is communicated with the variable's values.
1320 The value of this variable depends on the Route Manager in
1323 When the Route Manager is expecting to connect to an xAPP
1324 and push route tables, this variable must indicate the
1325 port which RMR should use to listen for these connections.
1327 When the Route Manager is expecting RMR to connect and
1328 request a table update during initialisation, the variable
1329 should be the host of the Route Manager process.
1331 The RMR_CTL_PORT variable (added with the support of
1332 sending table update requests to Route manager), controls
1333 the behaviour if this variable is not set. See the
1334 description of that variable for details.
1339 By default RMR writes messages to standard error
1340 (incorrectly referred to as log messages) in human
1341 readable format. If this environment variable is set to 0,
1342 the format of standard error messages might be written in
1343 some format not easily read by humans. If missing, a value
1349 This is a numeric value which corresponds to the verbosity
1350 level used to limit messages written to standard error.
1351 The lower the number the less chatty RMR functions are
1352 during execution. The following is the current
1353 relationship between the value set on this variable and
1354 the messages written:
1359 Off; no messages of any sort are written.
1364 Only critical messages are written (default if this
1365 variable does not exist)
1370 Errors and all messages written with a lower value.
1375 Warnings and all messages written with a lower value.
1380 Informational and all messages written with a lower
1386 Debugging mode -- all messages written, however this
1387 requires RMR to have been compiled with debugging
1394 **Deprecated.** Should be set to 1 if the route table
1395 generator is sending "plain" messages (not using RMR to
1396 send messages, 0 if the rtg is using RMR to send. The
1397 default is 1 as we don't expect the rtg to use RMR.
1399 This variable is only recognised when using the NNG
1400 transport library as it is not possible to support NNG
1401 "raw" communications with other transport libraries. It is
1402 also necessary to match the value of this variable with
1403 the capabilities of the Route Manager; at some point in
1404 the future RMR will assume that all Route Manager messages
1405 will arrive via an RMR connection and will ignore this
1410 This is used to supply a static route table which can be
1411 used for debugging, testing, or if no route table
1412 generator process is being used to supply the route table.
1413 If not defined, no static table is used and RMR will not
1414 report *ready* until a table is received. The static route
1415 table may contain both the route table (between newrt
1416 start and end records), and the MEID map (between meid_map
1417 start and end records)
1421 This is either the name or IP address which is placed into
1422 outbound messages as the message source. This will used
1423 when an RMR based application uses the rmr_rts_msg()
1424 function to return a response to the sender. If not
1425 supplied RMR will use the hostname which in some container
1426 environments might not be routable.
1428 The value of this variable is also used for Route Manager
1429 messages which are sent via an RMR connection.
1433 This supplies the name of a verbosity control file. The
1434 core RMR functions do not produce messages unless there is
1435 a critical failure. However, the route table collection
1436 thread, not a part of the main message processing
1437 component, can write additional messages to standard
1438 error. If this variable is set, RMR will extract the
1439 verbosity level for these messages (0 is silent) from the
1440 first line of the file. Changes to the file are detected
1441 and thus the level can be changed dynamically, however RMR
1442 will only suss out this variable during initialisation, so
1443 it is impossible to enable verbosity after startup.
1447 If set to 1, RMR will write some warnings which are
1448 non-performance impacting. If the variable is not defined,
1449 or set to 0, RMR will not write these additional warnings.
1453 --------------------------------------------------------------------------------------------
1455 The rmr_init function returns a void pointer (a contex if you
1456 will) that is passed as the first parameter to nearly all
1457 other RMR functions. If rmr_init is unable to properly
1458 initialise the environment, NULL is returned and errno is set
1459 to an appropriate value.
1462 --------------------------------------------------------------------------------------------
1464 The following error values are specifically set by this RMR
1465 function. In some cases the error message of a system call is
1466 propagated up, and thus this list might be incomplete.
1471 Unable to allocate memory.
1475 --------------------------------------------------------------------------------------------
1481 rmr_mbuf* buf = NULL;
1482 uh = rmr_init( "43086", 4096, 0 );
1483 buf = rmr_rcv_msg( uh, buf );
1488 --------------------------------------------------------------------------------------------
1490 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
1491 rmr_get_rcvfd(3), rmr_mt_call(3), rmr_mt_rcv(3),
1492 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
1493 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
1494 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
1499 --------------------------------------------------------------------------------------------
1504 --------------------------------------------------------------------------------------------
1509 #include <rmr/rmr.h>
1510 void* rmr_init_trace( void* ctx )
1515 --------------------------------------------------------------------------------------------
1517 The rmr_init_trace function establishes the default trace
1518 space placed in each message buffer allocated with
1519 rmr_alloc_msg(). If this function is never called, then no
1520 trace space is allocated by default into any message buffer.
1522 Trace space allows the user application to pass some trace
1523 token, or other data with the message, but outside of the
1524 payload. Trace data may be added to any message with
1525 rmr_set_trace(), and may be extracted from a message with
1526 rmr_get_trace(). The number of bytes that a message contains
1527 for/with trace data can be determined by invoking
1530 This function may be safely called at any time during the
1531 life of the user programme to (re)set the default trace space
1532 reserved. If the user programme needs to allocate a message
1533 with trace space of a different size than is allocated by
1534 default, without fear of extra overhead of reallocating a
1535 message later, the rmr_tralloc_msg() function can be used.
1538 --------------------------------------------------------------------------------------------
1540 A value of 1 is returned on success, and 0 on failure. A
1541 failure indicates that the RMr context (a void pointer passed
1542 to this function was not valid.
1545 --------------------------------------------------------------------------------------------
1547 rmr_alloc_msg(3), rmr_tr_alloc_msg(3), rmr_call(3),
1548 rmr_free_msg(3), rmr_get_rcvfd(3), rmr_get_trace(3),
1549 rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
1550 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1551 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
1552 rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)
1556 --------------------------------------------------------------------------------------------
1561 --------------------------------------------------------------------------------------------
1566 #include <rmr/rmr.h>
1567 extern rmr_mbuf_t* rmr_mt_call( void* vctx, rmr_mbuf_t* msg, int id, int timeout );
1572 --------------------------------------------------------------------------------------------
1574 The rmr_mt_call function sends the user application message
1575 to a remote endpoint, and waits for a corresponding response
1576 message before returning control to the user application. The
1577 user application supplies a completed message buffer, as it
1578 would for a rmr_send_msg call, but unlike with a send, the
1579 buffer returned will have the response from the application
1580 that received the message. The thread invoking the
1581 *rmr_mt_call()* will block until a message arrives or until
1582 *timeout* milliseconds has passed; which ever comes first.
1583 Using a timeout value of zero (0) will cause the thread to
1584 block without a timeout.
1586 The *id* supplied as the third parameter is an integer in the
1587 range of 2 through 255 inclusive. This is a caller defined
1588 "thread number" and is used to match the response message
1589 with the correct user application thread. If the ID value is
1590 not in the proper range, the attempt to make the call will
1593 Messages which are received while waiting for the response
1594 are queued on a *normal* receive queue and will be delivered
1595 to the user application with the next invocation of
1596 *rmr_mt_rcv()* or *rmr_rvv_msg().* by RMR, and are returned
1597 to the user application when rmr_rcv_msg is invoked. These
1598 messages are returned in th order received, one per call to
1601 NOTE: Currently the multi-threaded functions are supported
1602 only when the NNG transport mechanism is being used. It will
1603 not be possible to link a programme using the Nanomsg version
1604 of the library when references to this function are present.
1607 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1609 The user application is responsible for setting the value of
1610 the transaction ID field before invoking *rmr_mt_call.* The
1611 transaction ID is a RMR_MAX_XID byte field that is used to
1612 match the response message when it arrives. RMr will compare
1613 **all** of the bytes in the field, so the caller must ensure
1614 that they are set correctly to avoid missing the response
1615 message. (The application which returns the response message
1616 is also expected to ensure that the return buffer has the
1617 matching transaction ID. This can be done transparently if
1618 the application uses the *rmr_rts_msg()* function and does
1619 not adjust the transaction ID.
1622 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1624 The send operations in RMr will retry *soft* send failures
1625 until one of three conditions occurs:
1631 The message is sent without error
1636 The underlying transport reports a * hard * failure
1641 The maximum number of retry loops has been attempted
1644 A retry loop consists of approximately 1000 send attemps **
1645 without** any intervening calls to * sleep() * or * usleep().
1646 * The number of retry loops defaults to 1, thus a maximum of
1647 1000 send attempts is performed before returning to the user
1648 application. This value can be set at any point after RMr
1649 initialisation using the * rmr_set_stimeout() * function
1650 allowing the user application to completely disable retires
1651 (set to 0), or to increase the number of retry loops.
1653 Transport Level Blocking
1654 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1656 The underlying transport mechanism used to send messages is
1657 configured in *non-blocking* mode. This means that if a
1658 message cannot be sent immediately the transport mechanism
1659 will **not** pause with the assumption that the inability to
1660 send will clear quickly (within a few milliseconds). This
1661 means that when the retry loop is completely disabled (set to
1662 0), that the failure to accept a message for sending by the
1663 underlying mechanisms (software or hardware) will be reported
1664 immediately to the user application.
1666 It should be noted that depending on the underlying transport
1667 mechanism being used, it is extremly possible that during
1668 normal operations that retry conditions are very likely to
1669 happen. These are completely out of RMr's control, and there
1670 is nothing that RMr can do to avoid or midigate these other
1671 than by allowing RMr to retry the send operation, and even
1672 then it is possible (e.g. during connection reattempts), that
1673 a single retry loop is not enough to guarentee a successful
1677 --------------------------------------------------------------------------------------------
1679 The rmr_mt_call function returns a pointer to a message
1680 buffer with the state set to reflect the overall state of
1681 call processing. If the state is RMR_OK then the buffer
1682 contains the response message; otherwise the state indicates
1683 the error encountered while attempting to send the message.
1685 If no response message is received when the timeout period
1686 has expired, a nil pointer will be returned (NULL).
1689 --------------------------------------------------------------------------------------------
1691 These values are reflected in the state field of the returned
1698 The call was successful and the message buffer references
1699 the response message.
1704 An argument passed to the function was invalid.
1709 The call failed and the value of *errno,* as described
1710 below, should be checked for the specific reason.
1715 An endpoint associated with the message type could not be
1716 found in the route table.
1721 The underlying transport mechanism was unable to accept
1722 the message for sending. The user application can retry
1723 the call operation if appropriate to do so.
1726 The global "variable" *errno* will be set to one of the
1727 following values if the overall call processing was not
1734 Too many messages were queued before receiving the
1740 The queued message ring is full, messages were dropped
1745 A parameter was not valid
1750 The underlying message system wsa interrupted or the
1751 device was busy; the message was **not** sent, and user
1752 application should call this function with the message
1757 --------------------------------------------------------------------------------------------
1759 The following code bit shows one way of using the rmr_mt_call
1760 function, and illustrates how the transaction ID must be set.
1765 int retries_left = 5; // max retries on dev not available
1766 static rmr_mbuf_t* mbuf = NULL; // response msg
1767 msg_t* pm; // private message (payload)
1768 m// get a send buffer and reference the payload
1769 mbuf = rmr_alloc_msg( mr, RMR_MAX_RCV_BYTES );
1770 pm = (msg_t*) mbuf->payload;
1771 p// generate an xaction ID and fill in payload with data and msg type
1772 rmr_bytes2xact( mbuf, xid, RMR_MAX_XID );
1773 snprintf( pm->req, sizeof( pm->req ), "{ \\"req\\": \\"num users\\"}" );
1774 mbuf->mtype = MT_USR_RESP;
1776 msg = rmr_mt_call( mr, msg, my_id, 100 ); e :// wait up to 100ms
1777 if( ! msg ) { // probably a timeout and no msg received
1778 return NULL; // let errno trickle up
1780 if( mbuf->state != RMR_OK ) {
1781 while( retries_left-- > 0 && // loop as long as eagain
1782 mbuf->state == RMR_ERR_RETRY &&
1783 (msg = rmr_mt_call( mr, msg )) != NULL &&
1784 mbuf->state != RMR_OK ) {
1785 usleep( retry_delay );
1788 if( mbuf == NULL || mbuf->state != RMR_OK ) {
1789 rmr_free_msg( mbuf ); // safe if nil
1793 // do something with mbuf
1798 --------------------------------------------------------------------------------------------
1800 rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3),
1801 rmr_mt_rcv(3), rmr_payload_size(3), rmr_send_msg(3),
1802 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1803 rmr_ready(3), rmr_fib(3), rmr_has_str(3),
1804 rmr_set_stimeout(3), rmr_tokenise(3), rmr_mk_ring(3),
1809 --------------------------------------------------------------------------------------------
1814 --------------------------------------------------------------------------------------------
1819 #include <rmr/rmr.h>
1820 rmr_mbuf_t* rmr_mt_rcv( void* vctx, rmr_mbuf_t* old_msg, int timeout );
1825 --------------------------------------------------------------------------------------------
1827 The rmr_mt_rcv function blocks until a message is received,
1828 or the timeout period (milliseconds) has passed. The result
1829 is an RMr message buffer which references a received message.
1830 In the case of a timeout the state will be reflected in an
1831 "empty buffer" (if old_msg was not nil, or simply with the
1832 return of a nil pointer. If a timeout value of zero (0) is
1833 given, then the function will block until the next message
1836 The *vctx* pointer is the pointer returned by the rmr_init
1837 function. *Old_msg* is a pointer to a previously used message
1838 buffer or NULL. The ability to reuse message buffers helps to
1839 avoid alloc/free cycles in the user application. When no
1840 buffer is available to supply, the receive function will
1843 The *old_msg* parameter allows the user to pass a previously
1844 generated RMr message back to RMr for reuse. Optionally, the
1845 user application may pass a nil pointer if no reusable
1846 message is available. When a timeout occurs, and old_msg was
1847 not nil, the state will be returned by returning a pointer to
1848 the old message with the state set.
1850 It is possible to use the *rmr_rcv_msg()* function instead of
1851 this function. Doing so might be advantagous if the user
1852 programme does not always start the multi-threaded mode and
1853 the use of *rmr_rcv_msg()* would make the flow of the code
1854 more simple. The advantags of using this function are the
1855 ability to set a timeout without using epoll, and a small
1856 performance gain (if multi-threaded mode is enabled, and the
1857 *rmr_rcv_msg()* function is used, it simply invokes this
1858 function without a timeout value, thus there is the small
1859 cost of a second call that results). Similarly, the
1860 *rmr_torcv_msg()* call can be used when in multi-threaded
1861 mode with the same "pass through" overhead to using this
1864 NOTE: Currently the multi-threaded functions are supported
1865 only when the NNG transport mechanism is being used. It will
1866 not be possible to link a programme using the nanomsg version
1867 of the library when references to this function are present.
1870 --------------------------------------------------------------------------------------------
1872 When a message is received before the timeout period expires,
1873 a pointer to the RMr message buffer which describes the
1874 message is returned. This will, with a high probability, be a
1875 different message buffer than *old_msg;* the user application
1876 should not continue to use *old_msg* after it is passed to
1879 In the event of a timeout the return value will be the old
1880 msg with the state set, or a nil pointer if no old message
1884 --------------------------------------------------------------------------------------------
1886 The *state* field in the message buffer will be set to one of
1887 the following values:
1893 The message was received without error.
1898 A parameter passed to the function was not valid (e.g. a
1899 nil pointer). indicate either RMR_OK or RMR_ERR_EMPTY if
1900 an empty message was received.
1905 The message received had no associated data. The length of
1906 the message will be 0.
1911 The multi-threaded option was not enabled when RMr was
1912 initialised. See the man page for *rmr_init()* for
1918 A hard error occurred preventing the receive from
1921 When a nil pointer is returned, or any other state value was
1922 set in the message buffer, errno will be set to one of the
1929 Parameter(s) passed to the function were not valid.
1934 The underlying message transport is unable to process the
1940 The underlying message transport is unable to process the
1946 The underlying message transport is unable to process the
1952 The underlying message transport is unable to process the
1958 The underlying message transport is unable to process the
1964 The underlying message transport is unable to process the
1970 The underlying message transport is unable to process the
1975 --------------------------------------------------------------------------------------------
1981 rmr_mbuf_t* mbuf = NULL; // received msg
1982 msg = rmr_mt_recv( mr, mbuf, 100 ); // wait up to 100ms
1984 switch( msg->state ) {
1986 printf( "got a good message\\n" );
1989 printf( "received timed out\\n" );
1992 printf( "receive error: %d\\n", mbuf->state );
1996 printf( "receive timeout (nil)\\n" );
2002 --------------------------------------------------------------------------------------------
2004 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
2005 rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3),
2006 rmr_mt_call(3), rmr_payload_size(3), rmr_send_msg(3),
2007 rmr_torcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
2008 rmr_ready(3), rmr_ring_free(3), rmr_torcv_msg(3)
2012 --------------------------------------------------------------------------------------------
2017 --------------------------------------------------------------------------------------------
2022 #include <rmr/rmr.h>
2023 int rmr_payload_size( rmr_mbuf_t* msg );
2028 --------------------------------------------------------------------------------------------
2030 Given a message buffer, this function returns the amount of
2031 space (bytes) available for the user application to consume
2032 in the message payload. This is different than the message
2033 length available as a field in the message buffer.
2036 --------------------------------------------------------------------------------------------
2038 The number of bytes available in the payload.
2041 --------------------------------------------------------------------------------------------
2047 Parameter(s) passed to the function were not valid.
2051 --------------------------------------------------------------------------------------------
2053 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2054 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
2055 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
2056 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
2060 --------------------------------------------------------------------------------------------
2065 --------------------------------------------------------------------------------------------
2070 #include <rmr/rmr.h>
2071 rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg );
2076 --------------------------------------------------------------------------------------------
2078 The rmr_rcv_msg function blocks until a message is received,
2079 returning the message to the caller via a pointer to a
2080 rmr_mbuf_t structure type. If messages were queued while
2081 waiting for the response to a previous invocation of
2082 rmr_call, the oldest message is removed from the queue and
2083 returned without delay.
2085 The *vctx* pointer is the pointer returned by the rmr_init
2086 function. *Old_msg* is a pointer to a previously used message
2087 buffer or NULL. The ability to reuse message buffers helps to
2088 avoid alloc/free cycles in the user application. When no
2089 buffer is available to supply, the receive function will
2093 --------------------------------------------------------------------------------------------
2095 The function returns a pointer to the rmr_mbuf_t structure
2096 which references the message information (state, length,
2097 payload), or a NULL pointer in the case of an extreme error.
2100 --------------------------------------------------------------------------------------------
2102 The *state* field in the message buffer will indicate either
2103 RMR_OK when the message receive process was successful and
2104 the message can be used by the caller. Depending on the
2105 underlying transport mechanism, one of the following RMR
2106 error stats may be returned:
2112 The message received had no payload, or was completely
2118 For some transport mechanisms, or if reading the receive
2119 queue from multiple threads, it is possible for one thread
2120 to find no data waiting when it queries the queue. When
2121 this state is reported, the message buffer does not
2122 contain message data and the user application should
2123 reinvoke the receive function.
2126 When an RMR error state is reported, the underlying errno
2127 value might provide more information. The following is a list
2128 of possible values that might accompany the states listed
2131 RMR_ERR_EMPTY if an empty message was received. If a nil
2132 pointer is returned, or any other state value was set in the
2133 message buffer, errno will be set to one of the following:
2139 Parameter(s) passed to the function were not valid.
2144 The underlying message transport is unable to process the
2150 The underlying message transport is unable to process the
2156 The underlying message transport is unable to process the
2162 The underlying message transport is unable to process the
2168 The underlying message transport is unable to process the
2174 The underlying message transport is unable to process the
2180 The underlying message transport is unable to process the
2185 --------------------------------------------------------------------------------------------
2189 --------------------------------------------------------------------------------------------
2191 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
2192 rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3),
2193 rmr_payload_size(3), rmr_send_msg(3), rmr_torcv_msg(3),
2194 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
2195 rmr_ring_free(3), rmr_torcv_msg(3)
2199 --------------------------------------------------------------------------------------------
2204 --------------------------------------------------------------------------------------------
2209 #include <rmr/rmr.h>
2210 int rmr_ready( void* vctx );
2215 --------------------------------------------------------------------------------------------
2217 The rmr_ready function checks to see if a routing table has
2218 been successfully received and installed. The return value
2219 indicates the state of readiness.
2222 --------------------------------------------------------------------------------------------
2224 A return value of 1 (true) indicates that the routing table
2225 is in place and attempts to send messages can be made. When 0
2226 is returned (false) the routing table has not been received
2227 and thus attempts to send messages will fail with *no
2231 --------------------------------------------------------------------------------------------
2233 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2234 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
2235 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_fib(3),
2236 rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
2241 --------------------------------------------------------------------------------------------
2246 --------------------------------------------------------------------------------------------
2251 #include <rmr/rmr.h>
2252 extern rmr_mbuf_t* rmr_realloc_payload( rmr_mbuf_t* msg, int new_len, int copy, int clone );
2257 --------------------------------------------------------------------------------------------
2259 The rmr_realloc_payload function will return a pointer to an
2260 RMR message buffer struct (rmr_mbuf_t) which has a payload
2261 large enough to accomodate *new_len* bytes. If necessary, the
2262 underlying payload is reallocated, and the bytes from the
2263 original payload are copied if the *copy* parameter is true
2264 (1). If the message passed in has a payload large enough,
2265 there is no additional memory allocation and copying.
2267 Cloning The Message Buffer
2268 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2270 This function can also be used to generate a separate copy of
2271 the original message, with the desired payload size, without
2272 destroying the original message buffer or the original
2273 payload. A standalone copy is made only when the *clone*
2274 parameter is true (1). When cloning, the payload is copied to
2275 the cloned message **only** if the *copy* parameter is true.
2277 Message Buffer Metadata
2278 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2280 The metadata in the original message buffer (message type,
2281 subscription ID, and payload length) will be preserved if the
2282 *copy* parameter is true. When this parameter is not true
2283 (0), then these values are set to the uninitialised value
2284 (-1) for type and ID, and the length is set to 0.
2287 --------------------------------------------------------------------------------------------
2289 The rmr_realloc_payload function returns a pointer to the
2290 message buffer with the payload which is large enough to hold
2291 *new_len* bytes. If the *clone* option is true, this will be
2292 a pointer to the newly cloned message buffer; the original
2293 message buffer pointer may still be used to referenced that
2294 message. It is the calling application's responsibility to
2295 free the memory associateed with both messages using the
2296 rmr_free_msg() function.
2298 When the *clone* option is not used, it is still good
2299 practice by the calling application to capture and use this
2300 reference as it is possible that the message buffer, and not
2301 just the payload buffer, was reallocated. In the event of an
2302 error, a nil pointer will be returned and the value of
2303 *errno* will be set to reflect the problem.
2306 --------------------------------------------------------------------------------------------
2308 These value of *errno* will reflect the error condition if a
2309 nil pointer is returned:
2315 Memory allocation of the new payload failed.
2320 The pointer passed in was nil, or refrenced an invalid
2321 message, or the required length was not valid.
2325 --------------------------------------------------------------------------------------------
2327 The following code bit illustrates how this function can be
2328 used to reallocate a buffer for a return to sender
2329 acknowledgement message which is larger than the message
2335 if( rmr_payload_size( msg ) < ack_sz ) { // received message too small for ack
2336 msg = rmr_realloc_payload( msg, ack_sz, 0, 0 ); // reallocate the message with a payload big enough
2338 fprintf( stderr, "[ERR] realloc returned a nil pointer: %s\\n", strerror( errno ) );
2340 } e// populate and send ack message
2347 --------------------------------------------------------------------------------------------
2349 rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3),
2350 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
2351 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
2352 rmr_fib(3), rmr_has_str(3), rmr_set_stimeout(3),
2353 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
2357 --------------------------------------------------------------------------------------------
2362 --------------------------------------------------------------------------------------------
2367 #include <rmr/rmr.h>
2368 rmr_mbuf_t* rmr_rts_msg( void* vctx, rmr_mbuf_t* msg );
2373 --------------------------------------------------------------------------------------------
2375 The rmr_rts_msg function sends a message returning it to the
2376 endpoint which sent the message rather than selecting an
2377 endpoint based on the message type and routing table. Other
2378 than this small difference, the behaviour is exactly the same
2382 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2384 The send operations in RMr will retry *soft* send failures
2385 until one of three conditions occurs:
2391 The message is sent without error
2396 The underlying transport reports a * hard * failure
2401 The maximum number of retry loops has been attempted
2404 A retry loop consists of approximately 1000 send attemps **
2405 without** any intervening calls to * sleep() * or * usleep().
2406 * The number of retry loops defaults to 1, thus a maximum of
2407 1000 send attempts is performed before returning to the user
2408 application. This value can be set at any point after RMr
2409 initialisation using the * rmr_set_stimeout() * function
2410 allowing the user application to completely disable retires
2411 (set to 0), or to increase the number of retry loops.
2413 Transport Level Blocking
2414 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2416 The underlying transport mechanism used to send messages is
2417 configured in *non-blocking* mode. This means that if a
2418 message cannot be sent immediately the transport mechanism
2419 will **not** pause with the assumption that the inability to
2420 send will clear quickly (within a few milliseconds). This
2421 means that when the retry loop is completely disabled (set to
2422 0), that the failure to accept a message for sending by the
2423 underlying mechanisms (software or hardware) will be reported
2424 immediately to the user application.
2426 It should be noted that depending on the underlying transport
2427 mechanism being used, it is extremly possible that during
2428 normal operations that retry conditions are very likely to
2429 happen. These are completely out of RMr's control, and there
2430 is nothing that RMr can do to avoid or midigate these other
2431 than by allowing RMr to retry the send operation, and even
2432 then it is possible (e.g. during connection reattempts), that
2433 a single retry loop is not enough to guarentee a successful
2437 --------------------------------------------------------------------------------------------
2439 When crafting a response based on a received message, the
2440 user application must take care not to write more bytes to
2441 the message payload than the allocated message has. In the
2442 case of a received message, it is possible that the response
2443 needs to be larger than the payload associated with the
2444 inbound message. In order to use the return to sender
2445 function, the source infomration in the orignal message must
2446 be present in the response; information which cannot be added
2447 to a message buffer allocated through the standard RMR
2448 allocation function. To allocate a buffer with a larger
2449 payload, and which retains the necessary sender data needed
2450 by this function, the *rmr_realloc_payload()* function must
2451 be used to extend the payload to a size suitable for the
2455 --------------------------------------------------------------------------------------------
2457 On success, a new message buffer, with an empty payload, is
2458 returned for the application to use for the next send. The
2459 state in this buffer will reflect the overall send operation
2460 state and should be RMR_OK.
2462 If the state in the returned buffer is anything other than
2463 UT_OK, the user application may need to attempt a
2464 retransmission of the message, or take other action depending
2465 on the setting of errno as described below.
2467 In the event of extreme failure, a NULL pointer is returned.
2468 In this case the value of errno might be of some use, for
2469 documentation, but there will be little that the user
2470 application can do other than to move on.
2473 --------------------------------------------------------------------------------------------
2475 The following values may be passed back in the *state* field
2476 of the returned message buffer.
2482 The message buffer pointer did not refer to a valid
2487 The header in the message buffer was not valid or
2492 The message type in the message buffer did not map to a
2497 The send failed; errno has the possible reason.
2500 The following values may be assigned to errno on failure.
2505 Parameter(s) passed to the function were not valid, or the
2506 underlying message processing environment was unable to
2507 interpret the message.
2512 The header information in the message buffer was invalid.
2517 No known endpoint for the message could be found.
2522 The underlying transport refused to accept the message
2523 because of a size value issue (message was not attempted
2529 The message referenced by the message buffer is corrupt
2530 (NULL pointer or bad internal length).
2535 Internal RMR error; information provided to the message
2536 transport environment was not valid.
2541 Sending was not supported by the underlying message
2547 The device is not in a state that can accept the message.
2552 The device is not able to accept a message for sending.
2553 The user application should attempt to resend.
2558 The operation was interrupted by delivery of a signal
2559 before the message was sent.
2564 The underlying message environment timed out during the
2570 The underlying message environment is in a shutdown state.
2574 --------------------------------------------------------------------------------------------
2578 --------------------------------------------------------------------------------------------
2580 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2581 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
2582 rmr_rcv_specific(3), rmr_ready(3), rmr_fib(3),
2583 rmr_has_str(3), rmr_set_stimeout(3), rmr_tokenise(3),
2584 rmr_mk_ring(3), rmr_ring_free(3)
2588 --------------------------------------------------------------------------------------------
2593 --------------------------------------------------------------------------------------------
2598 #include <rmr/rmr.h>
2599 rmr_mbuf_t* rmr_send_msg( void* vctx, rmr_mbuf_t* msg );
2604 --------------------------------------------------------------------------------------------
2606 The rmr_send_msg function accepts a message buffer from the
2607 user application and attempts to send it. The destination of
2608 the message is selected based on the message type specified
2609 in the message buffer, and the matching information in the
2610 routing tables which are currently in use by the RMR library.
2611 This may actually result in the sending of the message to
2612 multiple destinations which could degrade expected overall
2613 performance of the user application. (Limiting excessive
2614 sending of messages is the responsibility of the
2615 application(s) responsible for building the routing table
2616 used by the RMR library, and not the responsibility of the
2620 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2622 The send operations in RMr will retry *soft* send failures
2623 until one of three conditions occurs:
2629 The message is sent without error
2634 The underlying transport reports a * hard * failure
2639 The maximum number of retry loops has been attempted
2642 A retry loop consists of approximately 1000 send attemps **
2643 without** any intervening calls to * sleep() * or * usleep().
2644 * The number of retry loops defaults to 1, thus a maximum of
2645 1000 send attempts is performed before returning to the user
2646 application. This value can be set at any point after RMr
2647 initialisation using the * rmr_set_stimeout() * function
2648 allowing the user application to completely disable retires
2649 (set to 0), or to increase the number of retry loops.
2651 Transport Level Blocking
2652 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2654 The underlying transport mechanism used to send messages is
2655 configured in *non-blocking* mode. This means that if a
2656 message cannot be sent immediately the transport mechanism
2657 will **not** pause with the assumption that the inability to
2658 send will clear quickly (within a few milliseconds). This
2659 means that when the retry loop is completely disabled (set to
2660 0), that the failure to accept a message for sending by the
2661 underlying mechanisms (software or hardware) will be reported
2662 immediately to the user application.
2664 It should be noted that depending on the underlying transport
2665 mechanism being used, it is extremly possible that during
2666 normal operations that retry conditions are very likely to
2667 happen. These are completely out of RMr's control, and there
2668 is nothing that RMr can do to avoid or midigate these other
2669 than by allowing RMr to retry the send operation, and even
2670 then it is possible (e.g. during connection reattempts), that
2671 a single retry loop is not enough to guarentee a successful
2675 --------------------------------------------------------------------------------------------
2677 On success, a new message buffer, with an empty payload, is
2678 returned for the application to use for the next send. The
2679 state in this buffer will reflect the overall send operation
2680 state and will be RMR_OK when the send was successful.
2682 When the message cannot be successfully sent this function
2683 will return the unsent (original) message buffer with the
2684 state set to indicate the reason for failure. The value of
2685 *errno* may also be set to reflect a more detailed failure
2686 reason if it is known.
2688 In the event of extreme failure, a NULL pointer is returned.
2689 In this case the value of errno might be of some use, for
2690 documentation, but there will be little that the user
2691 application can do other than to move on.
2693 **CAUTION:** In some cases it is extremely likely that the
2694 message returned by the send function does **not** reference
2695 the same memory structure. Thus is important for the user
2696 programme to capture the new pointer for future use or to be
2697 passed to rmr_free(). If you are experiencing either double
2698 free errors or segment faults in either rmr_free() or
2699 rmr_send_msg(), ensure that the return value from this
2700 function is being captured and used.
2703 --------------------------------------------------------------------------------------------
2705 The following values may be passed back in the *state* field
2706 of the returned message buffer.
2712 The message could not be sent, but the underlying
2713 transport mechanism indicates that the failure is
2714 temporary. If the send operation is tried again it might
2719 The send operation was not successful and the underlying
2720 transport mechanism indicates a permanent (hard) failure;
2721 retrying the send is not possible.
2725 The message buffer pointer did not refer to a valid
2730 The header in the message buffer was not valid or
2735 The message type in the message buffer did not map to a
2739 The following values may be assigned to errno on failure.
2744 Parameter(s) passed to the function were not valid, or the
2745 underlying message processing environment was unable to
2746 interpret the message.
2751 The header information in the message buffer was invalid.
2756 No known endpoint for the message could be found.
2761 The underlying transport refused to accept the message
2762 because of a size value issue (message was not attempted
2768 The message referenced by the message buffer is corrupt
2769 (NULL pointer or bad internal length).
2774 Internal RMR error; information provided to the message
2775 transport environment was not valid.
2780 Sending was not supported by the underlying message
2786 The device is not in a state that can accept the message.
2791 The device is not able to accept a message for sending.
2792 The user application should attempt to resend.
2797 The operation was interrupted by delivery of a signal
2798 before the message was sent.
2803 The underlying message environment timed out during the
2809 The underlying message environment is in a shutdown state.
2813 --------------------------------------------------------------------------------------------
2815 The following is a simple example of how the rmr_send_msg
2816 function is called. In this example, the send message buffer
2817 is saved between calls and reused eliminating alloc/free
2823 static rmr_mbuf_t* send_msg = NULL; // message to send; reused on each call
2824 msg_t* send_pm; // payload for send
2825 msg_t* pm; // our message format in the received payload
2826 mif( send_msg == NULL ) {
2827 send_msg = rmr_alloc_msg( mr, MAX_SIZE ); r// new buffer to send
2829 // reference payload and fill in message type
2830 pm = (msg_t*) send_msg->payload;
2831 send_msg->mtype = MT_ANSWER;
2832 msg->len = generate_data( pm ); // something that fills the payload in
2833 msg = rmr_send_msg( mr, send_msg ); // ensure new pointer used after send
2837 m sif( msg->state != RMR_OK ) {
2838 m s m// check for RMR_ERR_RETRY, and resend if needed
2839 m s m// else return error
2847 --------------------------------------------------------------------------------------------
2849 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2850 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
2851 rmr_rts_msg(3), rmr_ready(3), rmr_mk_ring(3),
2852 rmr_ring_free(3), rmr_torcv_rcv(3), rmr_wh_send_msg(3)
2856 --------------------------------------------------------------------------------------------
2861 --------------------------------------------------------------------------------------------
2866 #include <rmr/rmr.h>
2867 void rmr_set_fack( void* vctx );
2872 --------------------------------------------------------------------------------------------
2874 The rmr_set_fack function enables *fast TCP acknowledgements*
2875 if the underlying transport library supports it. This might
2876 be useful for applications which must send messages as a
2880 --------------------------------------------------------------------------------------------
2882 There is no return value.
2885 --------------------------------------------------------------------------------------------
2887 This function does not generate any errors.
2890 --------------------------------------------------------------------------------------------
2896 --------------------------------------------------------------------------------------------
2901 --------------------------------------------------------------------------------------------
2906 #include <rmr/rmr.h>
2907 rmr_mbuf_t* rmr_set_stimeout( void* vctx, int rloops );
2912 --------------------------------------------------------------------------------------------
2914 The rmr_set_stimeout function sets the configuration for how
2915 RMr will retry message send operations which complete with
2916 either a *timeout* or *again* completion value. (Send
2917 operations include all of the possible message send
2918 functions: *rmr_send_msg(), rmr_call(), rmr_rts_msg()* and
2919 *rmr_wh_send_msg().* The *rloops* parameter sets the maximum
2920 number of retry loops that will be attempted before giving up
2921 and returning the unsuccessful state to the user application.
2922 Each retry loop is approximately 1000 attempts, and RMr does
2923 **not** invoke any sleep function between retries in the
2924 loop; a small, 1 mu-sec, sleep is executed between loop sets
2925 if the *rloops* value is greater than 1.
2929 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2931 By default, the send operations will execute with an *rloop*
2932 setting of 1; each send operation will attempt to resend the
2933 message approximately 1000 times before giving up. If the
2934 user application does not want to have send operations retry
2935 when the underlying transport mechanism indicates *timeout*
2936 or *again,* the application should invoke this function and
2937 pass a value of 0 (zero) for *rloops.* With this setting, all
2938 RMr send operations will attempt a send operation only
2939 **once,** returning immediately to the caller with the state
2940 of that single attempt.
2943 --------------------------------------------------------------------------------------------
2945 This function returns a -1 to indicate that the *rloops*
2946 value could not be set, and the value *RMR_OK* to indicate
2950 --------------------------------------------------------------------------------------------
2952 Currently errno is **not** set by this function; the only
2953 cause of a failure is an invalid context (*vctx*) pointer.
2956 --------------------------------------------------------------------------------------------
2958 The following is a simple example of how the rmr_set_stimeout
2965 char* Oport = "43086"; // port for message router listen
2966 int rmax_size = 4096; // max message size for default allocations
2967 void* mr_context; // message router context
2968 mr_context = rmr_init( port, max_size, NO_FLAGS );
2969 if( mr_context != NULL ) {
2970 rmr_set_stimeout( mr_context, 0 ); // turn off retries
2976 --------------------------------------------------------------------------------------------
2978 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2979 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
2980 rmr_rts_msg(3), rmr_ready(3), rmr_mk_ring(3),
2981 rmr_ring_free(3), rmr_send_msg(3), rmr_torcv_rcv(3),
2986 --------------------------------------------------------------------------------------------
2991 --------------------------------------------------------------------------------------------
2996 #include <rmr/rmr.h>
2997 int rmr_set_trace( rmr_mbuf_t* mbuf, unsigned char* data, int len )
3002 --------------------------------------------------------------------------------------------
3004 The rmr_set_trace function will copy len bytes from data into
3005 the trace portion of mbuf. If the trace area of mbuf is not
3006 the correct size, the message buffer will be reallocated to
3007 ensure that enough space is available for the trace data.
3010 --------------------------------------------------------------------------------------------
3012 The rmr_set_trace function returns the number of bytes
3013 successfully copied to the message. If 0 is returned either
3014 the message pointer was nil, or the size in the parameters
3018 --------------------------------------------------------------------------------------------
3020 rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3),
3021 rmr_bytes2payload(3), rmr_call(3), rmr_free_msg(3),
3022 rmr_get_rcvfd(3), rmr_get_meid(3), rmr_get_trace(3),
3023 rmr_get_trlen(3), rmr_init(3), rmr_init_trace(3),
3024 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
3025 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
3026 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
3027 rmr_ring_free(3), rmr_str2meid(3), rmr_str2xact(3),
3028 rmr_wh_open(3), rmr_wh_send_msg(3)
3032 --------------------------------------------------------------------------------------------
3037 --------------------------------------------------------------------------------------------
3042 #include <rmr/rmr.h>
3043 #include <rmr/rmr_logging.h>
3044 void rmr_set_vlevel( int new_level )
3049 --------------------------------------------------------------------------------------------
3051 The rmr_set_vlevel allows the user programme to set the
3052 verbosity level which is used to determine the messages RMR
3053 writes to standard error. The new_vlevel value must be one of
3054 the following constants which have the indicated meanings:
3059 Turns off all message writing. This includes the stats and
3060 debugging messages generated by the route collector thread
3061 which are normally affected only by the externally managed
3062 verbose level file (and related environment variable).
3067 Write only messages of critical importance. From the point
3068 of view of RMR, when a critical proper behaviour of the
3069 library cannot be expected or guaranteed.
3073 Include error messages in the output. An error is an event
3074 from which RMR has no means to recover. Continued proper
3075 execution is likely except where the affected connection
3076 and/or component mentioned in the error is concerned.
3080 Include warning messages in the output. A warning
3081 indicates an event which is not considered to be normal,
3082 but is expected and continued acceptable behaviour of the
3087 Include informational messagees in the output.
3088 Informational messages include some diagnostic information
3089 which explain the activities of RMR.
3093 Include all debugging messages in the output. Debugging
3094 must have also been enabled during the build as a
3095 precaution to accidentally enabling this level of output
3096 as it can grossly affect performance.
3099 generally RMR does not write messages to the standard error
3100 device from *critical path* functions, therefore it is
3101 usually not harmful to enable a verbosity level of either
3102 RMR_VL_CRIT, or RMR_VL_ERR.
3104 Messages written from the route table collection thread are
3105 still governed by the value placed into the verbose level
3106 control file (see the man page for rmr_init()); those
3107 messages are affected only when logging is completely
3108 disabled by passing RMR_VL_OFF to this function.
3110 The verbosity level can also be set via an environment
3111 variable prior to the start of the RMR based application. The
3112 environment variable is read only during initialisation; if
3113 the programme must change the value during execution, this
3114 function must be used. The default value, if this function is
3115 never called, and the environment variable is not present, is
3119 --------------------------------------------------------------------------------------------
3125 --------------------------------------------------------------------------------------------
3130 --------------------------------------------------------------------------------------------
3135 #include <rmr/rmr.h>
3136 int rmr_str2meid( rmr_mbuf_t* mbuf, unsigned char* src, int len )
3141 --------------------------------------------------------------------------------------------
3143 The rmr_str2meid function will copy the string pointed to by
3144 src to the managed entity ID (meid) field in the given
3145 message. The field is a fixed length, gated by the constant
3146 RMR_MAX_MEID and if string length is larger than this value,
3147 then **nothing** will be copied. (Note, this differs slightly
3148 from the behaviour of the lrmr_bytes2meid() function.)
3151 --------------------------------------------------------------------------------------------
3153 On success, the value RMR_OK is returned. If the string
3154 cannot be copied to the message, the return value will be one
3155 of the errors listed below.
3158 --------------------------------------------------------------------------------------------
3160 If the return value is not RMR_OK, then it will be set to one
3161 of the values below.
3167 The message, or an internal portion of the message, was
3168 corrupted or the pointer was invalid.
3173 The length passed in was larger than the maximum length of
3174 the field; only a portion of the source bytes were copied.
3178 --------------------------------------------------------------------------------------------
3182 --------------------------------------------------------------------------------------------
3184 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
3185 rmr_get_meid(3), rmr_get_rcvfd(3), rmr_payload_size(3),
3186 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
3187 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
3188 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
3189 rmr_bytes2meid(3), rmr_wh_open(3), rmr_wh_send_msg(3)
3193 --------------------------------------------------------------------------------------------
3198 --------------------------------------------------------------------------------------------
3203 #include <rmr/rmr.h>
3204 int rmr_str2xact( rmr_mbuf_t* mbuf, unsigned char* src, int len )
3209 --------------------------------------------------------------------------------------------
3211 The rmr_str2xact function will copy the string pointed to by
3212 src to the transaction ID (xaction) field in the given
3213 message. The field is a fixed length, gated by the constant
3214 RMR_MAX_XID and if string length is larger than this value,
3215 then **nothing** will be copied. (Note, this differs slightly
3216 from the behaviour of the lrmr_bytes2xact() function.)
3220 --------------------------------------------------------------------------------------------
3222 On success, the value RMR_OK is returned. If the string
3223 cannot be copied to the message, the return value will be
3224 one of the errors listed below.
3227 --------------------------------------------------------------------------------------------
3229 If the return value is not RMR_OK, then it will be set to
3230 one of the values below.
3235 The message, or an internal portion of the message, was
3236 corrupted or the pointer was invalid.
3241 The length passed in was larger than the maximum length of
3242 the field; only a portion of the source bytes were copied.
3246 --------------------------------------------------------------------------------------------
3250 --------------------------------------------------------------------------------------------
3252 rmr_alloc_msg(3), rmr_bytes2meid(3), rmr_bytes2xact(3),
3253 rmr_call(3), rmr_free_msg(3), rmr_get_meid(3),
3254 rmr_get_rcvfd(3), rmr_get_xact(3), rmr_payload_size(3),
3255 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
3256 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
3257 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
3258 rmr_str2meid(3), rmr_wh_open(3), rmr_wh_send_msg(3)
3262 --------------------------------------------------------------------------------------------
3264 RMR support functions
3267 --------------------------------------------------------------------------------------------
3272 #include <rmr/rmr.h>
3273 #include <rmr/ring_inline.h>
3274 char* rmr_fib( char* fname );
3275 int rmr_has_str( char const* buf, char const* str, char sep, int max );
3276 int rmr_tokenise( char* buf, char** tokens, int max, char sep );
3277 void* rmr_mk_ring( int size );
3278 void rmr_ring_free( void* vr );
3279 static inline void* rmr_ring_extract( void* vr )
3280 static inline int rmr_ring_insert( void* vr, void* new_data )
3285 --------------------------------------------------------------------------------------------
3287 These functions support the RMR library, and are made
3288 available to user applications as some (e.g. route table
3289 generators) might need and/or want to make use of them. The
3290 rmr_fib function accepts a file name and reads the entire
3291 file into a single buffer. The intent is to provide an easy
3292 way to load a static route table without a lot of buffered
3295 The rmr_has_str function accepts a *buffer* containing a set
3296 of delimited tokens (e.g. foo,bar,goo) and returns true if
3297 the target string, *str,* matches one of the tokens. The
3298 *sep* parameter provides the separation character in the
3299 buffer (e.g a comma) and *max* indicates the maximum number
3300 of tokens to split the buffer into before checking.
3302 The rmr_tokenise function is a simple tokeniser which splits
3303 *buf* into tokens at each occurrence of *sep*. Multiple
3304 occurrences of the separator character (e.g. a,,b) result in
3305 a nil token. Pointers to the tokens are placed into the
3306 *tokens* array provided by the caller which is assumed to
3307 have at least enough space for *max* entries.
3309 The rmr_mk_ring function creates a buffer ring with *size*
3312 The rmr_ring_free function accepts a pointer to a ring
3313 context and frees the associated memory.
3315 The rmr_ring_insert and rmr_ring_extract functions are
3316 provided as static inline functions via the
3317 *rmr/ring_inline.h* header file. These functions both accept
3318 the ring *context* returned by mk_ring, and either insert a
3319 pointer at the next available slot (tail) or extract the data
3323 --------------------------------------------------------------------------------------------
3325 The following are the return values for each of these
3328 The rmr_fib function returns a pointer to the buffer
3329 containing the contents of the file. The buffer is terminated
3330 with a single nil character (0) making it a legitimate C
3331 string. If the file was empty or nonexistent, a buffer with
3332 an immediate nil character. If it is important to the calling
3333 programme to know if the file was empty or did not exist, the
3334 caller should use the system stat function call to make that
3337 The rmr_has_str function returns 1 if *buf* contains the
3338 token referenced by &ita and false (0) if it does not. On
3339 error, a -1 value is returned and errno is set accordingly.
3341 The rmr_tokenise function returns the actual number of token
3342 pointers placed into *tokens*
3344 The rmr_mk_ring function returns a void pointer which is the
3345 *context* for the ring.
3347 The rmr_ring_insert function returns 1 if the data was
3348 successfully inserted into the ring, and 0 if the ring is
3349 full and the pointer could not be deposited.
3351 The rmr_ring_extract will return the data which is at the
3352 head of the ring, or NULL if the ring is empty.
3355 --------------------------------------------------------------------------------------------
3357 Not many of these functions set the value in errno, however
3358 the value may be one of the following:
3363 Parameter(s) passed to the function were not valid.
3367 --------------------------------------------------------------------------------------------
3371 --------------------------------------------------------------------------------------------
3373 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
3374 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
3375 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
3379 --------------------------------------------------------------------------------------------
3384 --------------------------------------------------------------------------------------------
3389 #include <rmr/rmr.h>
3390 rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to );
3395 --------------------------------------------------------------------------------------------
3397 The rmr_torcv_msg function will pause for *ms_to*
3398 milliseconds waiting for a message to arrive. If a message
3399 arrives before the timeout expires the message buffer
3400 returned will have a status of RMR_OK and the payload will
3401 contain the data received. If the timeout expires before the
3402 message is received, the status will have the value
3403 RMR_ERR_TIMEOUT. When a received message is returned the
3404 message buffer will also contain the message type and length
3405 set by the sender. If messages were queued while waiting for
3406 the response to a previous invocation of rmr_call, the oldest
3407 message is removed from the queue and returned without delay.
3409 The *vctx* pointer is the pointer returned by the rmr_init
3410 function. *Old_msg* is a pointer to a previously used message
3411 buffer or NULL. The ability to reuse message buffers helps to
3412 avoid alloc/free cycles in the user application. When no
3413 buffer is available to supply, the receive function will
3417 --------------------------------------------------------------------------------------------
3419 The function returns a pointer to the rmr_mbuf_t structure
3420 which references the message information (state, length,
3421 payload), or a NULL pointer in the case of an extreme error.
3424 --------------------------------------------------------------------------------------------
3426 The *state* field in the message buffer will be one of the
3433 The message buffer (payload) references the received data.
3438 The first call to this function must initialise an
3439 underlying system notification mechanism. On failure, this
3440 error is returned and errno will have the system error
3441 status set. If this function fails to intialise, the poll
3442 mechansim, it is likely that message receives will never
3448 The timeout expired before a complete message was
3449 received. All other fields in the message buffer are not
3455 A message was received, but it had no payload. All other
3456 fields in the message buffer are not valid.
3463 Parameter(s) passed to the function were not valid.
3468 The underlying message transport is unable to process the
3474 The underlying message transport is unable to process the
3480 The underlying message transport is unable to process the
3486 The underlying message transport is unable to process the
3492 The underlying message transport is unable to process the
3498 The underlying message transport is unable to process the
3504 The underlying message transport is unable to process the
3509 --------------------------------------------------------------------------------------------
3513 --------------------------------------------------------------------------------------------
3515 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
3516 rmr_get_rcvfd(3), rmr_init(3), rmr_payload_size(3),
3517 rmr_rcv_msg(3), rmr_send_msg(3), rmr_rcv_specific(3),
3518 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
3519 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
3523 --------------------------------------------------------------------------------------------
3528 --------------------------------------------------------------------------------------------
3533 #include <rmr/rmr.h>
3534 int rmr_trace_ref( rmr_mbuf_t* mbuf, int* sizeptr )
3539 --------------------------------------------------------------------------------------------
3541 The rmr_trace_ref function return a pointer to the trace area
3542 in the message, and optionally populate the user programme
3543 supplied size integer with the trace area size, if *sizeptr*
3547 --------------------------------------------------------------------------------------------
3549 On success, a void pointer to the trace area of the message
3550 is returned. A nil pointer is returned if the message has no
3551 trace data area allocated, or if the message itself is
3555 --------------------------------------------------------------------------------------------
3557 rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3),
3558 rmr_bytes2meid(3), rmr_call(3), rmr_free_msg(3),
3559 rmr_get_rcvfd(3), rmr_get_trlen(3), rmr_init(3),
3560 rmr_init_trace(3), rmr_payload_size(3), rmr_send_msg(3),
3561 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
3562 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
3563 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
3564 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3),
3569 --------------------------------------------------------------------------------------------
3574 --------------------------------------------------------------------------------------------
3579 #include <rmr/rmr.h>
3580 rmr_mbuf_t* rmr_tralloc_msg( void* vctx, int size,
3581 int trace_size, unsigned const char *tr_data );
3586 --------------------------------------------------------------------------------------------
3588 The rmr_alloc_msg function is used to allocate a buffer which
3589 the user programme can write into and then send through the a
3590 library. The buffer is allocated such that sending it
3591 requires no additional copying from the buffer as it passes
3592 through the underlying transport mechanism.
3594 The *size* parameter is used to set the payload length in the
3595 message and If it is 0, then the default size supplied on the
3596 *rmr_init* call will be used. In addition to allocating the
3597 payload, a space in the buffer is reserved for *trace* data
3598 (tr_size bytes), and the bytes pointed to by *tr_data* are
3599 copied into that portion of the message. The *vctx* parameter
3600 is the void context pointer that was returned by the
3601 *rmr_init* function.
3603 The pointer to the message buffer returned is a structure
3604 which has some user application visible fields; the structure
3605 is described in rmr.h, and is illustrated below.
3614 unsigned char* payload;
3615 unsigned char* xaction;
3624 Is the current buffer state. Following a call to
3625 rmr_send_msg the state indicates whether the buffer was
3626 successfully sent which determines exactly what the
3627 payload points to. If the send failed, the payload
3628 referenced by the buffer is the message that failed to
3629 send (allowing the application to attempt a
3630 retransmission). When the state is a_OK the buffer
3631 represents an empty buffer that the application may fill
3632 in in preparation to send.
3637 When sending a message, the application is expected to set
3638 this field to the appropriate message type value (as
3639 determined by the user programme). Upon send this value
3640 determines how the a library will route the message. For a
3641 buffer which has been received, this field will contain
3642 the message type that was set by the sending application.
3647 The application using a buffer to send a message is
3648 expected to set the length value to the actual number of
3649 bytes that it placed into the message. This is likely less
3650 than the total number of bytes that the message can carry.
3651 For a message buffer that is passed to the application as
3652 the result of a receive call, this will be the value that
3653 the sending application supplied and should indicate the
3654 number of bytes in the payload which are valid.
3659 The payload is a pointer to the actual received data. The
3660 user programme may read and write from/to the memory
3661 referenced by the payload up until the point in time that
3662 the buffer is used on a rmr_send, rmr_call or rmr_reply
3663 function call. Once the buffer has been passed back to a a
3664 library function the user programme should **NOT** make
3665 use of the payload pointer.
3670 The *xaction* field is a pointer to a fixed sized area in
3671 the message into which the user may write a transaction
3672 ID. The ID is optional with the exception of when the user
3673 application uses the rmr_call function to send a message
3674 and wait for the reply; the underlying a processing
3675 expects that the matching reply message will also contain
3676 the same data in the *xaction* field.
3680 --------------------------------------------------------------------------------------------
3682 The function returns a pointer to a rmr_mbuf structure, or
3686 --------------------------------------------------------------------------------------------
3692 Unable to allocate memory.
3696 --------------------------------------------------------------------------------------------
3698 rmr_alloc_msg(3), rmr_mbuf(3) rmr_call(3), rmr_free_msg(3),
3699 rmr_init(3), rmr_init_trace(3), rmr_get_trace(3),
3700 rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
3701 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
3702 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
3703 rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)
3707 --------------------------------------------------------------------------------------------
3712 --------------------------------------------------------------------------------------------
3717 #include <rmr/rmr.h>
3718 rmr_mbuf_t* rmr_wh_call( void* vctx, rmr_whid_t whid, rmr_mbuf_t* msg, int call_id, int max_wait )
3723 --------------------------------------------------------------------------------------------
3725 The rmr_wh_call function accepts a message buffer (msg) from
3726 the user application and attempts to send it using the
3727 wormhole ID provided (whid). If the send is successful, the
3728 call will block until either a response message is received,
3729 or the max_wait number of milliseconds has passed. In order
3730 for the response to be recognised as a response, the remote
3731 process **must** use rmr_rts_msg() to send their response.
3733 Like *rmr_wh_send_msg,* this function attempts to send the
3734 message directly to a process at the other end of a wormhole
3735 which was created with *rmr_wh-open().* When sending message
3736 via wormholes, the normal RMr routing based on message type
3737 is ignored, and the caller may leave the message type
3738 unspecified in the message buffer (unless it is needed by the
3739 receiving process). The call_id parameter is a number in the
3740 range of 2 through 255 and is used to identify the calling
3741 thread in order to properly match a response message when it
3742 arrives. Providing this value, and ensuring the proper
3743 uniqueness, is the responsibility of the user application and
3744 as such the ability to use the rmr_wh_call() function from
3745 potentially non-threaded concurrent applications (such as
3746 Go's goroutines) is possible.
3749 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3751 The send operations in RMr will retry *soft* send failures
3752 until one of three conditions occurs:
3758 The message is sent without error
3763 The underlying transport reports a * hard * failure
3768 The maximum number of retry loops has been attempted
3771 A retry loop consists of approximately 1000 send attemps **
3772 without** any intervening calls to * sleep() * or * usleep().
3773 * The number of retry loops defaults to 1, thus a maximum of
3774 1000 send attempts is performed before returning to the user
3775 application. This value can be set at any point after RMr
3776 initialisation using the * rmr_set_stimeout() * function
3777 allowing the user application to completely disable retires
3778 (set to 0), or to increase the number of retry loops.
3780 Transport Level Blocking
3781 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3783 The underlying transport mechanism used to send messages is
3784 configured in *non-blocking* mode. This means that if a
3785 message cannot be sent immediately the transport mechanism
3786 will **not** pause with the assumption that the inability to
3787 send will clear quickly (within a few milliseconds). This
3788 means that when the retry loop is completely disabled (set to
3789 0), that the failure to accept a message for sending by the
3790 underlying mechanisms (software or hardware) will be reported
3791 immediately to the user application.
3793 It should be noted that depending on the underlying transport
3794 mechanism being used, it is extremly possible that during
3795 normal operations that retry conditions are very likely to
3796 happen. These are completely out of RMr's control, and there
3797 is nothing that RMr can do to avoid or midigate these other
3798 than by allowing RMr to retry the send operation, and even
3799 then it is possible (e.g. during connection reattempts), that
3800 a single retry loop is not enough to guarentee a successful
3804 --------------------------------------------------------------------------------------------
3806 On success, new message buffer, with the payload containing
3807 the response from the remote endpoint is returned. The state
3808 in this buffer will reflect the overall send operation state
3809 and should be RMR_OK.
3811 If a message is returned with a state which is anything other
3812 than RMR_OK, the indication is that the send was not
3813 successful. The user application must check the state and
3814 determine the course of action. If the return value is NULL,
3815 no message, the indication is that there was no response
3816 received within the timeout (max_wait) period of time.
3819 --------------------------------------------------------------------------------------------
3821 The following values may be passed back in the *state* field
3822 of the returned message buffer.
3828 The wormhole ID passed in was not associated with an open
3829 wormhole, or was out of range for a valid ID.
3833 No wormholes exist, further attempt to validate the ID are
3838 The message buffer pointer did not refer to a valid
3843 The header in the message buffer was not valid or
3848 --------------------------------------------------------------------------------------------
3850 The following is a simple example of how the a wormhole is
3851 created (rmr_wh_open) and then how rmr_wh_send_msg function
3852 is used to send messages. Some error checking is omitted for
3858 #include <rmr/rmr.h> .// system headers omitted for clarity
3860 rmr_whid_t whid = -1; // wormhole id for sending
3861 void* mrc; //msg router context
3863 rmr_mbuf_t* sbuf; // send buffer
3865 mrc = rmr_init( "43086", RMR_MAX_RCV_BYTES, RMRFL_NONE );
3867 fprintf( stderr, "[FAIL] unable to initialise RMr environment\\n" );
3870 while( ! rmr_ready( mrc ) ) { e i// wait for routing table info
3873 sbuf = rmr_alloc_msg( mrc, 2048 );
3876 whid = rmr_wh_open( mrc, "localhost:6123" ); // open fails if endpoint refuses conn
3877 w if( RMR_WH_CONNECTED( wh ) ) {
3878 snprintf( sbuf->payload, 1024, "periodic update from sender: %d", count++ );
3879 sbuf->len = strlen( sbuf->payload );
3880 sbuf = rmr_wh_call( mrc, whid, sbuf, 1000 ); f s// expect a response in 1s or less
3881 if( sbuf != NULL && sbuf->state = RMR_OK ) {
3882 sprintf( stderr, "response: %s\\n", sbuf->payload ); x// assume they sent a string
3884 sprintf( stderr, "response not received, or send error\\n" );
3895 --------------------------------------------------------------------------------------------
3897 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
3898 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
3899 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
3900 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
3901 rmr_set_stimeout(3), rmr_wh_open(3), rmr_wh_close(3),
3906 --------------------------------------------------------------------------------------------
3911 --------------------------------------------------------------------------------------------
3916 #include <rmr/rmr.h>
3917 void rmr_close( void* vctx, rmr_whid_t whid )
3922 --------------------------------------------------------------------------------------------
3924 The rmr_wh_close function closes the wormhole associated with
3925 the wormhole id passed in. Future calls to rmr_wh_send_msg
3926 with this ID will fail.
3928 The underlying TCP connection to the remote endpoint is
3929 **not** closed as this session may be reqruired for
3930 regularlly routed messages (messages routed based on message
3931 type). There is no way to force a TCP session to be closed at
3935 --------------------------------------------------------------------------------------------
3937 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
3938 rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3),
3939 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
3940 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
3941 rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_open(3),
3946 --------------------------------------------------------------------------------------------
3951 --------------------------------------------------------------------------------------------
3956 #include <rmr/rmr.h>
3957 void* rmr_wh_open( void* vctx, char* target )
3962 --------------------------------------------------------------------------------------------
3964 The rmr_wh_open function creates a direct link for sending, a
3965 wormhole, to another RMr based process. Sending messages
3966 through a wormhole requires that the connection be
3967 established overtly by the user application (via this
3968 function), and that the ID returned by rmr_wh_open be passed
3969 to the rmr_wh_send_msg function.
3971 *Target* is the *name* or *IP-address* combination of the
3972 processess that the wormhole should be connected to. *Vctx*
3973 is the RMr void context pointer that was returned by the
3976 When invoked, this function immediatly attempts to connect to
3977 the target process. If the connection cannot be established,
3978 an error is returned to the caller, and no direct messages
3979 can be sent to the target. Once a wormhole is connected, the
3980 underlying transport mechanism (e.g. NNG) will provide
3981 reconnects should the connection be lost, however the
3982 handling of messages sent when a connection is broken is
3983 undetermined as each underlying transport mechanism may
3984 handle buffering and retries differently.
3987 --------------------------------------------------------------------------------------------
3989 The rmr_wh_open function returns a type rmr_whid_t which must
3990 be passed to the rmr_wh_send_msg function when sending a
3991 message. The id may also be tested to determine success or
3992 failure of the connection by using the RMR_WH_CONNECTED macro
3993 and passing the ID as the parameter; a result of 1 indicates
3994 that the connection was esablished and that the ID is valid.
3997 --------------------------------------------------------------------------------------------
3999 The following error values are specifically set by this RMR
4000 function. In some cases the error message of a system call is
4001 propagated up, and thus this list might be incomplete.
4006 A parameter passed was not valid.
4010 The user applicarion does not have the ability to
4011 establish a wormhole to the indicated target (or maybe any
4016 The connection was refused.
4020 --------------------------------------------------------------------------------------------
4027 rmc = rmr_init( "43086", 4096, 0 ); // init context
4028 wh = rmr_wh_open( rmc, "localhost:6123" );
4029 if( !RMR_WH_CONNECTED( wh ) ) {
4030 f fprintf( stderr, "unable to connect wormhole: %s\\n",
4031 strerror( errno ) );
4037 --------------------------------------------------------------------------------------------
4039 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
4040 rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3),
4041 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
4042 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
4043 rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_close(3),
4044 rmr_wh_send_msg(3), rmr_wh_state(3)
4048 --------------------------------------------------------------------------------------------
4053 --------------------------------------------------------------------------------------------
4058 #include <rmr/rmr.h>
4059 rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t id, rmr_mbuf_t* msg );
4064 --------------------------------------------------------------------------------------------
4066 The rmr_wh_send_msg function accepts a message buffer from
4067 the user application and attempts to send it using the
4068 wormhole ID provided (id). Unlike *rmr_send_msg,* this
4069 function attempts to send the message directly to a process
4070 at the other end of a wormhole which was created with
4071 *rmr_wh-open().* When sending message via wormholes, the
4072 normal RMr routing based on message type is ignored, and the
4073 caller may leave the message type unspecified in the message
4074 buffer (unless it is needed by the receiving process).
4076 The message buffer (msg) used to send is the same format as
4077 used for regular RMr send and reply to sender operations,
4078 thus any buffer allocated by these means, or calls to
4079 *rmr_rcv_msg()* can be passed to this function.
4082 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4084 The send operations in RMr will retry *soft* send failures
4085 until one of three conditions occurs:
4091 The message is sent without error
4096 The underlying transport reports a * hard * failure
4101 The maximum number of retry loops has been attempted
4104 A retry loop consists of approximately 1000 send attemps **
4105 without** any intervening calls to * sleep() * or * usleep().
4106 * The number of retry loops defaults to 1, thus a maximum of
4107 1000 send attempts is performed before returning to the user
4108 application. This value can be set at any point after RMr
4109 initialisation using the * rmr_set_stimeout() * function
4110 allowing the user application to completely disable retires
4111 (set to 0), or to increase the number of retry loops.
4113 Transport Level Blocking
4114 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4116 The underlying transport mechanism used to send messages is
4117 configured in *non-blocking* mode. This means that if a
4118 message cannot be sent immediately the transport mechanism
4119 will **not** pause with the assumption that the inability to
4120 send will clear quickly (within a few milliseconds). This
4121 means that when the retry loop is completely disabled (set to
4122 0), that the failure to accept a message for sending by the
4123 underlying mechanisms (software or hardware) will be reported
4124 immediately to the user application.
4126 It should be noted that depending on the underlying transport
4127 mechanism being used, it is extremly possible that during
4128 normal operations that retry conditions are very likely to
4129 happen. These are completely out of RMr's control, and there
4130 is nothing that RMr can do to avoid or midigate these other
4131 than by allowing RMr to retry the send operation, and even
4132 then it is possible (e.g. during connection reattempts), that
4133 a single retry loop is not enough to guarentee a successful
4137 --------------------------------------------------------------------------------------------
4139 On success, a new message buffer, with an empty payload, is
4140 returned for the application to use for the next send. The
4141 state in this buffer will reflect the overall send operation
4142 state and should be RMR_OK.
4144 If the state in the returned buffer is anything other than
4145 RMR_OK, the user application may need to attempt a
4146 retransmission of the message, or take other action depending
4147 on the setting of errno as described below.
4149 In the event of extreme failure, a NULL pointer is returned.
4150 In this case the value of errno might be of some use, for
4151 documentation, but there will be little that the user
4152 application can do other than to move on.
4155 --------------------------------------------------------------------------------------------
4157 The following values may be passed back in the *state* field
4158 of the returned message buffer.
4164 The wormhole ID passed in was not associated with an open
4165 wormhole, or was out of range for a valid ID.
4169 No wormholes exist, further attempt to validate the ID are
4174 The message buffer pointer did not refer to a valid
4179 The header in the message buffer was not valid or
4183 The following values may be assigned to errno on failure.
4188 Parameter(s) passed to the function were not valid, or the
4189 underlying message processing environment was unable to
4190 interpret the message.
4195 The header information in the message buffer was invalid.
4200 No known endpoint for the message could be found.
4205 The underlying transport refused to accept the message
4206 because of a size value issue (message was not attempted
4212 The message referenced by the message buffer is corrupt
4213 (NULL pointer or bad internal length).
4218 Internal RMR error; information provided to the message
4219 transport environment was not valid.
4224 Sending was not supported by the underlying message
4230 The device is not in a state that can accept the message.
4235 The device is not able to accept a message for sending.
4236 The user application should attempt to resend.
4241 The operation was interrupted by delivery of a signal
4242 before the message was sent.
4247 The underlying message environment timed out during the
4253 The underlying message environment is in a shutdown state.
4257 --------------------------------------------------------------------------------------------
4259 The following is a simple example of how the a wormhole is
4260 created (rmr_wh_open) and then how rmr_wh_send_msg function
4261 is used to send messages. Some error checking is omitted for
4267 #include <rmr/rmr.h> .// system headers omitted for clarity
4269 rmr_whid_t whid = -1; // wormhole id for sending
4270 void* mrc; //msg router context
4272 rmr_mbuf_t* sbuf; // send buffer
4274 mrc = rmr_init( "43086", RMR_MAX_RCV_BYTES, RMRFL_NONE );
4276 fprintf( stderr, "[FAIL] unable to initialise RMr environment\\n" );
4279 while( ! rmr_ready( mrc ) ) { e i// wait for routing table info
4282 sbuf = rmr_alloc_msg( mrc, 2048 );
4285 whid = rmr_wh_open( mrc, "localhost:6123" ); // open fails if endpoint refuses conn
4286 w if( RMR_WH_CONNECTED( wh ) ) {
4287 snprintf( sbuf->payload, 1024, "periodic update from sender: %d", count++ );
4288 sbuf->len = strlen( sbuf->payload );
4289 sbuf = rmr_wh_send_msg( mrc, whid, sbuf );
4299 --------------------------------------------------------------------------------------------
4301 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
4302 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
4303 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
4304 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
4305 rmr_set_stimeout(3), rmr_wh_open(3), rmr_wh_close(3),
4310 --------------------------------------------------------------------------------------------
4315 --------------------------------------------------------------------------------------------
4320 #include <rmr/rmr.h>
4321 int rmr_wh_state( void* vctx, rmr_whid_t whid )
4326 --------------------------------------------------------------------------------------------
4328 The rmr_wh_state function will return the current state of
4329 the connection associated with the given wormhole (whid). The
4330 return value indicates whether the connection is open
4331 (RMR_OK), or closed (any other return value).
4333 When using some transport mechanisms (e.g. NNG), it may not
4334 be possible for RMR to know the actual state and the
4335 connection may always be reported as "open."
4338 --------------------------------------------------------------------------------------------
4340 The following values are potential return values.
4346 The wormhole ID is valid and the connection is "open."
4351 THe wormhole ID passed into the function was not valid.
4356 The wormhole is not open (not connected).
4361 The context passed to the function was nil or invalid.
4366 Wormholes have not been initialised (no wormhole open call
4372 --------------------------------------------------------------------------------------------
4374 rmr_wh_open(3), rmr_wh_send_msg(3), rmr_wh_close(3)