From 36fd87810274329c8cd86344b95a0521541e7bab Mon Sep 17 00:00:00 2001 From: Martin Sustrik Date: Sat, 21 Apr 2012 07:07:57 +0200 Subject: xs_shutdown implemented This patch allows for partial shutdown of the socket. Signed-off-by: Martin Sustrik --- doc/Makefile.am | 2 +- doc/xs_bind.txt | 8 +++--- doc/xs_connect.txt | 8 +++--- doc/xs_inproc.txt | 8 +++--- doc/xs_ipc.txt | 4 +-- doc/xs_pgm.txt | 4 +-- doc/xs_setsockopt.txt | 8 +++--- doc/xs_shutdown.txt | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++ doc/xs_tcp.txt | 10 ++++---- 9 files changed, 95 insertions(+), 26 deletions(-) create mode 100644 doc/xs_shutdown.txt (limited to 'doc') diff --git a/doc/Makefile.am b/doc/Makefile.am index 66dd87b..9f90feb 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -3,7 +3,7 @@ MAN3 = xs_bind.3 xs_close.3 xs_connect.3 xs_init.3 \ xs_msg_init_data.3 xs_msg_init_size.3 xs_msg_move.3 xs_msg_size.3 \ xs_poll.3 xs_recv.3 xs_send.3 xs_setsockopt.3 xs_socket.3 \ xs_strerror.3 xs_term.3 xs_version.3 xs_getsockopt.3 xs_errno.3 \ - xs_sendmsg.3 xs_recvmsg.3 xs_getmsgopt.3 xs_setctxopt.3 + xs_sendmsg.3 xs_recvmsg.3 xs_getmsgopt.3 xs_setctxopt.3 xs_shutdown.3 MAN7 = xs.7 xs_tcp.7 xs_pgm.7 xs_inproc.7 xs_ipc.7 xs_zmq.7 MAN_DOC = $(MAN1) $(MAN3) $(MAN7) diff --git a/doc/xs_bind.txt b/doc/xs_bind.txt index fc08124..3472f04 100644 --- a/doc/xs_bind.txt +++ b/doc/xs_bind.txt @@ -38,8 +38,8 @@ semantics involved when connecting or binding a socket to multiple endpoints. RETURN VALUE ------------ -The _xs_bind()_ function shall return zero if successful. Otherwise it shall -return `-1` and set 'errno' to one of the values defined below. +The _xs_bind()_ function shall return endpoint ID if successful. Otherwise it +shall return `-1` and set 'errno' to one of the values defined below. ERRORS @@ -71,10 +71,10 @@ void *socket = xs_socket (context, XS_PUB); assert (socket); /* Bind it to a in-process transport with the address 'my_publisher' */ int rc = xs_bind (socket, "inproc://my_publisher"); -assert (rc == 0); +assert (rc != -1); /* Bind it to a TCP transport on port 5555 of the 'eth0' interface */ rc = xs_bind (socket, "tcp://eth0:5555"); -assert (rc == 0); +assert (rc != -1); ---- diff --git a/doc/xs_connect.txt b/doc/xs_connect.txt index 898b915..02597da 100644 --- a/doc/xs_connect.txt +++ b/doc/xs_connect.txt @@ -42,8 +42,8 @@ physical connection was or can actually be established. RETURN VALUE ------------ -The _xs_connect()_ function shall return zero if successful. Otherwise it -shall return `-1` and set 'errno' to one of the values defined below. +The _xs_connect()_ function shall return endpoint ID if successful. Otherwise +it shall return `-1` and set 'errno' to one of the values defined below. ERRORS @@ -69,10 +69,10 @@ void *socket = xs_socket (context, XS_SUB); assert (socket); /* Connect it to an in-process transport with the address 'my_publisher' */ int rc = xs_connect (socket, "inproc://my_publisher"); -assert (rc == 0); +assert (rc != -1); /* Connect it to the host server001, port 5555 using a TCP transport */ rc = xs_connect (socket, "tcp://server001:5555"); -assert (rc == 0); +assert (rc != -1); ---- diff --git a/doc/xs_inproc.txt b/doc/xs_inproc.txt index 9ec255f..f0dae94 100644 --- a/doc/xs_inproc.txt +++ b/doc/xs_inproc.txt @@ -50,20 +50,20 @@ EXAMPLES ---- /* Assign the in-process name "#1" */ rc = xs_bind(socket, "inproc://#1"); -assert (rc == 0); +assert (rc != -1); /* Assign the in-process name "my-endpoint" */ rc = xs_bind(socket, "inproc://my-endpoint"); -assert (rc == 0); +assert (rc != -1); ---- .Connecting a socket ---- /* Connect to the in-process name "#1" */ rc = xs_connect(socket, "inproc://#1"); -assert (rc == 0); +assert (rc != -1); /* Connect to the in-process name "my-endpoint" */ rc = xs_connect(socket, "inproc://my-endpoint"); -assert (rc == 0); +assert (rc != -1); ---- diff --git a/doc/xs_ipc.txt b/doc/xs_ipc.txt index f3c5147..b917c78 100644 --- a/doc/xs_ipc.txt +++ b/doc/xs_ipc.txt @@ -54,14 +54,14 @@ EXAMPLES ---- /* Assign the pathname "/tmp/feeds/0" */ rc = xs_bind(socket, "ipc:///tmp/feeds/0"); -assert (rc == 0); +assert (rc != -1); ---- .Connecting a socket ---- /* Connect to the pathname "/tmp/feeds/0" */ rc = xs_connect(socket, "ipc:///tmp/feeds/0"); -assert (rc == 0); +assert (rc != -1); ---- SEE ALSO diff --git a/doc/xs_pgm.txt b/doc/xs_pgm.txt index fcce19a..2fc6ca8 100644 --- a/doc/xs_pgm.txt +++ b/doc/xs_pgm.txt @@ -137,12 +137,12 @@ EXAMPLE /* using the first Ethernet network interface on Linux */ /* and the Encapsulated PGM protocol */ rc = xs_connect(socket, "epgm://eth0;239.192.1.1:5555"); -assert (rc == 0); +assert (rc != -1); /* Connecting to the multicast address 239.192.1.1, port 5555, */ /* using the network interface with the address 192.168.1.1 */ /* and the standard PGM protocol */ rc = xs_connect(socket, "pgm://192.168.1.1;239.192.1.1:5555"); -assert (rc == 0); +assert (rc != -1); ---- diff --git a/doc/xs_setsockopt.txt b/doc/xs_setsockopt.txt index e07d9dd..d636c83 100644 --- a/doc/xs_setsockopt.txt +++ b/doc/xs_setsockopt.txt @@ -397,15 +397,15 @@ int64_t affinity; /* Incoming connections on TCP port 5555 shall be handled by I/O thread 1 */ affinity = 1; rc = xs_setsockopt (socket, XS_AFFINITY, &affinity, sizeof affinity); -assert (rc); +assert (rc == 0); rc = xs_bind (socket, "tcp://lo:5555"); -assert (rc); +assert (rc != -1); /* Incoming connections on TCP port 5556 shall be handled by I/O thread 2 */ affinity = 2; rc = xs_setsockopt (socket, XS_AFFINITY, &affinity, sizeof affinity); -assert (rc); +assert (rc == 0); rc = xs_bind (socket, "tcp://lo:5556"); -assert (rc); +assert (rc != -1); ---- diff --git a/doc/xs_shutdown.txt b/doc/xs_shutdown.txt new file mode 100644 index 0000000..8943933 --- /dev/null +++ b/doc/xs_shutdown.txt @@ -0,0 +1,69 @@ +xs_bind(3) +========== + + +NAME +---- +xs_shutdown - shut down part of the socket + + +SYNOPSIS +-------- +*int xs_shutdown (void '*socket', int 'how');* + + +DESCRIPTION +----------- +This function partially closes the socket. It disconnects or unbinds an endpoint +previously connected or bound by _xs_bind()_ or _xs_connect()_. 'how' parameter +is the endpoint ID as returned by _xs_bind()_ or _xs_connect()_. + +Endpoint shutdown honours 'linger' socket option. I.e. if there are any pending +outbound messages, Crossroads will try to push them to the network for the +specified amount of time before giving up. + +Note: inproc endpoints don't support partial shutdown at the moment. + +RETURN VALUE +------------ +The _xs_shutdown()_ function shall return zero if successful. Otherwise it +shall return `-1` and set 'errno' to one of the values defined below. + +ERRORS +------ +*EINVAL*:: +The endpoint ID supplied doesn't correspond to any active endpoint. +*ENOTSUP*:: +Specified endpoint doesn't support partial shutdown. +*ETERM*:: +The 'context' associated with the specified 'socket' was terminated. +*ENOTSOCK*:: +The provided 'socket' was invalid. + + +EXAMPLE +------- +.Binding socket to an endpoint, then unbinding it +---- +/* Create a socket */ +void *socket = xs_socket (context, XS_PUB); +assert (socket); +/* Bind it to a TCP endpoint */ +int id = xs_bind (socket, "tcp://*:5555"); +assert (id != -1); +/* Unbind the socket from the endpoint */ +rc = xs_shutdown (socket, id); +assert (rc == 0); +---- + + +SEE ALSO +-------- +linkxs:xs_connect[3] +linkxs:xs_bind[3] +linkxs:xs[7] + + +AUTHORS +------- +This manual page was written by Martin Sustrik . diff --git a/doc/xs_tcp.txt b/doc/xs_tcp.txt index b97be08..7437e36 100644 --- a/doc/xs_tcp.txt +++ b/doc/xs_tcp.txt @@ -127,23 +127,23 @@ EXAMPLES ---- /* TCP port 5555 on all available interfaces */ rc = xs_bind(socket, "tcp://*:5555"); -assert (rc == 0); +assert (rc != -1); /* TCP port 5555 on the local loop-back interface on all platforms */ rc = xs_bind(socket, "tcp://127.0.0.1:5555"); -assert (rc == 0); +assert (rc != -1); /* TCP port 5555 on the first Ethernet network interface on Linux */ rc = xs_bind(socket, "tcp://eth0:5555"); -assert (rc == 0); +assert (rc != -1); ---- .Connecting a socket ---- /* Connecting using an IP address */ rc = xs_connect(socket, "tcp://192.168.1.1:5555"); -assert (rc == 0); +assert (rc != -1); /* Connecting using a DNS name */ rc = xs_connect(socket, "tcp://server1:5555"); -assert (rc == 0); +assert (rc != -1); ---- -- cgit v1.2.3