s11n.net
s11nlite::save(Anything, Anywhere);
Project powered by:
SourceForge.net

libs11n 1.0.x

This page covers s11n 1.0.x. For info on 1.2.x, please see the 1.2 page.
s11n 1.0.x no longer maintained. libs11n 1.0 has been obsoleted by 1.2 for quite some time. The 1.0 code is kept around mainly for nostalgia's sake, and its use is not encouraged. See the main libs11n page for the latest version of s11n.

libs11n (s11n is short for "serialization") is a C++ library for serializing a wide range of data types, from PODs to STL containers to user-defined serializable types. It's very flexible and easy to understand and use. In addition, client-side s11n code is low-maintenance and relatively non-intrusive. Class templates make it possible for the library to adapt itself to client code (where possible/practical), plus other cool tricks such as fool-proof compile-time type safety with no type casts.

Usage samples: here, here, here, and here.

Development status:

The 1.0 tree is considered quite stable and ready for client use. i am not personally aware of any segfaults or other such nasties in libs11n or it's supporting libraries, at least not for "valid use cases".
Users new to s11n are encouraged to skip 1.0 and jump directly to the newer releases, as they make some major improvements in code portability and exception safety guarantees.

Primary features

  • Provides client code with easy de/serialization of arbitrary streamable types, user-defined Serializable types and various STL containers.
  • Most STL containers can be serialized with no special client-side work, as long as all contained types are either Serializable or are of a supported container type. e.g., std::map<std::string,std::list<MySerializable*>> is serializable as long as MySerializable is.
  • Does not tie clients to a specific serializable interface/heirarchy. The internally-used interfaces can be easily directed to use client-specific serializable interfaces, which means that the library can be made to conform to your projects, as opposed to your projects conforming to it.
  • User types can be made serializable "intrusively" - by implementing serialization opertors - or via proxying, in which case they need know nothing about s11n.
  • Serializer proxies can be written for almost any classes. For example, Qt objects can be serialized via this library without changing those objects. Proxies allow almost any type to be serialized without the object knowing it is participating in serialization.
  • Lends itself well to a large number of uses, from de/serializing arbitrary vectors or maps of data (a-la config files) to saving whole applications in one go (the amount of code is the same for the client, either way).
  • API is 100% data-format agnostic. Several different data format handlers are provided with the library, and adding your own is fairly painless. If you use s11nlite, as opposed to the core library, then you never even need to know what format your data is saved in.
  • Optional client-transparent zlib and bz2lib file de/compression (for amazing file size reduction).
  • A weird and wonderful classloader.
  • The model inherently does not suffer (as, e.g., Java's does) from the problem of invalidating serialized data every time an internal change is made to a serializable data type. It's properties-based system ensures that data do not become un-deserializable until the developer wants them to become so. It also ensures that clients written in different programming languages can deserializer your data, provided they have a way of converting the class types to local implementations. (Naturally, they can always read the raw data, without deserializing it, without any special support.)
  • By implementing an API front-end - like the included s11nlite namespace - client objects can be made 100% ignorant of the s11n core, enhancing non-intrusivity. This can also be used to factor all of the necessary APIs into one client-side namespace for easy access from client code.
Minor features:
  • Comes with an absolutely absurd amount of documentation, in the form of a library manual, API documentation, sample code and this web site. Most of the docs even halfway-correctly reflect reality!!! :)
  • Integration into existing class heirarchies is normally straightforward, quick, relatively painless and can often be incrementally applied to subsets of a project over time as needed (as opposed to forcing a client to completely refactor).
  • While saving requires specifying a data file format (i.e. a Serializer type), loading can be done in one line without knowing the format or knowing whether the file is compressed (nor do clients need to know which compression method it might be compressed with).
  • The primary data structures follow STL [Standard Template Library] conventions and are container-centric, thus many generic algorithms can be easily applied to them.
  • Uses only standard C++ constructs, no compiler-specific extensions. That said, it requires a relatively recent, standards-compiliant compiler with very good support for class templates.
  • Does not impose any file naming conventions on client data files: loading files is handled by looking at the first few bytes and delegating them to the appropriate loader. Clients can easily register their own stream handlers.
  • Comes with s11nconvert, a command-line tool to convert your data files between any supported formats.
  • Of course, it's completely experimental and subject to change at any moment. ;)

Caveats

libs11n is not a magic bullet - there are things it cannot do, and cases it is not suitable for.
  • It's heavy reliance on template specialization noticably cuts into compile times and bloats object and binary file sizes. One user reported that compilations took 14 times longer after adding s11n support. Experimentation is underway to reduce these times, but they are an unfortunate cost of using C++ templates, as described in more detail on the FAQ page.
  • The above-mentioned object/binary bloat means that this library is probably not suitable for systems with very restricted memory or filesystem space, like embedded or "old" (pre-21st-century) systems.
  • The library is designed with flexibility and maintainability in mind, not pure speed. That said, it performs fast enough for my needs: make your own judgement here.
  • It currently comes with no algorithms for handling cyclic structures (i.e., graphs), so clients using structures with cycles/joins will have to do some additional work. The library manual goes into this in more detail. That said, this library can inherently handle cycles and joins, but no algorithms current come with the library to handle them. The majority of parent/child-like relationships are no problem to handle using this library without special client-side work.
  • Microsoft-based systems are not currently supported (sorry, i don't have those tools). If someone will donate legal copies of WinXP and Visual Studio 7.1+ to this project then some effort will be put into porting it! That said, i personally find Windows OSes both physically and mentally painful to work with, so i can't promise anything, but i would certainly make an effort if someone would be generous enough to donate the required tools. (No, i'm not anti-Microsoft on philosophical or "principals" levels, as so many of my Linux-using brethren are.)

Requirements

  • Recent, ISO-conformant C++ compiler. Only tested with with GNU gcc 3.{2,3,4}.x, and will not work with gcc 2.9x.
  • GNU versions of most common Unix system tools, like make, find, bash, etc.
  • Only tested on Linux systems. Your mileage may vary on other OSes. That said, it uses no Linux-specific source code, but the build tree itself is very GNU-centric. That said, it is reported, by the Debian team, to build on at least 11(!!!) different Unix-like platforms (that tickles me pink, really).
  • Either libdl or libltdl. These are used for opening DLLs, and are pre-installed on all modern Unix-like environments.

Optional components:
  • libz, to enable gzip-style compression.
  • libbz2, to enable bzip-style compression.
The optional components are, as of 0.9.0, supported by supplemental libraries which ship as part of the libs11n download bundle.