3 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
4 .. SPDX-License-Identifier: CC-BY-4.0
5 .. CAUTION: this document is generated from source in doc/src/rtd.
6 .. To make changes edit the source and recompile the document.
7 .. Do NOT make changes directly to .rst or .md files.
10 ============================================================================================
12 ============================================================================================
15 ============================================================================================
19 --------------------------------------------------------------------------------------------
24 --------------------------------------------------------------------------------------------
30 void* rmr_wh_open( void* vctx, char* target )
35 --------------------------------------------------------------------------------------------
37 The rmr_wh_open function creates a direct link for sending, a
38 wormhole, to another RMR based process. Sending messages
39 through a wormhole requires that the connection be
40 established overtly by the user application (via this
41 function), and that the ID returned by rmr_wh_open be passed
42 to the rmr_wh_send_msg function.
44 *Target* is the *name* or *IP-address* combination of the
45 processess that the wormhole should be connected to. *Vctx*
46 is the RMR void context pointer that was returned by the
49 When invoked, this function immediatly attempts to connect to
50 the target process. If the connection cannot be established,
51 an error is returned to the caller, and no direct messages
52 can be sent to the target. Once a wormhole is connected, the
53 underlying transport mechanism (e.g. NNG) will provide
54 reconnects should the connection be lost, however the
55 handling of messages sent when a connection is broken is
56 undetermined as each underlying transport mechanism may
57 handle buffering and retries differently.
60 --------------------------------------------------------------------------------------------
62 The rmr_wh_open function returns a type rmr_whid_t which must
63 be passed to the rmr_wh_send_msg function when sending a
64 message. The id may also be tested to determine success or
65 failure of the connection by using the RMR_WH_CONNECTED macro
66 and passing the ID as the parameter; a result of 1 indicates
67 that the connection was esablished and that the ID is valid.
70 --------------------------------------------------------------------------------------------
72 The following error values are specifically set by this RMR
73 function. In some cases the error message of a system call is
74 propagated up, and thus this list might be incomplete.
79 A parameter passed was not valid.
83 The user application does not have the ability to
84 establish a wormhole to the indicated target (or maybe any
89 The connection was refused.
93 --------------------------------------------------------------------------------------------
100 rmc = rmr_init( "43086", 4096, 0 ); // init context
101 wh = rmr_wh_open( rmc, "localhost:6123" );
102 if( !RMR_WH_CONNECTED( wh ) ) {
103 fprintf( stderr, "unable to connect wormhole: %s\\n",
110 --------------------------------------------------------------------------------------------
112 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
113 rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3),
114 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
115 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
116 rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_close(3),
117 rmr_wh_send_msg(3), rmr_wh_state(3)