openpilot_comma/external/zmq/share/man/man3/zsocket.3

'\" t
.\"     Title: zsocket
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      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