Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 447 lines (275 sloc) 19.498 kb
eec8e2f7 » hintjens
2011-06-08 Fixed typo in README
1 .set GIT=https://github.com/zeromq/czmq
e282512d » hintjens
2011-03-22 Initial upload of skeleton API
2 .sub 0MQ=ØMQ
3
fcaf6e23 » hintjens
2011-06-09 Renamed czmq to CZMQ
4 # CZMQ - High-level C binding for 0MQ
e282512d » hintjens
2011-03-22 Initial upload of skeleton API
5
6 ## Contents
7
8 .toc
9
10 ## Overview
11
12 ### Scope and Goals
13
fcaf6e23 » hintjens
2011-06-09 Renamed czmq to CZMQ
14 CZMQ has these goals:
e282512d » hintjens
2011-03-22 Initial upload of skeleton API
15
16 * To wrap the 0MQ core API in semantics that are natural and lead to shorter, more readable applications.
46ba9418 » hintjens
2012-03-18 Generated documentation
17 * To hide the differences between versions of 0MQ, particularly 2.1 and 3.1.
e282512d » hintjens
2011-03-22 Initial upload of skeleton API
18 * To provide a space for development of more sophisticated API semantics.
19
fcaf6e23 » hintjens
2011-06-09 Renamed czmq to CZMQ
20 CZMQ grew out of concepts developed in [ØMQ - The Guide](http://zguide.zeromq.org) and [ZFL](http://zfl.zeromq.org). Until end-April 2011, CZMQ was known as *libzapi*.
66d39e10 » hintjens
2011-03-22 zapi is now working
21
a3eb3409 » hintjens
2011-03-24 Updated for 1.1.1, improved docs
22 [diagram]
23 +---------------+
24 | |
25 | C application |
26 | |
27 +-----+---+-----+
28 | |
29 | |
30 +------------+ |
31 | |
32 v |
33 Open context +---------+ |
34 Create sockets | | | Connect, bind sockets
fcaf6e23 » hintjens
2011-06-09 Renamed czmq to CZMQ
35 Close sockets | CZMQ | | get/set socket options
a3eb3409 » hintjens
2011-03-24 Updated for 1.1.1, improved docs
36 Send/receive | cYEL | |
37 Multithreading +----+----+ |
38 Reactor pattern | |
39 Hash container +------------+ |
40 List container | |
e4bf5459 » hintjens
2011-03-24 Added zclock class
41 System clock v v
42 Close context +---------+
a3eb3409 » hintjens
2011-03-24 Updated for 1.1.1, improved docs
43 | |
44 | libzmq |
45 | |
46 +---------+
47
48 [/diagram]
49
66d39e10 » hintjens
2011-03-22 zapi is now working
50 ### Highlights
51
46ba9418 » hintjens
2012-03-18 Generated documentation
52 * Single API hides differences between 0MQ/2.1, and 0MQ/3.1.
66d39e10 » hintjens
2011-03-22 zapi is now working
53 * Work with messages as strings, individual frames, or multipart messages.
54 * Automatic closure of any open sockets at context termination.
55 * Automatic LINGER configuration of all sockets for context termination.
4790ff7c » hintjens
2011-03-23 Released version 1.1.0 of zapi
56 * Portable API for creating child threads and 0MQ pipes to talk to them.
66d39e10 » hintjens
2011-03-22 zapi is now working
57 * Simple reactor with one-off and repeated timers, and socket readers.
e4bf5459 » hintjens
2011-03-24 Added zclock class
58 * System clock functions for sleeping and calculating timers.
9f90df9c » hintjens
2011-04-07 Added zsocket and zsockopt classes
59 * Easy API to get/set all socket options.
66d39e10 » hintjens
2011-03-22 zapi is now working
60 * Portable to Linux, UNIX, OS X, Windows (porting is not yet complete).
4790ff7c » hintjens
2011-03-23 Released version 1.1.0 of zapi
61 * Includes generic hash and list containers.
62 * Full selftests on all classes.
66d39e10 » hintjens
2011-03-22 zapi is now working
63
e282512d » hintjens
2011-03-22 Initial upload of skeleton API
64 ### Ownership and License
65
fcaf6e23 » hintjens
2011-06-09 Renamed czmq to CZMQ
66 CZMQ is maintained by Pieter Hintjens and Mikko Koppanen (build system). Its other authors and contributors are listed in the AUTHORS file. It is held by the ZeroMQ organization at github.com.
e282512d » hintjens
2011-03-22 Initial upload of skeleton API
67
fcaf6e23 » hintjens
2011-06-09 Renamed czmq to CZMQ
68 The authors of CZMQ grant you use of this software under the terms of the GNU Lesser General Public License (LGPL). For details see the files `COPYING` and `COPYING.LESSER` in this directory.
e282512d » hintjens
2011-03-22 Initial upload of skeleton API
69
70 ### Contributing
71
46ba9418 » hintjens
2012-03-18 Generated documentation
72 CZMQ uses the [C4 (Collective Code Construction Contract)](http://rfc.zeromq.org/spec:16) process which says, "Everyone, without distinction or discrimination, SHALL have an equal right to become a Contributor under the terms of this contract".
e282512d » hintjens
2011-03-22 Initial upload of skeleton API
73
46ba9418 » hintjens
2012-03-18 Generated documentation
74 To report an issue, use the [CZMQ issue tracker](https://github.com/zeromq/czmq/issues) at github.com.
e282512d » hintjens
2011-03-22 Initial upload of skeleton API
75
fcaf6e23 » hintjens
2011-06-09 Renamed czmq to CZMQ
76 ## Using CZMQ
e282512d » hintjens
2011-03-22 Initial upload of skeleton API
77
66d39e10 » hintjens
2011-03-22 zapi is now working
78 ### Building and Installing
79
fcaf6e23 » hintjens
2011-06-09 Renamed czmq to CZMQ
80 CZMQ uses autotools for packaging. To build from git (all example commands are for Linux):
66d39e10 » hintjens
2011-03-22 zapi is now working
81
d5d0ec90 » hintjens
2011-04-26 Released czmq v1.0.0
82 git clone git://github.com/zeromq/czmq.git
83 cd czmq
66d39e10 » hintjens
2011-03-22 zapi is now working
84 sh autogen.sh
85 ./configure
86 make all
87 sudo make install
88 sudo ldconfig
89
90 You will need the libtool and autotools packages. On FreeBSD, you may need to specify the default directories for configure:
91
b0a049cc » dcolish
2012-03-21 Correct libzmq configure flag in README
92 ./configure --with-libzmq=/usr/local
66d39e10 » hintjens
2011-03-22 zapi is now working
93
fcaf6e23 » hintjens
2011-06-09 Renamed czmq to CZMQ
94 After building, you can run the CZMQ selftests:
66d39e10 » hintjens
2011-03-22 zapi is now working
95
96 make check
97
98 ### Linking with an Application
99
fcaf6e23 » hintjens
2011-06-09 Renamed czmq to CZMQ
100 Include `czmq.h` in your application and link with libczmq. Here is a typical gcc link command:
66d39e10 » hintjens
2011-03-22 zapi is now working
101
d5d0ec90 » hintjens
2011-04-26 Released czmq v1.0.0
102 gcc -lczmq -lzmq myapp.c -o myapp
66d39e10 » hintjens
2011-03-22 zapi is now working
103
9c79f4d4 » hintjens
2011-03-22 Updated README to cover API
104 ### API Summary
105
106 #### zctx - working with 0MQ contexts
107
38873e12 » hintjens
2011-03-24 Generated documentation
108 .pull src/zctx.c@header,left
66d39e10 » hintjens
2011-03-22 zapi is now working
109
110 This is the class interface:
9c79f4d4 » hintjens
2011-03-22 Updated README to cover API
111
38873e12 » hintjens
2011-03-24 Generated documentation
112 .pull include/zctx.h@interface,code
113
114 .pull src/zctx.c@discuss,left
9c79f4d4 » hintjens
2011-03-22 Updated README to cover API
115
9f90df9c » hintjens
2011-04-07 Added zsocket and zsockopt classes
116 #### zsocket - working with 0MQ sockets
117
118 .pull src/zsocket.c@header,left
119
120 This is the class interface:
121
122 .pull include/zsocket.h@interface,code
123
124 .pull src/zsocket.c@discuss,left
125
126 #### zsockopt - working with 0MQ socket options
127
128 .pull src/zsockopt.c@header,left
129
130 This is the class interface:
131
132 .pull include/zsockopt.h@interface,code
133
134 .pull src/zsockopt.c@discuss,left
135
9c79f4d4 » hintjens
2011-03-22 Updated README to cover API
136 #### zstr - sending and receiving strings
137
38873e12 » hintjens
2011-03-24 Generated documentation
138 .pull src/zstr.c@header,left
66d39e10 » hintjens
2011-03-22 zapi is now working
139
a3eb3409 » hintjens
2011-03-24 Updated for 1.1.1, improved docs
140 [diagram]
141
38873e12 » hintjens
2011-03-24 Generated documentation
142 Memory Wire
143 +-------------+---+ +---+-------------+
144 Send | S t r i n g | 0 | ----> | 6 | S t r i n g |
145 +-------------+---+ +---+-------------+
a3eb3409 » hintjens
2011-03-24 Updated for 1.1.1, improved docs
146
38873e12 » hintjens
2011-03-24 Generated documentation
147 Wire Heap
148 +---+-------------+ +-------------+---+
149 Recv | 6 | S t r i n g | ----> | S t r i n g | 0 |
150 +---+-------------+ +-------------+---+
a3eb3409 » hintjens
2011-03-24 Updated for 1.1.1, improved docs
151
152 [/diagram]
153
66d39e10 » hintjens
2011-03-22 zapi is now working
154 This is the class interface:
9c79f4d4 » hintjens
2011-03-22 Updated README to cover API
155
38873e12 » hintjens
2011-03-24 Generated documentation
156 .pull include/zstr.h@interface,code
157
158 .pull src/zstr.c@discuss,left
9c79f4d4 » hintjens
2011-03-22 Updated README to cover API
159
392ddba1 » hintjens
2011-05-31 Added zfile class
160 #### zfile - work with files
161
162 .pull src/zfile.c@header,left
163
164 This is the class interface:
165
166 .pull include/zfile.h@interface,code
167
168 .pull src/zfile.c@discuss,left
169
9c79f4d4 » hintjens
2011-03-22 Updated README to cover API
170 #### zframe - working with single message frames
171
38873e12 » hintjens
2011-03-24 Generated documentation
172 .pull src/zframe.c@header,left
66d39e10 » hintjens
2011-03-22 zapi is now working
173
174 This is the class interface:
9c79f4d4 » hintjens
2011-03-22 Updated README to cover API
175
38873e12 » hintjens
2011-03-24 Generated documentation
176 .pull include/zframe.h@interface,code
177
178 .pull src/zframe.c@discuss,left
9c79f4d4 » hintjens
2011-03-22 Updated README to cover API
179
180 #### zmsg - working with multipart messages
181
38873e12 » hintjens
2011-03-24 Generated documentation
182 .pull src/zmsg.c@header,left
66d39e10 » hintjens
2011-03-22 zapi is now working
183
184 This is the class interface:
9c79f4d4 » hintjens
2011-03-22 Updated README to cover API
185
38873e12 » hintjens
2011-03-24 Generated documentation
186 .pull include/zmsg.h@interface,code
187
188 .pull src/zmsg.c@discuss,left
9c79f4d4 » hintjens
2011-03-22 Updated README to cover API
189
190 #### zloop - event-driven reactor
191
38873e12 » hintjens
2011-03-24 Generated documentation
192 .pull src/zloop.c@header,left
66d39e10 » hintjens
2011-03-22 zapi is now working
193
194 This is the class interface:
9c79f4d4 » hintjens
2011-03-22 Updated README to cover API
195
38873e12 » hintjens
2011-03-24 Generated documentation
196 .pull include/zloop.h@interface,code
197
198 .pull src/zloop.c@discuss,left
9c79f4d4 » hintjens
2011-03-22 Updated README to cover API
199
a5b7c9cc » hintjens
2011-04-07 Generated documentation
200 #### zthread - working with system threads
201
202 .pull src/zthread.c@header,left
203
204 This is the class interface:
205
206 .pull include/zthread.h@interface,code
207
208 .pull src/zthread.c@discuss,left
209
66d39e10 » hintjens
2011-03-22 zapi is now working
210 #### zhash - expandable hash table container
e282512d » hintjens
2011-03-22 Initial upload of skeleton API
211
38873e12 » hintjens
2011-03-24 Generated documentation
212 .pull src/zhash.c@header,left
e282512d » hintjens
2011-03-22 Initial upload of skeleton API
213
66d39e10 » hintjens
2011-03-22 zapi is now working
214 This is the class interface:
e282512d » hintjens
2011-03-22 Initial upload of skeleton API
215
38873e12 » hintjens
2011-03-24 Generated documentation
216 .pull include/zhash.h@interface,code
217
218 .pull src/zhash.c@discuss,left
e282512d » hintjens
2011-03-22 Initial upload of skeleton API
219
66d39e10 » hintjens
2011-03-22 zapi is now working
220 #### zlist - singly-linked list container
e282512d » hintjens
2011-03-22 Initial upload of skeleton API
221
38873e12 » hintjens
2011-03-24 Generated documentation
222 .pull src/zlist.c@header,left
e282512d » hintjens
2011-03-22 Initial upload of skeleton API
223
66d39e10 » hintjens
2011-03-22 zapi is now working
224 This is the class interface:
e282512d » hintjens
2011-03-22 Initial upload of skeleton API
225
38873e12 » hintjens
2011-03-24 Generated documentation
226 .pull include/zlist.h@interface,code
227
228 .pull src/zlist.c@discuss,left
e282512d » hintjens
2011-03-22 Initial upload of skeleton API
229
e4bf5459 » hintjens
2011-03-24 Added zclock class
230 #### zclock - millisecond clocks and delays
231
38873e12 » hintjens
2011-03-24 Generated documentation
232 .pull src/zclock.c@header,left
e4bf5459 » hintjens
2011-03-24 Added zclock class
233
234 This is the class interface:
235
38873e12 » hintjens
2011-03-24 Generated documentation
236 .pull include/zclock.h@interface,code
237
238 .pull src/zclock.c@discuss,left
e4bf5459 » hintjens
2011-03-24 Added zclock class
239
4e05565d » hintjens
2011-03-26 Extended main doc page
240 ## Design Ideology
241
242 ### The Problem with C
243
e5f77252 » hintjens
2011-03-30 Small doc fixes
244 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.
4e05565d » hintjens
2011-03-26 Extended main doc page
245
246 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.
247
248 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.
249
250 ### A Simple Class Model
251
252 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](http://www.openamq.org), a messaging client and server of 0.5M LoC, that a consistent model for extending C makes life for the application developer much easier.
253
fcaf6e23 » hintjens
2011-06-09 Renamed czmq to CZMQ
254 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):
4e05565d » hintjens
2011-03-26 Extended main doc page
255
256 zregexp_t *regexp = zregexp_new (regexp_string);
257 if (!regexp)
258 printf ("E: invalid regular expression: %s\n", regexp_string);
259 else
260 if (zregexp_match (regexp, input_buffer))
261 printf ("I: successful match for %s\n", input buffer);
262 zregexp_destroy (&regexp);
263
264 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's not worthwhile. The goal is not to emulate an OO system, it's simply to gain consistency. The constructor returns an object reference, or NULL if it fails. The destructor nullifies the class pointer, and is idempotent.
265
266 What we aim at here is the simplest possible consistent syntax.
267
268 No model is fully consistent, and classes can define their own rules if it helps make a better result. For example:
269
270 * 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.
271
272 * 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.
273
274 * 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.
275
276 ### Naming Style
277
fcaf6e23 » hintjens
2011-06-09 Renamed czmq to CZMQ
278 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:
4e05565d » hintjens
2011-03-26 Extended main doc page
279
280 zclassname_methodname
281
282 And the reader can easily parse this without needing special syntax to separate the class name from the method name.
283
284 ### Containers
285
286 After a long experiment with containers, we've decided that we need exactly two containers:
287
288 * A singly-linked list.
289 * A hash table using text keys.
290
291 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.
292
293 We assume that at some point we'll need to switch to a doubly-linked list.
294
295 ### Portability
296
297 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 0MQ core), there is no portability layer and application code does conditional compilation for all mixes of platforms. This leads to quite messy code.
298
fcaf6e23 » hintjens
2011-06-09 Renamed czmq to CZMQ
299 CZMQ is a portability layer, similar to but thinner than libraries like the [Apache Portable Runtime](http://apr.apache.org) (APR).
4e05565d » hintjens
2011-03-26 Extended main doc page
300
301 These are the places a C application is subject to arbitrary system differences:
302
d5d0ec90 » hintjens
2011-04-26 Released czmq v1.0.0
303 * 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 'patching' the language in czmq_prelude.h, e.g. defining int64_t on Windows.
304 * 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.
4e05565d » hintjens
2011-03-26 Extended main doc page
305 * 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, 'C', which detects the OS type and version (at runtime) and builds the necessary link commands.
306 * 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.
307
308 An example of the last:
309
310 #if (defined (__UNIX__))
311 pid = GetCurrentProcessId();
312 #elif (defined (__WINDOWS__))
313 pid = getpid ();
314 #else
315 pid = 0;
316 #endif
317
fcaf6e23 » hintjens
2011-06-09 Renamed czmq to CZMQ
318 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.
4e05565d » hintjens
2011-03-26 Extended main doc page
319
320 ### Technical Aspects
321
322 * *Thread safety*: the use of opaque structures is thread safe, though 0MQ applications should not share state between threads in any case.
323 * *Name spaces*: we prefix class names with `z`, which ensures that all exported functions are globally safe.
324 * *Library versioning*: we don't 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.
325 * *Performance*: 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.
d5d0ec90 » hintjens
2011-04-26 Released czmq v1.0.0
326 * *Self-testing*: 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.
fcaf6e23 » hintjens
2011-06-09 Renamed czmq to CZMQ
327 * *Memory management*: CZMQ classes do not use any special memory management techiques to detect leaks. We've done this in the past but it makes the code relatively complex. Instead, we do memory leak testing using tools like valgrind.
4e05565d » hintjens
2011-03-26 Extended main doc page
328
329 ## Under the Hood
330
331 ### Adding a New Class
332
fcaf6e23 » hintjens
2011-06-09 Renamed czmq to CZMQ
333 If you define a new CZMQ class `myclass` you need to:
4e05565d » hintjens
2011-03-26 Extended main doc page
334
335 * Write the `zmyclass.c` and `zmyclass.h` source files, in `src` and `include` respectively.
d5d0ec90 » hintjens
2011-04-26 Released czmq v1.0.0
336 * Add`#include <zmyclass.h>` to `include/czmq.h`.
337 * Add the myclass header and test call to `src/czmq_selftest.c`.
4e05565d » hintjens
2011-03-26 Extended main doc page
338 * Add a reference documentation to 'doc/zmyclass.txt'.
339 * Add myclass to 'src/Makefile.am` and `doc/Makefile.am`.
340
341 The `bin/newclass.sh` shell script will automate these steps for you.
342
343 ### Coding Style
344
345 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:
346
347 * The // comment style.
348 * Variables definitions placed in or before the code that uses them.
349
350 So while ANSI C code might say:
351
352 zblob_t *file_buffer; /* Buffer for our file */
353 ... (100 lines of code)
354 file_buffer = zblob_new ();
355 ...
356
fcaf6e23 » hintjens
2011-06-09 Renamed czmq to CZMQ
357 The style in CZMQ would be:
4e05565d » hintjens
2011-03-26 Extended main doc page
358
359 zblob_t *file_buffer = zblob_new ();
360
361 ### Assertions
362
fcaf6e23 » hintjens
2011-06-09 Renamed czmq to CZMQ
363 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.
4e05565d » hintjens
2011-03-26 Extended main doc page
364
365 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).
366
367 Assertion code should always take this form:
368
369 int rc = some_function (arguments);
370 assert (rc == 0);
371
372 Rather than the side-effect form:
373
374 assert (some_function (arguments) == 0);
375
376 Since assertions may be removed by an optimizing compiler.
377
378 ### Documentation
379
aa610c91 » hintjens
2011-03-26 Generated documentation
380 Man pages are generated from the class header and source files via the doc/mkman tool, and similar functionality in the gitdown tool (http://github.com/imatix/gitdown). The header file for a class must wrap its interface as follows (example is from include/zclock.h):
381
382 // @interface
383 // Sleep for a number of milliseconds
a5b7c9cc » hintjens
2011-04-07 Generated documentation
384 void
aa610c91 » hintjens
2011-03-26 Generated documentation
385 zclock_sleep (int msecs);
386
387 // Return current system clock as milliseconds
a5b7c9cc » hintjens
2011-04-07 Generated documentation
388 int64_t
aa610c91 » hintjens
2011-03-26 Generated documentation
389 zclock_time (void);
390
391 // Self test of this class
a5b7c9cc » hintjens
2011-04-07 Generated documentation
392 int
aa610c91 » hintjens
2011-03-26 Generated documentation
393 zclock_test (Bool verbose);
394 // @end
395
396 The source file for a class must provide documentation as follows:
397
a5b7c9cc » hintjens
2011-04-07 Generated documentation
398 /*
aa610c91 » hintjens
2011-03-26 Generated documentation
399 @header
400 ...short explanation of class...
401 @discuss
402 ...longer discussion of how it works...
403 @end
404 */
405
406 The source file for a class then provides the self test example as follows:
407
408 // @selftest
409 int64_t start = zclock_time ();
410 zclock_sleep (10);
411 assert ((zclock_time () - start) >= 10);
412 // @end
413
414 The template for man pages is in doc/mkman.
4e05565d » hintjens
2011-03-26 Extended main doc page
415
66d39e10 » hintjens
2011-03-22 zapi is now working
416 ### Development
e282512d » hintjens
2011-03-22 Initial upload of skeleton API
417
fcaf6e23 » hintjens
2011-06-09 Renamed czmq to CZMQ
418 CZMQ is developed through a test-driven process that guarantees no memory violations or leaks in the code:
66d39e10 » hintjens
2011-03-22 zapi is now working
419
420 * Modify a class or method.
421 * Update the test method for that class.
422 * Run the 'selftest' script, which uses the Valgrind memcheck tool.
423 * Repeat until perfect.
e282512d » hintjens
2011-03-22 Initial upload of skeleton API
424
fcaf6e23 » hintjens
2011-06-09 Renamed czmq to CZMQ
425 ### Porting CZMQ
4e05565d » hintjens
2011-03-26 Extended main doc page
426
fcaf6e23 » hintjens
2011-06-09 Renamed czmq to CZMQ
427 When you try CZMQ on an OS that it's 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 non-trivial. In any case, the benefit is that once ported, the functionality is available to all applications.
4e05565d » hintjens
2011-03-26 Extended main doc page
428
d5d0ec90 » hintjens
2011-04-26 Released czmq v1.0.0
429 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:
4e05565d » hintjens
2011-03-26 Extended main doc page
430
d5d0ec90 » hintjens
2011-04-26 Released czmq v1.0.0
431 * Defining typedefs which are missing on that specific compiler: do this in czmq_prelude.h.
432 * Defining macros that rename exotic library functions to more conventional names: do this in czmq_prelude.h.
4e05565d » hintjens
2011-03-26 Extended main doc page
433 * 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.
434
fcaf6e23 » hintjens
2011-06-09 Renamed czmq to CZMQ
435 The canonical 'standard operating system' for all CZMQ code is Linux, gcc, POSIX. The canonical 'weird operating system' for CZMQ is Windows.
4e05565d » hintjens
2011-03-26 Extended main doc page
436
9f90df9c » hintjens
2011-04-07 Added zsocket and zsockopt classes
437 ### Code Generation
438
46ba9418 » hintjens
2012-03-18 Generated documentation
439 We generate the zsockopt class using the mysterious but powerful GSL code generator. It's actually cool, since about 30 lines of XML are sufficient to generate 700 lines of code. Better, since many of the option data types changed in 0MQ/3.1, it's possible to completely hide the differences. To regenerate the zsockopt class, build and install GSL from https://github.com/imatix/gsl, and then:
9f90df9c » hintjens
2011-04-07 Added zsocket and zsockopt classes
440
441 gsl sockopts
442
443 You may also enjoy using this same technique if you're writing bindings in other languages. See the sockopts.gsl file, this can be easily modified to produce code in whatever language interests you.
444
e282512d » hintjens
2011-03-22 Initial upload of skeleton API
445 ### This Document
446
447 This document is originally at README.txt and is built using [gitdown](http://github.com/imatix/gitdown).
Something went wrong with that request. Please try again.