August 2014

Reference Counting, Finalization and Resurrection

I've been enamoured of reference counting since devouring Smalltalk-80: The Language and its Implementation in 1987, and actively using it since reading Coplien's Advanced C++ in 1993.

For compatibility with the Object Pascal memory model, which ameliorated the lack of physical memory management, C++ on the Mac generally used handle-based heap objects. This had serious structural issues because they just weren't firmly located in memory.

Ultimately regular pointer-based heap objects won out even on Mac and reference counting became usable. I encapsulated the necessary activities in the smart pointer ZRef and the object base class ZCounted, which stabilized in the late 1990s after some struggles with the advent of preemptive multithreading.

All of which is to justify why I haven't simply embraced the C++11 standard library's smart_ptr — by implementing reference counting for myself I think I stumbled over every possible mistake, but also found a really useful mechanism I haven't encountered elsewhere. In the literature reference counting is considered to have two fundamental problems — reference cycles and object resurrection. In my experience a cycle (ultimately) indicates a broken data model.

However, inadvertent resurrection is a significant problem.

The issue is that we may want to take additional action when an entity's count transitions from one to zero, but if that action itself needs to treat the entity as counted, then the count will necessarily increment from zero, must ultimately transition down again, and we're into recursive execution of finalization.

Another situation is when we don't want simply to release the entity when it's no longer in general circulation, but want to change its treatment, perhaps by placing it in a cache. So we actually still have a physical reference to the entity, but managed with some different mechanism. This kind of changeover is very susceptible to thread issues. We could acquire a lock every time we manipulate any reference count, but that utterly kills performance and creates a pervasive and non-obvious source of deadlocks.

The solution is in the statement — we know to take action when the reference count changes from one to zero. What if we don't change the count in that case? Remember we're tracking the number of extant physical references. Seeing the one to zero transition tells us there's no other reference to the object than the one in our hands at that moment. So any further reference originates from the one we're considering finalizing. Rather than the typical atomic-decrement-and-test, releasing a reference uses a get, test and CAS sequence. The finalization code is now free to pass the entity to other code and no (legal) operation can again take the count from one to zero. Ultimately execution returns to the finalization. If the count has returned to (or remained) one, then we release the entity, otherwise do a simple atomic decrement and exit.

February 2014

WireOver - Fast, Free, Secure File Sending

WireOver is a Mac, Windows and Linux application for sending and receiving files. It's easy to use and very low friction, requiring only entry of an email address and click on a received web link to set up. Receiving an unsolicited send is even easier, as acting on the receipt of the notifying email naturally associates that email with the recipient.

Transfers (by subscribers) use perfect forward secrecy, and can be entirely asynchronous, so sender and receiver need never be online at the same time. Of course if they are, then transmission goes as fast as the physical network allows.

We built the backend and client mainly in Python, supporting Mac and Windows back to 10.5 and XP respectively. For Linux we support 32 and 64 bit Ubuntu 12 and later.

Much of my focus has been on keeping OS variations from impacting the main body of the code. To that end, we're using wxWidgets to abstract the GUI, and I've implemented such native code as needed to interface with unwrapped aspects of the OS and third-party libraries. In some cases the fluent Python bindings to OS facilities just aren't fast enough, and native code is used there also.

February 2012


Representations of rectangles and points are essential in any system working with graphics. Every API and many applications define their own. Depending on the era of the API there may be a full suite of algebraic-style operations, or the types may be simple data carriers with a handful of manipulating functions provided.

So what happens when bodies of code collide? Well, we end up with ad hoc transference of information from one representation to another, and chunks of code using a rich representation just look different from chunks using something more primitive.

In ZooLib I made several attempts at creating a clean suite of cartesian types and operations, with conversion operators and constructors, pseudo constructors and miscellaneous helper functions. But the approach just never scaled well.

Recently I've taken a very different tack. In ZCartesian I've defined a suite of template accessor functions -- passed a rectangle/point the edges, corners and centers can be extracted. Offsetting and aligning operations build on those accessors, as do sensible algebraic operators.

