'\" t .\" Title: zsocket .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.78.1 .\" Date: 09/14/2016 .\" Manual: CZMQ Manual .\" Source: CZMQ 3.0.2 .\" Language: English .\" .TH "ZSOCKET" "3" "09/14/2016" "CZMQ 3\&.0\&.2" "CZMQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" zsocket \- working with 0MQ sockets (deprecated) .SH "SYNOPSIS" .sp .nf // This port range is defined by IANA for dynamic or private ports // We use this when choosing a port for dynamic binding\&. #define ZSOCKET_DYNFROM 0xc000 #define ZSOCKET_DYNTO 0xffff // Callback function for zero\-copy methods typedef void (zsocket_free_fn) (void *data, void *arg); // Create a new socket within our CZMQ context, replaces zmq_socket\&. // Use this to get automatic management of the socket at shutdown\&. // Note: SUB sockets do not automatically subscribe to everything; you // must set filters explicitly\&. CZMQ_EXPORT void * zsocket_new (zctx_t *self, int type); // Destroy a socket within our CZMQ context, replaces zmq_close\&. CZMQ_EXPORT void zsocket_destroy (zctx_t *ctx, void *self); // Bind a socket to a formatted endpoint\&. If the port is specified as // \*(Aq*\*(Aq, binds to any free port from ZSOCKET_DYNFROM to ZSOCKET_DYNTO // and returns the actual port number used\&. Otherwise asserts that the // bind succeeded with the specified port number\&. Always returns the // port number if successful\&. CZMQ_EXPORT int zsocket_bind (void *self, const char *format, \&.\&.\&.); // Unbind a socket from a formatted endpoint\&. // Returns 0 if OK, \-1 if the endpoint was invalid or the function // isn\*(Aqt supported\&. CZMQ_EXPORT int zsocket_unbind (void *self, const char *format, \&.\&.\&.); // Connect a socket to a formatted endpoint // Returns 0 if OK, \-1 if the endpoint was invalid\&. CZMQ_EXPORT int zsocket_connect (void *self, const char *format, \&.\&.\&.); // Disconnect a socket from a formatted endpoint // Returns 0 if OK, \-1 if the endpoint was invalid or the function // isn\*(Aqt supported\&. CZMQ_EXPORT int zsocket_disconnect (void *self, const char *format, \&.\&.\&.); // Poll for input events on the socket\&. Returns TRUE if there is input // ready on the socket, else FALSE\&. CZMQ_EXPORT bool zsocket_poll (void *self, int msecs); // Returns socket type as printable constant string CZMQ_EXPORT const char * zsocket_type_str (void *self); // Send data over a socket as a single message frame\&. // Accepts these flags: ZFRAME_MORE and ZFRAME_DONTWAIT\&. // Returns \-1 on error, 0 on success CZMQ_EXPORT int zsocket_sendmem (void *self, const void *data, size_t size, int flags); // Send a signal over a socket\&. A signal is a zero\-byte message\&. // Signals are used primarily between threads, over pipe sockets\&. // Returns \-1 if there was an error sending the signal\&. CZMQ_EXPORT int zsocket_signal (void *self); // Wait on a signal\&. Use this to coordinate between threads, over // pipe pairs\&. Returns \-1 on error, 0 on success\&. CZMQ_EXPORT int zsocket_wait (void *self); // Self test of this class CZMQ_EXPORT void zsocket_test (bool verbose); .fi .SH "DESCRIPTION" .sp The zsocket class provides helper functions for 0MQ sockets\&. It doesn\(cqt wrap the 0MQ socket type, to avoid breaking all libzmq socket\-related calls\&. .sp Please add @discuss section in \&.\&./src/zsocket\&.c\&. .SH "EXAMPLE" .PP \fBFrom zsocket_test method\fR. .sp .if n \{\ .RS 4 .\} .nf zctx_t *ctx = zctx_new (); assert (ctx); // Create a detached thread, let it run char *interf = "127\&.0\&.0\&.1"; char *domain = "localhost"; int service = 5560; void *writer = zsocket_new (ctx, ZMQ_PUSH); assert (writer); void *reader = zsocket_new (ctx, ZMQ_PULL); assert (reader); assert (streq (zsocket_type_str (writer), "PUSH")); assert (streq (zsocket_type_str (reader), "PULL")); int rc = zsocket_bind (writer, "tcp://%s:%d", interf, service); assert (rc == service); #if (ZMQ_VERSION >= ZMQ_MAKE_VERSION (3, 2, 0)) // Check unbind rc = zsocket_unbind (writer, "tcp://%s:%d", interf, service); assert (rc == 0); // In some cases and especially when running under Valgrind, doing // a bind immediately after an unbind causes an EADDRINUSE error\&. // Even a short sleep allows the OS to release the port for reuse\&. zclock_sleep (100); // Bind again rc = zsocket_bind (writer, "tcp://%s:%d", interf, service); assert (rc == service); #endif rc = zsocket_connect (reader, "tcp://%s:%d", domain, service); assert (rc == 0); zstr_send (writer, "HELLO"); char *message = zstr_recv (reader); assert (message); assert (streq (message, "HELLO")); free (message); // Test binding to ports int port = zsocket_bind (writer, "tcp://%s:*", interf); assert (port >= ZSOCKET_DYNFROM && port <= ZSOCKET_DYNTO); assert (zsocket_poll (writer, 100) == false); // Test error state when connecting to an invalid socket type // (\*(Aqtxp://\*(Aq instead of \*(Aqtcp://\*(Aq, typo intentional) rc = zsocket_connect (reader, "txp://%s:%d", domain, service); assert (rc == \-1); // Test sending frames to socket rc = zsocket_sendmem (writer, "ABC", 3, ZFRAME_MORE); assert (rc == 0); rc = zsocket_sendmem (writer, "DEFG", 4, 0); assert (rc == 0); zframe_t *frame = zframe_recv (reader); assert (frame); assert (zframe_streq (frame, "ABC")); assert (zframe_more (frame)); zframe_destroy (&frame); frame = zframe_recv (reader); assert (frame); assert (zframe_streq (frame, "DEFG")); assert (!zframe_more (frame)); zframe_destroy (&frame); rc = zsocket_signal (writer); assert (rc == 0); rc = zsocket_wait (reader); assert (rc == 0); zsocket_destroy (ctx, reader); zsocket_destroy (ctx, writer); zctx_destroy (&ctx); .fi .if n \{\ .RE .\} .sp .SH "AUTHORS" .sp The czmq manual was written by the authors in the AUTHORS file\&. .SH "RESOURCES" .sp Main web site: \m[blue]\fB\%\fR\m[] .sp Report bugs to the email <\m[blue]\fBzeromq\-dev@lists\&.zeromq\&.org\fR\m[]\&\s-2\u[1]\d\s+2> .SH "COPYRIGHT" .sp Copyright (c) 1991\-2012 iMatix Corporation \-\- http://www\&.imatix\&.com Copyright other contributors as noted in the AUTHORS file\&. This file is part of CZMQ, the high\-level C binding for 0MQ: http://czmq\&.zeromq\&.org This Source Code Form is subject to the terms of the Mozilla Public License, v\&. 2\&.0\&. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla\&.org/MPL/2\&.0/\&. LICENSE included with the czmq distribution\&. .SH "NOTES" .IP " 1." 4 zeromq-dev@lists.zeromq.org .RS 4 \%mailto:zeromq-dev@lists.zeromq.org .RE