Zsocket (3) Linux Manual Page

zsocket – working with 0MQ sockets (deprecated)

Synopsis

//  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
//  '*', 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't 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't 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);

Description

The zsocket class provides helper functions for 0MQ sockets. It doesn’t wrap the 0MQ socket type, to avoid breaking all libzmq socket-related calls.

Please add @discuss section in ../src/zsocket.c.

Example

From zsocket_test method.

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
//  ('txp://' instead of 'tcp://', 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);

Authors

The czmq manual was written by the authors in the AUTHORS file.

Resources

Main web site: m[blue]m[]

Report bugs to the email <m[blue]zeromq-dev [at] lists.zeromq.orgm[][1]>

Copyright

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.

Notes

1.

zeromq-dev [at] lists.zeromq.org

mailto:zeromq-dev [at] lists.zeromq.org

zsocket (3) Linux Manual Page