1CZMQ(7) CZMQ Manual CZMQ(7)
2
6 czmq - high-level C binding for ZeroMQ
7
9 #include <czmq.h>
10 cc ['flags'] 'files' -lzmq -lczmq ['libraries']
12
14 Classes
15 These classes provide the main socket and message API:
16 · zsock(3) - working with ZeroMQ sockets (high-level)
18 · zstr(3) - sending and receiving strings
20 · zmsg(3) - working with multipart messages
22 · zframe(3) - working with single message frames
24 · zactor(3) - Actor class (socket + thread)
26 · zloop(3) - event-driven reactor
28 · zpoller(3) - trivial socket poller class
30 · zproxy(3) - proxy actor (like zmq_proxy_steerable)
32 · zmonitor(3) - monitor events on ZeroMQ sockets
34 These classes support authentication and encryption:
36 · zauth(3) - authentication actor for ZeroMQ servers
38 · zcert(3) - work with CURVE security certificates
40 · zcertstore(3) - work with CURVE security certificate stores
42 These classes provide generic containers:
44 · zhash(3) - simple generic hash container
46 · zhashx(3) - extended generic hash container
48 · zlist(3) - simple generic list container
50 · zlistx(3) - extended generic list container
52 These classes wrap-up non-portable functionality:
54 · zbeacon(3) - LAN discovery and presence
56 · zclock(3) - millisecond clocks and delays
58 · zdir(3) - work with file-system directories
60 · zdir_patch(3) - work with directory differences
62 · zfile(3) - work with file-system files
64 · zsys(3) - system-level methods
66 · zuuid(3) - UUID support class
68 · ziflist(3) - list available network interfaces
70 And these utility classes add value:
72 · zchunk(3) - work with memory chunks
74 · zconfig(3) - work with textual config files
76 · zrex(3) - work with regular expressions
78 · zgossip(3) - decentralized configuration management
80 These classes are deprecated:
82 · zctx(3) - working with ZeroMQ contexts
84 · zsocket(3) - working with ZeroMQ sockets (low-level)
86 · zsockopt(3) - get/set ZeroMQ socket options
88 · zthread(3) - working with system threads
90 · zauth_v2(3) - authentication for ZeroMQ servers
92 · zbeacon_v2(3) - LAN discovery and presence
94 · zmonitor_v2(3) - socket event monitor
96 · zproxy_v2(3) - zmq_proxy wrapper
98 Scope and Goals
100 CZMQ has these goals:
101 · To wrap the ØMQ core API in semantics that are natural and lead to
103 shorter, more readable applications.
104 · To hide the differences between versions of ØMQ.
106 · To provide a space for development of more sophisticated API
108 semantics.
109 Ownership and License
111 CZMQ is maintained by the ZeroMQ community at github.com/zeromq. Its
112 other authors and contributors are listed in the AUTHORS file.
113 The contributors are listed in AUTHORS. This project uses the MPL v2
115 license, see LICENSE.
116 Contributing
118 To submit an issue use the issue tracker at
119 http://github.com/zeromq/czmq/issues. All discussion happens on the
120 zeromq-dev list or #zeromq IRC channel at irc.freenode.net.
121 The proper way to submit patches is to clone this repository, make your
123 changes, and use git to create a patch or a pull request. See
124 http://www.zeromq.org/docs:contributing. All contributors are listed in
125 AUTHORS.
126 All classes are maintained by a single person, who is the responsible
128 editor for that class and who is named in the header as such. This is
129 usually the originator of the class. When several people collaborate on
130 a class, one single person is always the lead maintainer and the one to
131 blame when it breaks.
132 The general rule is, if you contribute code to CZMQ you must be willing
134 to maintain it as long as there are users of it. Code with no active
135 maintainer will in general be deprecated and/or removed.
136
138 Building and Installing
139 CZMQ uses autotools for packaging. To build from git (all example
140 commands are for Linux):
141 git clone git://github.com/zeromq/czmq.git
143 cd czmq
144 sh autogen.sh
145 ./configure
146 make all
147 sudo make install
148 sudo ldconfig
149 You will need the pkg-config, libtool, and autoreconf packages. Set the
151 LD_LIBRARY_PATH to /usr/local/libs unless you install elsewhere.
152 After building, you can run the CZMQ selftests:
154 cd src
156 ./czmq_selftest
157 Linking with an Application
159 Include czmq.h in your application and link with CZMQ. Here is a
160 typical gcc link command:
161 gcc -lczmq -lzmq myapp.c -o myapp
163 You should read czmq.h. This file includes zmq.h and the system header
165 files that typical ØMQ applications will need. The provided c shell
166 script lets you write simple portable build scripts:
167 c -lczmq -lzmq -l myapp
169 The Class Model
171 CZMQ consists of classes, each class consisting of a .h and a .c.
172 Classes may depend on other classes.
173 czmq.h includes all classes header files, all the time. For the user,
175 CZMQ forms one single package. All classes start by including czmq.h.
176 All applications that use CZMQ start by including czmq.h. czmq.h also
177 defines a limited number of small, useful macros and typedefs that have
178 proven useful for writing clearer C code.
179 All classes (with some exceptions) are based on a flat C class system
181 and follow these rules (where zclass is the class name):
182 · Class typedef: zclass_t
184 · Constructor: zclass_new
186 · Destructor: zclass_destroy
188 · Property methods: zclass_property_set, zclass_property
190 · Class structures are private (defined in the .c source but not the
192 .h)
193 · Properties are accessed only via methods named as described above.
195 · In the class source code the object is always called self.
197 · The constructor may take arbitrary arguments, and returns NULL on
199 failure, or a new object.
200 · The destructor takes a pointer to an object reference and nullifies
202 it.
203 Return values for methods are:
205 · For methods that return an object reference, either the reference,
207 or NULL on failure.
208 · For methods that signal success/failure, a return value of 0 means
210 success, -1 failure.
211 Private/static functions in a class are named s_functionname and are
213 not exported via the header file.
214 All classes (with some exceptions) have a test method called
216 zclass_test.
217
219 The Problem with C
220 C has the significant advantage of being a small language that, if we
221 take a little care with formatting and naming, can be easily
222 interchanged between developers. Every C developer will use much the
223 same 90% of the language. Larger languages like C++ provide powerful
224 abstractions like STL containers but at the cost of interchange.
225 The huge problem with C is that any realistic application needs
227 packages of functionality to bring the language up to the levels we
228 expect for the 21st century. Much can be done by using external
229 libraries but every additional library is a dependency that makes the
230 resulting applications harder to build and port. While C itself is a
231 highly portable language (and can be made more so by careful use of the
232 preprocessor), most C libraries consider themselves part of the
233 operating system, and as such do not attempt to be portable.
234 The answer to this, as we learned from building enterprise-level C
236 applications at iMatix from 1995-2005, is to create our own fully
237 portable, high-quality libraries of pre-packaged functionality, in C.
238 Doing this right solves both the requirements of richness of the
239 language, and of portability of the final applications.
240 A Simple Class Model
242 C has no standard API style. It is one thing to write a useful
243 component, but something else to provide an API that is consistent and
244 obvious across many components. We learned from building OpenAMQ
245 (http://www.openamq.org), a messaging client and server of 0.5M LoC,
246 that a consistent model for extending C makes life for the application
247 developer much easier.
248 The general model is that of a class (the source package) that provides
250 objects (in fact C structures). The application creates objects and
251 then works with them. When done, the application destroys the object.
252 In C, we tend to use the same name for the object as the class, when we
253 can, and it looks like this (to take a fictitious CZMQ class):
254 zregexp_t *regexp = zregexp_new (regexp_string);
256 if (!regexp)
257 printf ("E: invalid regular expression: %s\n", regexp_string);
258 else
259 if (zregexp_match (regexp, input_buffer))
260 printf ("I: successful match for %s\n", input buffer);
261 zregexp_destroy (&regexp);
262 As far as the C program is concerned, the object is a reference to a
264 structure (not a void pointer). We pass the object reference to all
265 methods, since this is still C. We could do weird stuff like put method
266 addresses into the structure so that we can emulate a C++ syntax but
267 it’s not worthwhile. The goal is not to emulate an OO system, it’s
268 simply to gain consistency. The constructor returns an object
269 reference, or NULL if it fails. The destructor nullifies the class
270 pointer, and is idempotent.
271 What we aim at here is the simplest possible consistent syntax.
273 No model is fully consistent, and classes can define their own rules if
275 it helps make a better result. For example:
276 · Some classes may not be opaque. For example, we have cases of
278 generated serialization classes that encode and decode structures
279 to/from binary buffers. It feels clumsy to have to use methods to
280 access the properties of these classes.
281 · While every class has a new method that is the formal constructor,
283 some methods may also act as constructors. For example, a "dup"
284 method might take one object and return a second object.
285 · While every class has a destroy method that is the formal
287 destructor, some methods may also act as destructors. For example,
288 a method that sends an object may also destroy the object (so that
289 ownership of any buffers can passed to background threads). Such
290 methods take the same "pointer to a reference" argument as the
291 destroy method.
292 Naming Style
294 CZMQ aims for short, consistent names, following the theory that names
295 we use most often should be shortest. Classes get one-word names,
296 unless they are part of a family of classes in which case they may be
297 two words, the first being the family name. Methods, similarly, get
298 one-word names and we aim for consistency across classes (so a method
299 that does something semantically similar in two classes will get the
300 same name in both). So the canonical name for any method is:
301 zclassname_methodname
303 And the reader can easily parse this without needing special syntax to
305 separate the class name from the method name.
306 Containers
308 After a long experiment with containers, we’ve decided that we need
309 exactly two containers:
310 · A singly-linked list.
312 · A hash table using text keys.
314 These are zlist and zhash, respectively. Both store void pointers, with
316 no attempt to manage the details of contained objects. You can use
317 these containers to create lists of lists, hashes of lists, hashes of
318 hashes, etc.
319 We assume that at some point we’ll need to switch to a doubly-linked
321 list.
322 Portability
324 Creating a portable C application can be rewarding in terms of
325 maintaining a single code base across many platforms, and keeping
326 (expensive) system-specific knowledge separate from application
327 developers. In most projects (like ØMQ core), there is no portability
328 layer and application code does conditional compilation for all mixes
329 of platforms. This leads to quite messy code.
330 czmq acts as a portability layer, similar to but thinner than libraries
332 like the [Apache Portable Runtime](http://apr.apache.org) (APR).
333 These are the places a C application is subject to arbitrary system
335 differences:
336 · Different compilers may offer slightly different variants of the C
338 language, often lacking specific types or using neat non-portable
339 names. Windows is a big culprit here. We solve this by patching the
340 language in czmq_prelude.h, e.g. defining int64_t on Windows.
341 · System header files are inconsistent, i.e. you need to include
343 different files depending on the OS type and version. We solve this
344 by pulling in all necessary header files in czmq_prelude.h. This is
345 a proven brute-force approach that increases recompilation times
346 but eliminates a major source of pain.
347 · System libraries are inconsistent, i.e. you need to link with
349 different libraries depending on the OS type and version. We solve
350 this with an external compilation tool, C, which detects the OS
351 type and version (at runtime) and builds the necessary link
352 commands.
353 · System functions are inconsistent, i.e. you need to call different
355 functions depending, again, on OS type and version. We solve this
356 by building small abstract classes that handle specific areas of
357 functionality, and doing conditional compilation in these.
358 An example of the last:
360 #if (defined (__UNIX__))
362 pid = GetCurrentProcessId();
363 #elif (defined (__WINDOWS__))
364 pid = getpid ();
365 #else
366 pid = 0;
367 #endif
368 CZMQ uses the GNU autotools system, so non-portable code can use the
370 macros this defines. It can also use macros defined by the
371 czmq_prelude.h header file.
372 Technical Aspects
374 · Thread safety: the use of opaque structures is thread safe, though
375 ØMQ applications should not share state between threads in any
376 case.
377 · Name spaces: we prefix class names with z, which ensures that all
379 exported functions are globally safe.
380 · Library versioning: we don’t make any attempt to version the
382 library at this stage. Classes are in our experience highly stable
383 once they are built and tested, the only changes typically being
384 added methods.
385 · Performance: for critical path processing, you may want to avoid
387 creating and destroying classes. However on modern Linux systems
388 the heap allocator is very fast. Individual classes can choose
389 whether or not to nullify their data on allocation.
390 · Self-testing: every class has a selftest method that runs through
392 the methods of the class. In theory, calling all selftest functions
393 of all classes does a full unit test of the library. The
394 czmq_selftest application does this.
395 · Memory management: CZMQ classes do not use any special memory
397 management techiques to detect leaks. We’ve done this in the past
398 but it makes the code relatively complex. Instead, we do memory
399 leak testing using tools like valgrind.
400
402 Adding a New Class
403 If you define a new CZMQ class myclass you need to:
404 · Write the zmyclass.c and zmyclass.h source files, in src and
406 include respectively.
407 · Add`#include <zmyclass.h>` to include/czmq.h.
409 · Add the myclass header and test call to src/czmq_selftest.c.
411 · Add a reference documentation to doc/zmyclass.txt.
413 · Add myclass to 'src/Makefile.am` and doc/Makefile.am.
415 The bin/newclass.sh shell script will automate these steps for you.
417 Coding Style
419 In general the zctx class defines the style for the whole library. The
420 overriding rules for coding style are consistency, clarity, and ease of
421 maintenance. We use the C99 standard for syntax including principally:
422 · The // comment style.
424 · Variables definitions placed in or before the code that uses them.
426 So while ANSI C code might say:
428 zblob_t *file_buffer; /* Buffer for our file */
430 ... (100 lines of code)
431 file_buffer = zblob_new ();
432 ...
433 The style in CZMQ would be:
435 zblob_t *file_buffer = zblob_new ();
437 Assertions
439 We use assertions heavily to catch bad argument values. The CZMQ
440 classes do not attempt to validate arguments and report errors; bad
441 arguments are treated as fatal application programming errors.
442 We also use assertions heavily on calls to system functions that are
444 never supposed to fail, where failure is to be treated as a fatal
445 non-recoverable error (e.g. running out of memory).
446 Assertion code should always take this form:
448 int rc = some_function (arguments);
450 assert (rc == 0);
451 Rather than the side-effect form:
453 assert (some_function (arguments) == 0);
455 Since assertions may be removed by an optimizing compiler.
457 Documentation
459 Man pages are generated from the class header and source files via the
460 doc/mkman tool, and similar functionality in the gitdown tool
461 (http://github.com/imatix/gitdown). The header file for a class must
462 wrap its interface as follows (example is from include/zclock.h):
463 // @interface
465 // Sleep for a number of milliseconds
466 void
467 zclock_sleep (int msecs);
468 // Return current system clock as milliseconds
470 int64_t
471 zclock_time (void);
472 // Self test of this class
474 int
475 zclock_test (Bool verbose);
476 // @end
477 The source file for a class must provide documentation as follows:
479 /*
481 @header
482 ...short explanation of class...
483 @discuss
484 ...longer discussion of how it works...
485 @end
486 */
487 The source file for a class then provides the self test example as
489 follows:
490 // @selftest
492 int64_t start = zclock_time ();
493 zclock_sleep (10);
494 assert ((zclock_time () - start) >= 10);
495 // @end
496 The template for man pages is in doc/mkman.
498 Development
500 CZMQ is developed through a test-driven process that guarantees no
501 memory violations or leaks in the code:
502 · Modify a class or method.
504 · Update the test method for that class.
506 · Run the selftest script, which uses the Valgrind memcheck tool.
508 · Repeat until perfect.
510 Porting CZMQ
512 When you try CZMQ on an OS that it’s not been used on (ever, or for a
513 while), you will hit code that does not compile. In some cases the
514 patches are trivial, in other cases (usually when porting to Windows),
515 the work needed to build equivalent functionality may be quite heavy.
516 In any case, the benefit is that once ported, the functionality is
517 available to all applications.
518 Before attempting to patch code for portability, please read the
520 czmq_prelude.h header file. There are several typical types of changes
521 you may need to make to get functionality working on a specific
522 operating system:
523 · Defining typedefs which are missing on that specific compiler: do
525 this in czmq_prelude.h.
526 · Defining macros that rename exotic library functions to more
528 conventional names: do this in czmq_prelude.h.
529 · Reimplementing specific methods to use a non-standard API: this is
531 typically needed on Windows. Do this in the relevant class, using
532 #ifdefs to properly differentiate code for different platforms.
533 The canonical standard operating system for all CZMQ code is Linux,
535 gcc, POSIX.
536
538 The czmq manual was written by the authors in the AUTHORS file.
539
541 Main web site:
542 Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>
544
546 Copyright (c) the Contributors as noted in the AUTHORS file. This file
547 is part of CZMQ, the high-level C binding for 0MQ:
548 http://czmq.zeromq.org. This Source Code Form is subject to the terms
549 of the Mozilla Public License, v. 2.0. If a copy of the MPL was not
550 distributed with this file, You can obtain one at
551 http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
552 distribution.
553
555 1. zeromq-dev@lists.zeromq.org
556 mailto:zeromq-dev@lists.zeromq.org
557CZMQ 4.0.2 12/31/2016 CZMQ(7)