The accessor functions themselves forward to functions defined in traits templates. There's a suite of base classes for rectangles that are defined by variations of origin/extent or left/top/right/bottom. Supporting a new suite of cartesian types can be as simple as providing the definition of a traits class inheriting from one of the provided bases.

In this way we can work with NSRect, CGRect, XRectangle, QuickDraw Rect, Windows Rect, SDL_Rect, and their associated point (and size) structures using identical notation. And when we need to switch representations there's just a single pseudo-constructor to do the job.

April 2010

Jabber (XMPP) and AIM (OSCAR)

To integrate with existing social networks, the team at Zorap defined a mechanism that passed structured information via instant messages. My role was to implement Jabber (XMPP) and OSCAR, the AOL instant messenger protocol, in a portable and robust fashion.

Zorap ran as a browser extension, so could be instantiated and destroyed many times within the life of a process. Any code it used had to be robust, and could not depend on operating system facilities to dispose of resources like network sockets.

March 2008

Mac/BlackBerry SDK

The BlackBerry is a very popular mobile communications device. Official Mac support from Research in Motion is limited to providing the PocketMac utility as a free download. With no official SDK the Mac/BlackBerry ecosystem has seen very little activity.

ZBlackBerry is a suite of code that implements the BlackBerry USB communications protocol in a generic fashion. A few hundred lines of code let Macs use that protocol. A few hundred more allow multiple Mac applications to talk to a single BlackBerry simultaneously, something that has not been possible till now.

ZBlackBerry can also make a BlackBerry connected to a PC accessible via the same API as is used when it's connected directly to a Mac. This lets Mac application developers run their BlackBerry application under the Windows-based debugger and still have it communicate with their Mac application. This is a crucial capability when writing anything more than the most trivial application.

ZBlackBerry is part of ZooLib, our open source C++ library.

October 2007

Embedding Lua in Zen

Lua is a very nice little programming language, which combines a clean C-ish syntax with the power of Scheme. Rather than requiring a particular programming style it provides building blocks that allow one to work in any combination of object-oriented, functional or imperative styles. Lua is something of a hidden gem, having found a keen but un-publicized audience amongst game developers who generally use it for scripting in-game behavior. My interest in it is to provide customizability of behavior in the Zen home automation system.

Zen itself is only about 15,000 lines of C++, using ZooLib to run on Mac, Windows and Linux. It uses a tuplebase to store configuration and state, and uses the same tuplebase as the communication medium between its components.

To earn its stripes as the foundation for a smart home its higher-level behavior needs to be customizable. Some of that customizability can be captured as data-driven C++ code, but there are always edge cases to deal with, and C++ is not as malleable as I'd like when experimenting. So for a long time I'd been looking for an embeddable programming language that could talk with the C++. I've considered SIOD, but I'm just not a Scheme person. And although Javascript is a much nicer language than you might believe from only having seen its use in web pages, the various open source implementations are quite hard to incorporate into an application that's not the web browser that spawned them.

Lua is written in ANSI C, not requiring much even of the standard C library. It took only a couple of hours from downloading Lua to having it compiled using GCC on Linux and CodeWarrior on Mac. Actually connecting it to C++ and to Zen took a bit longer, but only because its scheme for sharing data between C++ and Lua is unique in my experience and took some thought to fully grok.

There is an excellent book, "Programming in Lua" whose first edition is available online and the second edition in printed form.

Lua supports a small range of data types, inluding the usual number, string and booleans. More complex structures are represented as what Lua calls tables, which are very like a blend of LISP s-lists and a-lists, and thus map nicely to ZooLib's tuples.

Lua's controlling mechanisms themselves use tables, so overriding library functions and global and function scopes use the same techniques as working with a program's own data structures.

Zen compiles Lua code that's kept in its tuplebase as that code is modified, and when the code is invoked provides access to state, which can be inspected and modified by Lua code. Reads from state variables are trapped and the code's dependency on those variables is noted so that external changes to those variables can cause the code to be re-run. This is much simpler than the scheme I initially implemented where each Lua function had to be declared in its own tuple, and its dependencies noted in that tuple.

