Save time. Save effort. Let s11n save your data, man.
Project powered by:
|
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.
|