Permalink
Browse files

Released czmq v1.0.0

  • Loading branch information...
1 parent 2b3431c commit d5d0ec9058b88a1ad86dc8df066c597fa5042b72 @hintjens hintjens committed Apr 26, 2011
Showing with 514 additions and 312 deletions.
  1. +9 −9 .gitignore
  2. +4 −2 NEWS
  3. +47 −46 README.md
  4. +37 −37 README.txt
  5. +5 −5 configure.in
  6. +2 −2 doc/Makefile.am
  7. +9 −9 doc/asciidoc.conf
  8. +44 −44 doc/{libzapi.txt → czmq.txt}
  9. +1 −1 doc/mkman
  10. +4 −4 doc/mksite
  11. +4 −4 doc/xml2wd.pl
  12. +2 −2 doc/zclock.txt
  13. +3 −3 doc/zctx.txt
  14. +1 −1 doc/zframe.txt
  15. +1 −1 doc/zhash.txt
  16. +1 −1 doc/zlist.txt
  17. +1 −1 doc/zloop.txt
  18. +1 −1 doc/zmsg.txt
  19. +4 −4 doc/zsocket.txt
  20. +1 −1 doc/zsockopt.txt
  21. +1 −1 doc/zstr.txt
  22. +1 −1 doc/zthread.txt
  23. BIN images/README_1.png
  24. BIN images/README_2.png
  25. +6 −6 include/{zapi.h → czmq.h}
  26. +14 −14 include/{zapi_prelude.h → czmq_prelude.h}
  27. +2 −2 include/zclock.h
  28. +4 −4 include/zctx.h
  29. +2 −2 include/zframe.h
  30. +2 −2 include/zhash.h
  31. +2 −2 include/zlist.h
  32. +2 −2 include/zloop.h
  33. +2 −2 include/zmsg.h
  34. +4 −4 include/zsocket.h
  35. +2 −2 include/zsockopt.h
  36. +2 −2 include/zstr.h
  37. +2 −2 include/zthread.h
  38. +5 −5 sockopts.gsl
  39. +11 −11 src/Makefile.am
  40. +148 −0 src/czmq_selftest
  41. +5 −5 src/{zapi_selftest.c → czmq_selftest.c}
  42. +41 −0 src/libczmq.la
  43. +10 −0 src/libczmq.pc
  44. +3 −3 src/{libzapi.pc.in → libczmq.pc.in}
  45. +3 −3 src/zclock.c
  46. +6 −6 src/zctx.c
  47. +3 −3 src/zframe.c
  48. +3 −3 src/zhash.c
  49. +3 −3 src/zlist.c
  50. +3 −3 src/zloop.c
  51. +3 −3 src/zmsg.c
  52. +4 −4 src/zsocket.c
  53. +3 −3 src/zsockopt.c
  54. +3 −3 src/zstr.c
  55. +3 −3 src/zthread.c
  56. +4 −4 win32/README.txt
  57. +2 −2 win32/{zapi.sln → czmq.sln}
  58. +12 −12 win32/{zapi.vcproj → czmq.vcproj}
  59. +7 −7 win32/{zapi_selftest.vcproj → czmq_selftest.vcproj}
