libs11n 1.2.x

This page covers s11n 1.2. The library can be downloaded from the downloads page, as can the library manual and API docs. Examples of using the library can be found here.

1.2 is architecturally almost identical to 1.0, but it has been restructured and refactored, primarily in the name of having a more portable source tree. It also provides a number of leak guarantees which 1.0 does not correctly impose (and cannot without significant changes).

Main features

Provides easy-to-use, easy-to-integrate, and low-maintenance interfaces for serializing a wide variety of C++ types.
Serialization support can often be added to types without modifying those types, or them even being aware they are playing along. For example...
Out of the box it supports all STL containers (and workalikes), nested arbitrarily deep. By extension, we can (rightfully) assume that...
Clients can easily extend it to support their own types using, often non-intrusively.
It is data-format agnostic, meaning it doesn't internally care about any file formats. It is container-centric, not stream-centric. The provided i/o layer is just one potential solution to i/o, and the core library can be used with arbitrary client-side i/o mechanisms. The core inherently supports in-memory serialization, not requiring any i/o layer whatsoever (this is useful for serializing over a clipboard-like mechanism and for "casting via serialization").
Comes with support for several different file formats, and add-ons can be written to provide further formats (e.g., sqlite3 databases).
On some platforms it can dynamically load new data format handlers and Serializable types on-demand from DLLs. This includes Linux and probably most other Unices. Win32 support for plugins is problematic for reasons explained in the Porting Guide.
With the exception of the (optional) plugins support, the library uses only ISO-standard C++ constructs, meaning the code is portable to arbitrary modern C++ platforms. That said, it requires a compiler with excellent templates support, including partial template specialization. GCC 3.2+ are believed to be adequate, as is MSVC 2003+.
On Unix platforms, it optionally supports client-transparent de/compression from/to zlib- and b2lib-compressed files. (This requires the zfstream utility library.)
The library comes with an absurd amount of documentation, in the forms of this web site, API docs, and a large library manual.
Comes with s11nconvert, a tool which can convert s11n-saved data between all supported formats.

In no particular order, the significant changes and additions in 1.2, compared to 1.0, include...

Exception handling

The exceptions support has been completely overhauled. Version 1.2 fixes all known potential leaks which (it was realized quite late) could happen during deserialization of, e.g., standard containers holding pointers. Most of the default de/serialization algorithms can now make safety and no-modification guaratees which were previously impossible to make. For client types which have special cleanup needs, it provides an API for clients to tell s11n how to clean up those types during failed deserializations.

s11nlite refactoring

s11nlite's interface hasn't changed much, but it is now refactored to live on top of a class, client_api<NodeType>. The purpose of this is to allow client code to very easily create their own variant of s11nlite by simply templatizing the type client_api<NodeType> to suit their needs, or via subclassing. s11nlite allows clients to plug in their own type, as long as it uses the same node type as s11nlite. See the sample under src/client/sample/mylite.cpp

Header file re-orgs

Many of the 1.0 headers have their names for historical - not practical - purposes. At one point i had two completely different s11n architectures living in the same source directory, and had to differentiate their header file names. (i needed it to allow my s11n 0.6-based client code to work.) Many headers have been moved around, in particular the proxy-related headers have been reorganized to be easier to find.

Compilation speed improvements

Due mainly to the header file re-orgs, compile times for many typical client cases have been notably shortened. Test cases involving small numbers of Serializable types (1-4 or so is fairly typical) showed compile times cut by 50-80%.

Platform portability improvements

As of version 1.1.2+ we can build under Windows :). We also ship source trees which are suitable for arbitrary platforms, without the need to generate the files which are normally generated as part of the standard build process. These require the addition of build files, such as a project file or Autotools, or can be dropped right in to your project tree.

Standalone source tree

Unlike 1.0, which was built on top of several support libraries, 1.2 does not rely on external libraries for any features. It has optional support for the zfstream library (available on the downloads page), but it is not required.

Factory rewrite

i've rewritten the underlying factory (classloader) layer from scratch. i won't say it's any better or worse, just a bit different. This won't affect the majority of client code, since s11n provides an abstraction API into the classloader in the first place.

Potential TODOs

Some potential TODOs for future 1.2.x releases, or potentially 1.3+, include:

Serializer interface: add a way to cancel/interrupt a de/serialize operation. This requires reworking the current Serializers to honor that "suggestion." This feature currently can't be consolidated into most of the current Serializer implementations, due to the separation of the Serializer objects from the actual code which does the input. (Long story.)
Focus more on the functional composition code. This opens up a lot of as-yet-not-fully-understood doors.
Rethink the plugin layer, and potentially define conventions for specific symbols in DLLs which will be called (if available) on opening a DLL, in order to allow us to pass info (like command-line options and database handles) to certain types of plugins.
Figure out a typesafe way for clients to feed data to Serializers for purposes of enhancing de/serialization. An example would be the ability for a database-aware Serializer to get at a database handle, such that it could read SQL files and feed them to that db.

Main menu:

Download from:

Libs/apps/utils:

SourceForge:

More Resources:

Related sites: