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