January 2006


WebDAV is an extension to the HTTP protocol. It is the basis for Apple's iDisk and Windows' Web Folders, standard features of Mac OS X and Windows XP. It is thus the easiest way for a server to make data available to a client machine without requiring that client software be installed first.

ZooLib provides a generic WebDAV server. Your application need only implement subclasses of ZNodeRep to represent nodes in your desired hierarchy. Standard subclasses of ZNodeRep let you lay one tree over another, or expose part of the server's file system to clients.

Frankly, WebDAV is an inelegant protocol. It puts some information in the URL, some in header lines, and some is encoded as XML in the body of requests and responses. But it has three sterling characteristics:

  • It exists
  • It works
  • It's usable out of the box on Mac, Windows and many flavors of UNIX

May 2005

ZTSoup: UI-Friendly Tuplebase Access

The tuplebase API is well-suited to data processing needs. But it's clumsy as the mechanism by which data in a tuplebase is to be presented and maintained in a live UI, rather than web pages or generated reports.

ZTSoup gets its name and inspiration from the Apple Newton concept. A ZTSoup is backed by the same data as a tuplebase, but that data is accessed by instantiating a ZTCrouton for each tuple that code is interested in, and a ZTSieve for the result set of any query of interest. Why the funny names? A soup has croutons floating in it, interesting ones are sieved out of it.

There are two problems with connecting a UI to a transaction-based store like the tuplebase. First, how do you efficiently identify the minimal set of interesting changes that have been made in the tuplebase. Second, in reading or writing data, what do you do when a transaction fails to commit?

ZTSoup addresses these problems by maintaining objects locally that record a snapshot of the subset of the tuplebase in which the software is interested. Local changes are recorded in those objects, and they are sent to the tuplebase as a single atomic update operation. It's simply a matter of hooking a call to the soup's Update method into the normal event loop -- all additions and removals of interest in croutons and sieves are sent to the tuplebase, and remote changes to the croutons and sieves are returned.

Because the soup may be talking to a tuplebase on the end of a comms link the update work is split into a synchronous piece, which executes in a small amount of time with no blocking, and an async piece that accumulates work done by the synchronous piece and communicates with the server as fast as latency and server CPU will allow.

May 2003


ZDCPixmapBlit uses templates to generate the code for source/destination and source/matte/destination blitting, matte/destination filling, and destination-only munging, using the four Porter/Duff composition operators Copy, Over, In and Plus.

October 2002


ZooLib's tuplebase is derived from the tuplespace concept initially explored in the Linda coordination language, another well known derivation of which is Sun's JavaSpaces system. Whereas JavaSpaces is Java-only and relies on many of that languages's features, ZooLib's tuplebase works today with C++ and Java, and is well suited to work with other languages.

Language agnosticism is a key feature of tuplebase. Another is its runtime flexibility, which contrasts with most relational database implementations.

The power of a relational database is that the data it stores conforms to a rigorously defined structure. For a single piece of software it's always possible to find a single structure that supports all the work to be performed. As the nature of that work changes the database schema is evolved along with it. But this evolution must be coordinated so that all software that depends on the schema is updated to accommodate the changes, or virtual views are created to preserve a logical interface to the data.

Tuplebase takes a very different approach. Rather than enforcing a structure it allows any structure at all to be stored. Different pieces of software with overlapping concerns obviously must coordinate amongst themselves, but there's no requirement that there be any single authority managing everything. And because there's no mandated structure it's possible at runtime to treat multiple physical tuplebases as a single logical tuplebase, even if they contain data of different provenances. If the code using the data is written to be accommodating to the gradual migration of meaning then newer code can correctly interpret older data, and older code will ignore (but preserve) newer data.

October 2002

IFF and QuickTime File Formats

