ZFL is the ØMQ Function Library, a thin portability & function library for ZeroMQ applications in C/C++. It is written as clear readable C classes, portable to all ØMQ platforms, and licensed under the LGPL.

ZFL is maintained by Pieter Hintjens and Martin Hurton. Its other authors and contributors are listed in the AUTHORS file. It is held by the ZeroMQ organization at github.com.

The authors of ZFL grant you free 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.

ZFL uses autotools for packaging. To build from git (all example commands are for Linux):

git clone git://github.com/zeromq/zfl.git
cd zfl
sh autogen.sh
./configure
make all
sudo make install
sudo ldconfig

You will need the pkg-config, libtool, and autoreconf packages. Set the LD_LIBRARY_PATH to /usr/local/libs unless you install elsewhere.

After building, you can run the ZFL selftests:

cd src
./zfl_selftest

Include zfl.h in your application and link with libzfl. Here is a typical gcc link command:

gcc -lzfl -lzmq myapp.c -o myapp

You should read zfl.h. This file includes zmq.h and the system header files that typical ØMQ applications will need. The provided 'c' shell script lets you write simple portable build scripts:

c -lzfl -lzmq -l myapp

ZFL consists of classes, each class consisting of a .h and a .c. Classes may depend on other classes.

zfl.h includes all classes header files, all the time. For the user, ZFL forms one single package. All classes start by including zfl.h. All applications that use ZFL start by including zfl.h. zfl.h also defines a limited number of small, useful macros and typedefs that have proven useful for writing clearer C code.

The canonical example for ZFL style is the zfl_base class, which defines the template for all other classes. The nomenclature for all classes is consistent. We use zfl_base as an example:

• Source files: zfl_base.c, zfl_base.h
• Methods: zfl_base_test, zfl_base_print, ...

All classes are based on a flat C class system and follow these rules:

• Class typedef: zfl_base_t
• Constructor: zfl_base_new
• Destructor: zfl_base_destroy
• Property methods: zfl_base_property_set, zfl_base_property
• Class structures are private (defined in the .c source but not the .h)
• Properties are accessed only via methods named as described above.
• In the class source code the object is always called self.
• The constructor may take arbitrary arguments, and returns NULL on failure, or a new object.
• The destructor takes a pointer to an object reference and nullifies it.

Return values for methods are:

• For methods that return an object reference, either the reference, or NULL on failure.
• For methods that signal success/failure, a return value of 0 means sucess, -1 failure.

Private/static functions in a class are named s_functionname and are not exported via the header file.

All classes have a test method called zfl_classname_test.

These are the existing ZFL classes:

• zfl_base - base class for ZFL
• zfl_blob - binary long object
• zfl_config - work with configuration files
• zfl_device - configure a device or device socket
• zfl_hash - expandable hash table container
• zfl_list - singly-linked list container
• zfl_msg - multipart ØMQ message
• zfl_rpcd - server side reliable RPC
• zfl_rpc - client side reliable RPC
• zfl_thread - work with operating system threads

The file zfl_prelude.h defines a number of macros including these:

#define FOREVER             for (;;)            //  FOREVER { ... }
#define until(expr)         while (!(expr))     //  do { ... } until (expr)
#define streq(s1,s2)        (!strcmp ((s1), (s2)))
#define strneq(s1,s2)       (strcmp ((s1), (s2)))
#define strused(s)          (*(s) != 0)
#define strnull(s)          (*(s) == 0)
#define strclr(s)           (*(s) = 0)
#define strlast(s)          ((s) [strlen (s) - 1])
#define strterm(s)          ((s) [strlen (s)])

#define tblsize(x)          (sizeof (x) / sizeof ((x) [0]))
#define tbllast(x)          (x [tblsize (x) - 1])

#define randomof(num)       (int) (((float) num) * rand () / (RAND_MAX + 1.0))
#define randomize()         srand ((uint) apr_time_usec (apr_time_now ()))

