jyoung/external/zmq/share/man/man7/czmq.7

'\" t
.\"     Title: czmq
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 12/31/2016
.\"    Manual: CZMQ Manual
.\"    Source: CZMQ 4.0.2
.\"  Language: English
.\"
.TH "CZMQ" "7" "12/31/2016" "CZMQ 4\&.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"
czmq \- high\-level C binding for ZeroMQ
.SH "SYNOPSIS"
.sp
.nf
#include <czmq\&.h>

cc [\*(Aqflags\*(Aq] \*(Aqfiles\*(Aq \-lzmq \-lczmq [\*(Aqlibraries\*(Aq]
.fi
.SH "DESCRIPTION"
.SS "Classes"
.sp
These classes provide the main socket and message API:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzsock\fR(3)
\- working with ZeroMQ sockets (high\-level)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzstr\fR(3)
\- sending and receiving strings
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzmsg\fR(3)
\- working with multipart messages
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzframe\fR(3)
\- working with single message frames
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzactor\fR(3)
\- Actor class (socket + thread)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzloop\fR(3)
\- event\-driven reactor
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzpoller\fR(3)
\- trivial socket poller class
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzproxy\fR(3)
\- proxy actor (like zmq_proxy_steerable)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzmonitor\fR(3)
\- monitor events on ZeroMQ sockets
.RE
.sp
These classes support authentication and encryption:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzauth\fR(3)
\- authentication actor for ZeroMQ servers
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzcert\fR(3)
\- work with CURVE security certificates
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzcertstore\fR(3)
\- work with CURVE security certificate stores
.RE
.sp
These classes provide generic containers:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzhash\fR(3)
\- simple generic hash container
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzhashx\fR(3)
\- extended generic hash container
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzlist\fR(3)
\- simple generic list container
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzlistx\fR(3)
\- extended generic list container
.RE
.sp
These classes wrap\-up non\-portable functionality:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzbeacon\fR(3)
\- LAN discovery and presence
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzclock\fR(3)
\- millisecond clocks and delays
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzdir\fR(3)
\- work with file\-system directories
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzdir_patch\fR(3)
\- work with directory differences
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzfile\fR(3)
\- work with file\-system files
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzsys\fR(3)
\- system\-level methods
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzuuid\fR(3)
\- UUID support class
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBziflist\fR(3)
\- list available network interfaces
.RE
.sp
And these utility classes add value:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzchunk\fR(3)
\- work with memory chunks
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzconfig\fR(3)
\- work with textual config files
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzrex\fR(3)
\- work with regular expressions
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzgossip\fR(3)
\- decentralized configuration management
.RE
.sp
These classes are deprecated:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzctx\fR(3)
\- working with ZeroMQ contexts
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzsocket\fR(3)
\- working with ZeroMQ sockets (low\-level)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzsockopt\fR(3)
\- get/set ZeroMQ socket options
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzthread\fR(3)
\- working with system threads
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzauth_v2\fR(3)
\- authentication for ZeroMQ servers
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzbeacon_v2\fR(3)
\- LAN discovery and presence
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzmonitor_v2\fR(3)
\- socket event monitor
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBzproxy_v2\fR(3)
\- zmq_proxy wrapper
.RE
.SS "Scope and Goals"
.sp
CZMQ has these goals:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
To wrap the \(/OMQ core API in semantics that are natural and lead to shorter, more readable applications\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
To hide the differences between versions of \(/OMQ\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
To provide a space for development of more sophisticated API semantics\&.
.RE
.SS "Ownership and License"
.sp
CZMQ is maintained by the ZeroMQ community at github\&.com/zeromq\&. Its other authors and contributors are listed in the AUTHORS file\&.
.sp
The contributors are listed in AUTHORS\&. This project uses the MPL v2 license, see LICENSE\&.
.SS "Contributing"
.sp
To submit an issue use the issue tracker at \m[blue]\fBhttp://github\&.com/zeromq/czmq/issues\fR\m[]\&. All discussion happens on the zeromq\-dev list or #zeromq IRC channel at irc\&.freenode\&.net\&.
.sp
The proper way to submit patches is to clone this repository, make your changes, and use git to create a patch or a pull request\&. See \m[blue]\fBhttp://www\&.zeromq\&.org/docs:contributing\fR\m[]\&. All contributors are listed in AUTHORS\&.
.sp
All classes are maintained by a single person, who is the responsible editor for that class and who is named in the header as such\&. This is usually the originator of the class\&. When several people collaborate on a class, one single person is always the lead maintainer and the one to blame when it breaks\&.
.sp
The general rule is, if you contribute code to CZMQ you must be willing to maintain it as long as there are users of it\&. Code with no active maintainer will in general be deprecated and/or removed\&.
.SH "USING CZMQ"
.SS "Building and Installing"
.sp
CZMQ uses autotools for packaging\&. To build from git (all example commands are for Linux):
.sp
.if n \{\
.RS 4
.\}
.nf
    git clone git://github\&.com/zeromq/czmq\&.git
    cd czmq
    sh autogen\&.sh
    \&./configure
    make all
    sudo make install
    sudo ldconfig
.fi
.if n \{\
.RE
.\}
.sp
You will need the pkg\-config, libtool, and autoreconf packages\&. Set the LD_LIBRARY_PATH to /usr/local/libs unless you install elsewhere\&.
.sp
After building, you can run the CZMQ selftests:
.sp
.if n \{\
.RS 4
.\}
.nf
    cd src
    \&./czmq_selftest
.fi
.if n \{\
.RE
.\}
.SS "Linking with an Application"
.sp
Include czmq\&.h in your application and link with CZMQ\&. Here is a typical gcc link command:
.sp
.if n \{\
.RS 4
.\}
.nf
    gcc \-lczmq \-lzmq myapp\&.c \-o myapp
.fi
.if n \{\
.RE
.\}
.sp
You should read czmq\&.h\&. This file includes zmq\&.h and the system header files that typical \(/OMQ applications will need\&. The provided \fIc\fR shell script lets you write simple portable build scripts:
.sp
.if n \{\
.RS 4
.\}
.nf
    c \-lczmq \-lzmq \-l myapp
.fi
.if n \{\
.RE
.\}
.SS "The Class Model"
.sp
CZMQ consists of classes, each class consisting of a \&.h and a \&.c\&. Classes may depend on other classes\&.
.sp
czmq\&.h includes all classes header files, all the time\&. For the user, CZMQ forms one single package\&. All classes start by including czmq\&.h\&. All applications that use CZMQ start by including czmq\&.h\&. czmq\&.h also defines a limited number of small, useful macros and typedefs that have proven useful for writing clearer C code\&.
.sp
All classes (with some exceptions) are based on a flat C class system and follow these rules (where \fIzclass\fR is the class name):
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Class typedef:
zclass_t
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Constructor:
zclass_new
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Destructor:
zclass_destroy
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Property methods:
zclass_property_set,
zclass_property
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Class structures are private (defined in the \&.c source but not the \&.h)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Properties are accessed only via methods named as described above\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
In the class source code the object is always called
self\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The constructor may take arbitrary arguments, and returns NULL on failure, or a new object\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The destructor takes a pointer to an object reference and nullifies it\&.
.RE
.sp
Return values for methods are:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
For methods that return an object reference, either the reference, or NULL on failure\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
For methods that signal success/failure, a return value of 0 means success, \-1 failure\&.
.RE
.sp
Private/static functions in a class are named s_functionname and are not exported via the header file\&.
.sp
All classes (with some exceptions) have a test method called zclass_test\&.
.SH "DESIGN IDEOLOGY"
.SS "The Problem with C"
.sp
C has the significant advantage of being a small language that, if we take a little care with formatting and naming, can be easily interchanged between developers\&. Every C developer will use much the same 90% of the language\&. Larger languages like C++ provide powerful abstractions like STL containers but at the cost of interchange\&.
.sp
The huge problem with C is that any realistic application needs packages of functionality to bring the language up to the levels we expect for the 21st century\&. Much can be done by using external libraries but every additional library is a dependency that makes the resulting applications harder to build and port\&. While C itself is a highly portable language (and can be made more so by careful use of the preprocessor), most C libraries consider themselves part of the operating system, and as such do not attempt to be portable\&.
.sp
The answer to this, as we learned from building enterprise\-level C applications at iMatix from 1995\-2005, is to create our own fully portable, high\-quality libraries of pre\-packaged functionality, in C\&. Doing this right solves both the requirements of richness of the language, and of portability of the final applications\&.
.SS "A Simple Class Model"
.sp
C has no standard API style\&. It is one thing to write a useful component, but something else to provide an API that is consistent and obvious across many components\&. We learned from building OpenAMQ (\m[blue]\fBhttp://www\&.openamq\&.org\fR\m[]), a messaging client and server of 0\&.5M LoC, that a consistent model for extending C makes life for the application developer much easier\&.
.sp
The general model is that of a class (the source package) that provides objects (in fact C structures)\&. The application creates objects and then works with them\&. When done, the application destroys the object\&. In C, we tend to use the same name for the object as the class, when we can, and it looks like this (to take a fictitious CZMQ class):
.sp
.if n \{\
.RS 4
.\}
.nf
    zregexp_t *regexp = zregexp_new (regexp_string);
    if (!regexp)
        printf ("E: invalid regular expression: %s\en", regexp_string);
    else
    if (zregexp_match (regexp, input_buffer))
        printf ("I: successful match for %s\en", input buffer);
    zregexp_destroy (&amp;regexp);
.fi
.if n \{\
.RE
.\}
.sp
As far as the C program is concerned, the object is a reference to a structure (not a void pointer)\&. We pass the object reference to all methods, since this is still C\&. We could do weird stuff like put method addresses into the structure so that we can emulate a C++ syntax but it\(cqs not worthwhile\&. The goal is not to emulate an OO system, it\(cqs simply to gain consistency\&. The constructor returns an object reference, or NULL if it fails\&. The destructor nullifies the class pointer, and is idempotent\&.
.sp
What we aim at here is the simplest possible consistent syntax\&.
.sp
No model is fully consistent, and classes can define their own rules if it helps make a better result\&. For example:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Some classes may not be opaque\&. For example, we have cases of generated serialization classes that encode and decode structures to/from binary buffers\&. It feels clumsy to have to use methods to access the properties of these classes\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
While every class has a new method that is the formal constructor, some methods may also act as constructors\&. For example, a "dup" method might take one object and return a second object\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
While every class has a destroy method that is the formal destructor, some methods may also act as destructors\&. For example, a method that sends an object may also destroy the object (so that ownership of any buffers can passed to background threads)\&. Such methods take the same "pointer to a reference" argument as the destroy method\&.
.RE
.SS "Naming Style"
.sp
CZMQ aims for short, consistent names, following the theory that names we use most often should be shortest\&. Classes get one\-word names, unless they are part of a family of classes in which case they may be two words, the first being the family name\&. Methods, similarly, get one\-word names and we aim for consistency across classes (so a method that does something semantically similar in two classes will get the same name in both)\&. So the canonical name for any method is:
.sp
.if n \{\
.RS 4
.\}
.nf
    zclassname_methodname
.fi
.if n \{\
.RE
.\}
.sp
And the reader can easily parse this without needing special syntax to separate the class name from the method name\&.
.SS "Containers"
.sp
After a long experiment with containers, we\(cqve decided that we need exactly two containers:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A singly\-linked list\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A hash table using text keys\&.
.RE
.sp
These are zlist and zhash, respectively\&. Both store void pointers, with no attempt to manage the details of contained objects\&. You can use these containers to create lists of lists, hashes of lists, hashes of hashes, etc\&.
.sp
We assume that at some point we\(cqll need to switch to a doubly\-linked list\&.
.SS "Portability"
.sp
Creating a portable C application can be rewarding in terms of maintaining a single code base across many platforms, and keeping (expensive) system\-specific knowledge separate from application developers\&. In most projects (like \(/OMQ core), there is no portability layer and application code does conditional compilation for all mixes of platforms\&. This leads to quite messy code\&.
.sp
czmq acts as a portability layer, similar to but thinner than libraries like the [Apache Portable Runtime](\m[blue]\fBhttp://apr\&.apache\&.org\fR\m[]) (APR)\&.
.sp
These are the places a C application is subject to arbitrary system differences:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Different compilers may offer slightly different variants of the C language, often lacking specific types or using neat non\-portable names\&. Windows is a big culprit here\&. We solve this by
\fIpatching\fR
the language in czmq_prelude\&.h, e\&.g\&. defining int64_t on Windows\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
System header files are inconsistent, i\&.e\&. you need to include different files depending on the OS type and version\&. We solve this by pulling in all necessary header files in czmq_prelude\&.h\&. This is a proven brute\-force approach that increases recompilation times but eliminates a major source of pain\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
System libraries are inconsistent, i\&.e\&. you need to link with different libraries depending on the OS type and version\&. We solve this with an external compilation tool,
\fIC\fR, which detects the OS type and version (at runtime) and builds the necessary link commands\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
System functions are inconsistent, i\&.e\&. you need to call different functions depending, again, on OS type and version\&. We solve this by building small abstract classes that handle specific areas of functionality, and doing conditional compilation in these\&.
.RE
.sp
An example of the last:
.sp
.if n \{\
.RS 4
.\}
.nf
    #if (defined (__UNIX__))
        pid = GetCurrentProcessId();
    #elif (defined (__WINDOWS__))
        pid = getpid ();
    #else
        pid = 0;
    #endif
.fi
.if n \{\
.RE
.\}
.sp
CZMQ uses the GNU autotools system, so non\-portable code can use the macros this defines\&. It can also use macros defined by the czmq_prelude\&.h header file\&.
.SS "Technical Aspects"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBThread safety\fR: the use of opaque structures is thread safe, though \(/OMQ applications should not share state between threads in any case\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBName spaces\fR: we prefix class names with
z, which ensures that all exported functions are globally safe\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBLibrary versioning\fR: we don\(cqt make any attempt to version the library at this stage\&. Classes are in our experience highly stable once they are built and tested, the only changes typically being added methods\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBPerformance\fR: for critical path processing, you may want to avoid creating and destroying classes\&. However on modern Linux systems the heap allocator is very fast\&. Individual classes can choose whether or not to nullify their data on allocation\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBSelf\-testing\fR: every class has a
selftest
method that runs through the methods of the class\&. In theory, calling all selftest functions of all classes does a full unit test of the library\&. The
czmq_selftest
application does this\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBMemory management\fR: CZMQ classes do not use any special memory management techiques to detect leaks\&. We\(cqve done this in the past but it makes the code relatively complex\&. Instead, we do memory leak testing using tools like valgrind\&.
.RE
.SH "UNDER THE HOOD"
.SS "Adding a New Class"
.sp
If you define a new CZMQ class myclass you need to:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Write the
zmyclass\&.c
and
zmyclass\&.h
source files, in
src
and
include
respectively\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Add`#include <zmyclass\&.h>` to
include/czmq\&.h\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Add the myclass header and test call to
src/czmq_selftest\&.c\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Add a reference documentation to
\fIdoc/zmyclass\&.txt\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Add myclass to \*(Aqsrc/Makefile\&.am` and
doc/Makefile\&.am\&.
.RE
.sp
The bin/newclass\&.sh shell script will automate these steps for you\&.
.SS "Coding Style"
.sp
In general the zctx class defines the style for the whole library\&. The overriding rules for coding style are consistency, clarity, and ease of maintenance\&. We use the C99 standard for syntax including principally:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The // comment style\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Variables definitions placed in or before the code that uses them\&.
.RE
.sp
So while ANSI C code might say:
.sp
.if n \{\
.RS 4
.\}
.nf
    zblob_t *file_buffer;       /*  Buffer for our file */
    \&.\&.\&. (100 lines of code)
    file_buffer = zblob_new ();
    \&.\&.\&.
.fi
.if n \{\
.RE
.\}
.sp
The style in CZMQ would be:
.sp
.if n \{\
.RS 4
.\}
.nf
    zblob_t *file_buffer = zblob_new ();
.fi
.if n \{\
.RE
.\}
.SS "Assertions"
.sp
We use assertions heavily to catch bad argument values\&. The CZMQ classes do not attempt to validate arguments and report errors; bad arguments are treated as fatal application programming errors\&.
.sp
We also use assertions heavily on calls to system functions that are never supposed to fail, where failure is to be treated as a fatal non\-recoverable error (e\&.g\&. running out of memory)\&.
.sp
Assertion code should always take this form:
.sp
.if n \{\
.RS 4
.\}
.nf
    int rc = some_function (arguments);
    assert (rc == 0);
.fi
.if n \{\
.RE
.\}
.sp
Rather than the side\-effect form:
.sp
.if n \{\
.RS 4
.\}
.nf
    assert (some_function (arguments) == 0);
.fi
.if n \{\
.RE
.\}
.sp
Since assertions may be removed by an optimizing compiler\&.
.SS "Documentation"
.sp
Man pages are generated from the class header and source files via the doc/mkman tool, and similar functionality in the gitdown tool (\m[blue]\fBhttp://github\&.com/imatix/gitdown\fR\m[])\&. The header file for a class must wrap its interface as follows (example is from include/zclock\&.h):
.sp
.if n \{\
.RS 4
.\}
.nf
    //  @interface
    //  Sleep for a number of milliseconds
    void
        zclock_sleep (int msecs);

    //  Return current system clock as milliseconds
    int64_t
        zclock_time (void);

    //  Self test of this class
    int
        zclock_test (Bool verbose);
    //  @end
.fi
.if n \{\
.RE
.\}
.sp
The source file for a class must provide documentation as follows:
.sp
.if n \{\
.RS 4
.\}
.nf
    /*
    @header
    \&.\&.\&.short explanation of class\&.\&.\&.
    @discuss
    \&.\&.\&.longer discussion of how it works\&.\&.\&.
    @end
    */
.fi
.if n \{\
.RE
.\}
.sp
The source file for a class then provides the self test example as follows:
.sp
.if n \{\
.RS 4
.\}
.nf
    //  @selftest
    int64_t start = zclock_time ();
    zclock_sleep (10);
    assert ((zclock_time () \- start) >= 10);
    //  @end
.fi
.if n \{\
.RE
.\}
.sp
The template for man pages is in doc/mkman\&.
.SS "Development"
.sp
CZMQ is developed through a test\-driven process that guarantees no memory violations or leaks in the code:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Modify a class or method\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Update the test method for that class\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Run the
\fIselftest\fR
script, which uses the Valgrind memcheck tool\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Repeat until perfect\&.
.RE
.SS "Porting CZMQ"
.sp
When you try CZMQ on an OS that it\(cqs not been used on (ever, or for a while), you will hit code that does not compile\&. In some cases the patches are trivial, in other cases (usually when porting to Windows), the work needed to build equivalent functionality may be quite heavy\&. In any case, the benefit is that once ported, the functionality is available to all applications\&.
.sp
Before attempting to patch code for portability, please read the czmq_prelude\&.h header file\&. There are several typical types of changes you may need to make to get functionality working on a specific operating system:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Defining typedefs which are missing on that specific compiler: do this in czmq_prelude\&.h\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Defining macros that rename exotic library functions to more conventional names: do this in czmq_prelude\&.h\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Reimplementing specific methods to use a non\-standard API: this is typically needed on Windows\&. Do this in the relevant class, using #ifdefs to properly differentiate code for different platforms\&.
.RE
.sp
The canonical \fIstandard operating system\fR for all CZMQ code is Linux, gcc, POSIX\&.
.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) the 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