IFF is a venerable data meta-format, introduced in 1985 by Electronic Arts as a standard framing mechanism for multimedia data. In short it defines a nested chunked format, where the file as a whole is considered to be a chunk. A chunk has as its first four bytes a tag that indicates the type of data in the payload, a 32 bit (four bytes again) count of the number of bytes in the payload, and then that number bytes being the payload itself. Some chunk types are known to contain zero or more other chunks in their payload, so an arbitrarily complex hiearchy can be established. There are other details, but chunk types and sizes are IFF's essentials. QuickTime's file format is almost the same, except that the size comes first, and includes the eight bytes of the chunk header.

IFF/QT are simpler than most file formats, but can still be fiddly to work with. To make it easier for me to parse and generate QT files manually (on platforms which don't have QT libraries) I put together a suite of ZooLib streams that take care of all the bookkeeping.

Tuples Defined Rigorously

For most of my career I've been very suspicious of dynamic data representations. After all, what's the point of having a compiler if it isn't provided with enough information about the shape of the data being manipulated to tell you when your code is going wrong. However, that really only works for data created and consumed within a single application. In the mid-90s, every C++ framework worth its salt had a huge bunch of code dedicated to turning arbitrary C++ objects into something that could be serialized and regenerated as objects later; and in fact that's about as far as most people got with CORBA before giving up.

But most objects in a C++ program, if they're objects at all, simply don't need to be serialized. The ones that do have disparate needs, and special cases abound. The approach I've found most flexible and least intrusive is to provide ZTuple. In this context a tuple is isomorphic to a LISP a-list, Python or Cocoa dictionary, Perl or Ruby Hash or to a Java Map. It's simply a list of name/value pairs, where values can be primitives (strings, numbers, raw bytes etc), tuples or lists of values.

ZooLib provides a suite of facilities that read and write tuples to binary streams, generate and parse a well-defined and easy to read text format, and that can read and write appropriate data formats as tuples.

ZDC_ZooLib: Portable Graphics

ZooLib defines and implements a graphics API that produces identical results across all supported platforms. It is geared towards creating user interface elements and so is pixel-based rather than geometric so that a programmer can know precisely which pixels will be touched by a drawing operation. It supports pixel-plotting, lines of any thickness, text, rectangles, rounded rectangles, ovals, arbitrary regions and the drawing of masked-pixmaps. ZDC_ZooLib is an implementation of this API using no OS facilities at all, and thus can be used in server applications without the difficulties that normally poses (gaining access to a window or graphics server from a low-privilege process).

The implementation uses operations on ZBigRegion instances to decide which pixels to touch, decomposes the regions into rectangles and then calls ZDCPixmapBlit to actually do the work.

January 2002


There's a maxim, a citation for which I can't locate now, which pours scorn on the idea of multiplexing streams over TCP. It kinda made sense when I first saw it, but in these days of ornery system adminstrators and their firewalls that sometimes allow connections seemingly on the roll of a die, there's a lot to be said for the all or nothing of getting a connection to a server, and then sharing it locally.

I wrote ZStreamMUX after coming across an early draft of WebMUX. ZStreamMUX takes a read stream and a write stream, and runs a lightweight protocol over them to support multiple independent sessions. The overall interface is similar to that provided by sockets. The protocol is asynchronous, and uses buffer credits to prevent deadlock at the protocol level.

June 2001

BlockStore: File System in a File

Applications often have to satisfy two conflicting requirements. On the one hand the data created by a user has a structure whose parts should be managed independently of one another, ideally with each piece placed in its own file. On the other hand users like to think of their data as a single entity which can be copied, emailed and backed up in its entirety. Although Mac OS X has the notion of a bundle, a specially marked directory which behaves like a single file when manipulated by the Finder, other operating systems do not.

So, a ZBlockStore takes a single file (or file-like entity) and allows an application to work with resizable blocks allocated within it, easily, efficiently and (with ZBlockStore_PhaseTree) safely.

  • Easy to use — blocks are managed with the same API as real files.
  • Efficient — all the data lives in a wide fan-out B+ Tree.
  • Safe — modifications to nodes in the tree cause the entire ancestor branch to be replicated into existing free space, and the new root is atomically updated only when descendant nodes are known to be in stable storage.

March 2001

Assets: Portable resources

I picked the name 'asset' as an alternative to 'resource', a term that already has too many disparate meanings on different platforms. That said, assets are used in the same situations that MacOS/Win32/BeOS resources would be, although the mechanism is more flexible.

The data making up an asset tree is directly usable by any processor, big or little-endian. It can be kept in a file, loaded into RAM, memory-mapped from disk or accessed from a stream.

December 2000


ZooLib is an Open Source (MIT License) C++ library that makes it easy to write one set of source and build an application for Windows, Mac and UNIX. It provides a foundation suite of facilities that in essence form a virtual operating system API, and wide range of higher-level facilities that build on that foundation.

ZooLib abstracts threads, files, networking, graphics and the user interface. And there are escape hatches whereby OS-specific features can be accessed without compromising the platform-agnostic nature of the rest of the code.

ZooLib has been under continual development since 1992, and incorporates fixes for every OS bug or anomaly I've encountered, and generally provides cleaner mechanisms for most tasks than OSes traditionally provide. It's been the basis of Measurement in Motion, NetPhone, and every version of the Knowledge Forum server and client applications.

September 2000


ZStreamR_Boundary is a ZooLib stream derivative that uses Boyer-Moore-Horspool to take a source stream and efficiently provide to a caller only that data preceding a boundary. This is very useful when parsing MIME multipart streams, which can be nested arbitrarily and otherwise get very fiddly to deal with.

August 1999


NPainter is a suite of classes that provides a MacPaint-like interface, but supporting indexed and true color, across all platforms supported by ZooLib.

A key design feature is that it never touches its hosting environment directly. Instead it simply posts update notifications, and so the hosting environment is free to clip or draw on top of a painting as it is being worked on. This makes it easier to host in environments with tricky constraints, and to achieve effects like multiple views onto different parts of the same painting.

May 1999

Windoids: Windows Within Windows...

Measurement in Motion 1.0 had an interesting interface. A document contained a set of measurements, and various objects that could display and modify those measurements. The objects were represented as 'windoids', windows within the document window. MiM 1.0 was a Mac application, so the windoids could depend only on ZooLib's graphics API, with no help from the OS. When demand for a Windows version became overwhelming I implemented a full windowing system that conformed to ZooLib's ZOSWindow API, so that any code that worked within a regular OS window could instead be hosted in a windoid. QuickTime by this point was writing to the screen buffer asynchronously, so any change in the visible region of a windoid is notified before it happens and after its completed, somewhat like the BeOS BDirectWindow mechanism.

August 1998


In porting ZooLib to BeOS I found that BeOS's region API was missing key features. Exclusive or and equivalence testing could be handled by composing more primitive operations, but insetting was trickier. So I dug through the X source and found that their implementation of insetting was totally generic, basically shifting the source region for each set bit in the inset distance and accumulating a union (for expanding) or intersection (for contracting).

But BRegion was also quite slow. The internal representation was pretty close to that used by the X code, being a list of non-overlapping rectangles organized into bands. BRegion did not always maintain the same tight constraints as the X code, but it still proved possible to significantly improve performance by manipulating BRegion's internal data using the X code.

By this point I was intimately familiar with X regions and it was a small step to take the X source and rework it, the result being ZBigRegion - a portable region implementation using 32 bit coordinates. Combined with ZDCPixmapBlit it forms the basis of ZDC_ZooLib.

January 1996

ZDBase: Portable Database Engine

ZDBase is a relatively simple database storage engine. It's more of an alternative to Berkeley DB (as it was) than a replacement for MySQL. It supports an arbitrary number of tables, records and typed/named fields within those records. Each table maintains as many indices as desired, and the schema can be updated at any time. All data is kept in a blockstore, so everything lives in a single file, and the code and data are portable across platforms.

This was my first serious use of B-Trees, the essential basis of most high-performance disk-based storage systems. The searching of B-Tree content and the insertion of new data is well documented in numerous sources, but the deletion of data is invariably left as an exercise for the reader, which was a bit frustrating but ultimately empowering.

Project Archives