#if (!defined (MIN))
#   define MIN(a,b)         (((a) < (b))? (a): (b))
#   define MAX(a,b)         (((a) > (b))? (a): (b))
#endif

//- Assertion that pointer value is as expect -------------------------------

#define assert_eq(value,const) \
if ((value) != (const)) {\
    printf ("Assertion failed, expected=%d actual=%d", (const), (value));\
    assert ((value) == (const));\
}

//- Boolean operators and constants -----------------------------------------

#if (!defined (TRUE))
#    define TRUE        1               //  ANSI standard
#    define FALSE       0
#endif

Functions that create or search objects return object references success and NULL on failure. Functions that perform work return 0 on success and -1 on failure.

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. Every C++ developer will use a different 20% of the language.

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.

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.

ZFL 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:

zfl_classname_methodname

And the reader can easily parse this without needing special syntax to separate the class name from the method name.

After a long experiment with containers, we've decided that we need exactly two containers:

• A singly-linked list.
• A hash table using text keys.

These are zfl_list and zfl_hash, 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.

We assume that at some point we'll need to switch to a doubly-linked list.

ZFL provides two ways to do inheritance from base classes to higher level classes. First, by code copying. You may laugh but it works. The zfl_base class defines a basic syntactic structure. If we decide to change some of the ground rules shared by all classes, we modify the zfl_base class and then we manually make the same modifications in all other ZFL classes. Obviously as the number of classes in ZFL grows this becomes progressively harder, which is good: we don't want the basics to change more than they need to.

The second way is by straight encapsulation. For example if I want to make a specialized container that has some intelligence about the objects it contains, I can take the list or hash class, wrap that in a new class and add the necessary code on top. There is no attempt, nor need, to export methods or properties automatically. If I want this, I do it by hand.

Writing such code by hand may seem laborious but when we work with ruthlessly consistent style and semantics, it is easy, safe, and often the shortest path from problem to solution.

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 ØMQ core), there is no portability layer and application code does conditional compilation for all mixes of platforms. This leads to quite messy code.

• Thread safety: the use of opaque structures is thread safe, though ØMQ applications should not share state between threads in any case.

• Name spaces: we prefix class names with zfl_, 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 zfl_selftest application does this.

• Portability: the ZFL library is aimed at becoming a portability layer (like Apache APR or the older iMatix SFL) but that depends on it actually being ported. See section on 'Porting ZFL' below.

• Memory management: ZFL 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 mtrace:

  gcc -g -o zfl_selftest zfl*.c -lzmq export MALLOC_TRACE=mtrace.txt zfl_selftest mtrace zfl_selftest mtrace.txt

If you define a new ZFL class myclass you need to:

• Write the zfl_myclass.c and zfl_myclass.h source files, in zfl/src and zfl/include respectively.
• Add#include <zfl_myclass.h> to zfl/include/zfl.h.
• Add the myclass header and test call to src/zfl_selftest.c.
• Add a reference documentation to 'doc/zfl_myclass.txt'.
• Add myclass to 'src/Makefile.amanddoc/Makefile.am`.

In general the zfl_base class defines the style for the whole library. The overriding rule for coding style is consistency.

When you try ZFL 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.

Before attempting to patch code for portability, please read the zfl_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 zfl_prelude.h.
• Defining macros that rename exotic library functions to more conventional names: do this in zfl_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 ZFL code is Linux, gcc, POSIX.

To test against memory leaks we use the mtrace tool under Linux. The zfl_selftest.c program calls MALLOC_TRACE, which zfl_prelude.h sets to mtrace() under Linux. This is how we build and run the selftests with mtrace:

#  Run selftests and check memory
gcc -g -o zfl_selftest zfl*.c -lzmq
export MALLOC_TRACE=mtrace.txt
zfl_selftest -v
mtrace zfl_selftest mtrace.txt

Note that mtrace is not threadsafe and will not work consistently in multithreaded applications or test cases. All test cases should therefore be single-threaded.