View
18 .gitignore 100755 → 100644
@@ -13,19 +13,19 @@ libtool
src/.deps/
src/Makefile
src/Makefile.in
-src/libzapi.pc
+src/libczmq.pc
src/platform.hpp
src/platform.hpp.in
src/platform.hpp.in~
src/stamp-h1
src/*.o
src/mtrace.txt
src/outbin
-src/zapi_selftest
+src/czmq_selftest
doc/*.7
doc/*.xml
src/.libs/
-src/libzapi.la
+src/czmq.la
src/platform.h
src/platform.h.in
src/platform.h.in~
@@ -40,9 +40,9 @@ src/core
ipr
*.gz
*.zip
-win32/zapi.ncb
-win32/zapi.vcproj.WS200902.user.user
-win32/zapi_selftest.exe.embed.manifest
-win32/zapi_selftest.exe.embed.manifest.res
-win32/zapi_selftest.exe.intermediate.manifest
-win32/zapi_selftest.vcproj.WS200902.user.user
+win32/czmq.ncb
+win32/czmq.vcproj.WS200902.user.user
+win32/czmq_selftest.exe.embed.manifest
+win32/czmq_selftest.exe.embed.manifest.res
+win32/czmq_selftest.exe.intermediate.manifest
+win32/czmq_selftest.vcproj.WS200902.user.user
View
6 NEWS
@@ -1,11 +1,13 @@
-libzapi version 1.3.3 (stable), released on 2011/04/xx
-======================================================
+czmq version 1.0.0 (stable), released on 2011/04/26
+===================================================
Changes
-------
* At build time, reports error if libzmq version isn't at least 2.1.
+* Renamed project to czmq for coherence with other language bindings.
+
libzapi version 1.3.2 (beta), released on 2011/04/15
====================================================
View

Large diffs are not rendered by default.

Oops, something went wrong.
View
74 README.txt 100755 → 100644
@@ -1,7 +1,7 @@
-.set GIT=https://github.com/zeromq/libzapi
+Z.set GIT=https://github.com/zeromq/czmq
.sub 0MQ=ØMQ
-# libzapi - High-level C binding for 0MQ
+# czmq - High-level C binding for 0MQ
## Contents
@@ -11,13 +11,13 @@
### Scope and Goals
-libzapi has these goals:
+czmq has these goals:
* To wrap the 0MQ core API in semantics that are natural and lead to shorter, more readable applications.
-* To hide the differences between versions of 0MQ, particularly 2.0, 2.1, and 3.0.
+* To hide the differences between versions of 0MQ, particularly 2.1 and 3.0.
* To provide a space for development of more sophisticated API semantics.
-libzapi grew out of concepts developed in [ØMQ - The Guide](http://zguide.zeromq.org) and [ZFL](http://zfl.zeromq.org).
+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//.
[diagram]
+---------------+
@@ -32,7 +32,7 @@ libzapi grew out of concepts developed in [ØMQ - The Guide](http://zguide.zerom
v |
Open context +---------+ |
Create sockets | | | Connect, bind sockets
- Close sockets | libzapi | | get/set socket options
+ Close sockets | czmq | | get/set socket options
Send/receive | cYEL | |
Multithreading +----+----+ |
Reactor pattern | |
@@ -63,26 +63,26 @@ libzapi grew out of concepts developed in [ØMQ - The Guide](http://zguide.zerom
### Ownership and License
-libzapi 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.
+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.
-The authors of libzapi 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.
+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.
### Contributing
-To submit an issue use the [issue tracker](http://github.com/zeromq/libzapi/issues). All discussion happens on the [zeromq-dev](zeromq-dev@lists.zeromq.org) list or #zeromq IRC channel at irc.freenode.net.
+To submit an issue use the [issue tracker](http://github.com/zeromq/czmq/issues). All discussion happens on the [zeromq-dev](zeromq-dev@lists.zeromq.org) list or #zeromq IRC channel at irc.freenode.net.
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 http://www.zeromq.org/docs:contributing. All contributors are listed in AUTHORS.
-The general rule is, if you contribute code to libzapi 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.
+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.
-## Using libzapi
+## Using czmq
### Building and Installing
-libzapi uses autotools for packaging. To build from git (all example commands are for Linux):
+czmq uses autotools for packaging. To build from git (all example commands are for Linux):
- git clone git://github.com/zeromq/libzapi.git
- cd libzapi
+ git clone git://github.com/zeromq/czmq.git
+ cd czmq
sh autogen.sh
./configure
make all
@@ -93,15 +93,15 @@ You will need the libtool and autotools packages. On FreeBSD, you may need to sp
./configure --with-zeromq=/usr/local
-After building, you can run the libzapi selftests:
+After building, you can run the czmq selftests:
make check
### Linking with an Application
-Include `zapi.h` in your application and link with libzapi. Here is a typical gcc link command:
+Include `czmq.h` in your application and link with czmq. Here is a typical gcc link command:
- gcc -lzapi -lzmq myapp.c -o myapp
+ gcc -lczmq -lzmq myapp.c -o myapp
### API Summary
@@ -243,7 +243,7 @@ The answer to this, as we learned from building enterprise-level C applications
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.
-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 libzapi class):
+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):
zregexp_t *regexp = zregexp_new (regexp_string);
if (!regexp)
@@ -267,7 +267,7 @@ No model is fully consistent, and classes can define their own rules if it helps
### Naming Style
-libzapi 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:
+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:
zclassname_methodname
@@ -288,12 +288,12 @@ We assume that at some point we'll need to switch to a doubly-linked list.
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.
-libzapi is a portability layer, similar to but thinner than libraries like the [Apache Portable Runtime](http://apr.apache.org) (APR).
+czmq is a portability layer, similar to but thinner than libraries like the [Apache Portable Runtime](http://apr.apache.org) (APR).
These are the places a C application is subject to arbitrary system differences:
-* 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 zapi_prelude.h, e.g. defining int64_t on Windows.
-* 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 zapi_prelude.h. This is a proven brute-force approach that increases recompilation times but eliminates a major source of pain.
+* 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.
+* 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.
* 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.
* 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,26 +307,26 @@ An example of the last:
pid = 0;
#endif
-libzapi uses the GNU autotools system, so non-portable code can use the macros this defines. It can also use macros defined by the zapi_prelude.h header file.
+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.
### Technical Aspects
* *Thread safety*: the use of opaque structures is thread safe, though 0MQ applications should not share state between threads in any case.
* *Name spaces*: we prefix class names with `z`, which ensures that all exported functions are globally safe.
* *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.
* *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.
-* *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 `zapi_selftest` application does this.
-* *Memory management*: libzapi 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.
+* *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.
+* *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.
## Under the Hood
### Adding a New Class
-If you define a new libzapi class `myclass` you need to:
+If you define a new czmq class `myclass` you need to:
* Write the `zmyclass.c` and `zmyclass.h` source files, in `src` and `include` respectively.
-* Add`#include <zmyclass.h>` to `include/zapi.h`.
-* Add the myclass header and test call to `src/zapi_selftest.c`.
+* Add`#include <zmyclass.h>` to `include/czmq.h`.
+* Add the myclass header and test call to `src/czmq_selftest.c`.
* Add a reference documentation to 'doc/zmyclass.txt'.
* Add myclass to 'src/Makefile.am` and `doc/Makefile.am`.
@@ -346,13 +346,13 @@ So while ANSI C code might say:
file_buffer = zblob_new ();
...
-The style in libzapi would be:
+The style in czmq would be:
zblob_t *file_buffer = zblob_new ();
### Assertions
-We use assertions heavily to catch bad argument values. The libzapi classes do not attempt to validate arguments and report errors; bad arguments are treated as fatal application programming errors.
+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.
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).
@@ -407,24 +407,24 @@ The template for man pages is in doc/mkman.
### Development
-libzapi is developed through a test-driven process that guarantees no memory violations or leaks in the code:
+czmq is developed through a test-driven process that guarantees no memory violations or leaks in the code:
* Modify a class or method.
* Update the test method for that class.
* Run the 'selftest' script, which uses the Valgrind memcheck tool.
* Repeat until perfect.
-### Porting libzapi
+### Porting czmq
-When you try libzapi 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 quite heavy. In any case, the benefit is that once ported, the functionality is available to all applications.
+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.
-Before attempting to patch code for portability, please read the `zapi_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:
+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:
-* Defining typedefs which are missing on that specific compiler: do this in zapi_prelude.h.
-* Defining macros that rename exotic library functions to more conventional names: do this in zapi_prelude.h.
+* Defining typedefs which are missing on that specific compiler: do this in czmq_prelude.h.
+* Defining macros that rename exotic library functions to more conventional names: do this in czmq_prelude.h.
* 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.
-The canonical 'standard operating system' for all libzapi code is Linux, gcc, POSIX.
+The canonical 'standard operating system' for all czmq code is Linux, gcc, POSIX. The canonical 'weird operating system' for czmq is Windows.
### Code Generation
View
@@ -6,7 +6,7 @@ AC_PREREQ(2.61)
# The version in git should reflect the *next* version planned.
# Version must be MAJOR.MINOR.PATCH otherwise things will break.
#
-AC_INIT([libzapi],[1.3.3],[zeromq-dev@lists.zeromq.org])
+AC_INIT([czmq],[1.0.0],[zeromq-dev@lists.zeromq.org])
AC_CONFIG_AUX_DIR(config)
AC_CONFIG_MACRO_DIR(config)
@@ -33,7 +33,7 @@ AC_SUBST(PACKAGE_VERSION)
# know exactly what you're doing and have read and understand
# http://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html
#
-# libzapi -version-info
+# libczmq -version-info
LTVER="0:0:0"
AC_SUBST(LTVER)
@@ -107,7 +107,7 @@ if test "x$zapi_have_asciidoc" = "xno" -o "x$zapi_have_xmlto" = "xno"; then
# Tarballs built with 'make dist' ship with prebuilt documentation.
if ! test -f doc/zapi.7; then
zapi_install_man="no"
- AC_MSG_WARN([You are building an unreleased version of libzapi and asciidoc or xmlto are not installed.])
+ AC_MSG_WARN([You are building an unreleased version of libczmq and asciidoc or xmlto are not installed.])
AC_MSG_WARN([Documentation will not be built and manual pages will not be installed.])
fi
fi
@@ -116,7 +116,7 @@ AC_MSG_RESULT([$zapi_build_doc])
AC_MSG_CHECKING([whether to install manpages])
AC_MSG_RESULT([$zapi_install_man])
-# Set some default features required by libzapi code.
+# Set some default features required by libczmq code.
CPPFLAGS="-D_REENTRANT -D_THREAD_SAFE $CPPFLAGS"
# OS-specific tests
@@ -210,5 +210,5 @@ AM_CONDITIONAL(BUILD_DOC, test "x$zapi_build_doc" = "xyes")
AC_TYPE_SIGNAL
AC_CHECK_FUNCS(perror gettimeofday memset)
-AC_OUTPUT(Makefile src/Makefile doc/Makefile src/libzapi.pc)
+AC_OUTPUT(Makefile src/Makefile doc/Makefile src/libczmq.pc)
View
@@ -1,6 +1,6 @@
MAN1 =
MAN3 =
-MAN7 = libzapi.7 \
+MAN7 = czmq.7 \
zclock.7 \
zctx.7 \
zframe.7 \
@@ -34,7 +34,7 @@ SUFFIXES=.txt .xml .1 .3 .7
.txt.xml:
./mkman $<
asciidoc -d manpage -b docbook -f asciidoc.conf \
- -azapi_version=@PACKAGE_VERSION@ $<
+ -aczmq_version=@PACKAGE_VERSION@ $<
.xml.1:
xmlto man $<
.xml.3:
Oops, something went wrong.

0 comments on commit d5d0ec9

Please sign in to comment.