| 1 |
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> |
| 2 |
<html><head> |
| 3 |
|
| 4 |
|
| 5 |
|
| 6 |
|
| 7 |
|
| 8 |
|
| 9 |
<meta content="text/html; charset=ISO-8859-1" http-equiv="content-type"><title>Geners — Generic Serialization for C++</title></head><body> |
| 10 |
<h2 style="text-align: center;">Geners — Generic Serialization for C++</h2> |
| 11 |
The "geners" package is designed to address the problem of C++ object |
| 12 |
persistence in situations where the most typical data access pattern is |
| 13 |
"write once read many" (WORM). This access pattern is very common in |
| 14 |
scientific projects — a data recording device or a simulation program |
| 15 |
creates the original set of objects which is later reused (typically, |
| 16 |
for the purposes of data analysis and presentation of results) by other |
| 17 |
programs. |
| 18 |
"Geners" is, more or less, a set of tools and conventions which allows |
| 19 |
its users to develop C++ classes that can be converted to and from a |
| 20 |
storable stream of bytes in a well-organized and type-safe manner. |
| 21 |
Serialization of STL containers is supported, including the ones added |
| 22 |
in the C++11 standard. Independent versioning of each class |
| 23 |
definition is allowed. "Geners" code depends only on the standard C++ |
| 24 |
facilities and on two well-established portable data compression |
| 25 |
libraries, <a href="http://zlib.net/">zlib</a> and <a href="http://bzip.org/">bzip2</a>. These libraries are included by default in many Linux distributions.<br> |
| 26 |
<br> |
| 27 |
The functionality of "geners" is somewhat similar to that provided by the <a href="http://www.boost.org/libs/serialization">boost serialization</a> |
| 28 |
package. Compared to boost serialization, "geners" has a number of |
| 29 |
important differences (both advantages and drawbacks). Some of the |
| 30 |
advantages are listed below:<br> |
| 31 |
<ul> |
| 32 |
|
| 33 |
|
| 34 |
<li>"Geners" archives provide random access to stored objects.</li> |
| 35 |
|
| 36 |
|
| 37 |
<li>The archives can be searched using object labels assigned at the |
| 38 |
time the objects are stored. The object metadata can be examined |
| 39 |
without accessing the objects themselves.<br> |
| 40 |
</li> |
| 41 |
|
| 42 |
|
| 43 |
<li>File-based |
| 44 |
"geners" archives have built-in support for data |
| 45 |
compression (combining compression with serialization is somewhat |
| 46 |
cumbersome with boost). Random access and compression can be used |
| 47 |
together.<br> |
| 48 |
</li> |
| 49 |
|
| 50 |
|
| 51 |
<li>With proper wrappers for stored classes (e.g., generated by <a href="http://www.swig.org/">SWIG</a>), "geners" archives can be easily accessed from scripting languages.</li> |
| 52 |
|
| 53 |
|
| 54 |
<li>"Geners" can be used to create and serialize very large |
| 55 |
"archive-based" objects (e.g., collections of tuples) which do not fit |
| 56 |
in the computer memory.</li> |
| 57 |
|
| 58 |
|
| 59 |
<li> Serializable classes do not have to be implemented using template-based code, so compilation times can be shorter.</li> |
| 60 |
|
| 61 |
|
| 62 |
<li>"Geners" is a small package with very limited external dependencies.</li> |
| 63 |
|
| 64 |
</ul> |
| 65 |
|
| 66 |
Compared to boost serialization, "geners" drawbacks are:<br> |
| 67 |
<ol> |
| 68 |
</ol> |
| 69 |
<ul> |
| 70 |
<li>Only binary archives are currently implemented, there is no text |
| 71 |
or XML storage. As in boost, binary format is not portable |
| 72 |
across different platforms (archives created on 32-bit machines can not |
| 73 |
be read on 64-bit machines, little endian architectures are not |
| 74 |
compatible with big endian, etc). It would not be difficult to maintain |
| 75 |
binary portability, but at this time the package author simply does not |
| 76 |
have access to a sufficiently wide selection of hardware.<br> |
| 77 |
</li> |
| 78 |
|
| 79 |
<li>Serialization and deserialization are handled by separate methods |
| 80 |
of a class (in boost, these tasks can often be accomplished by a single template). For simple classes, this |
| 81 |
usually results in higher line counts of serialization-specific code |
| 82 |
than what is necessary for boost.<br> |
| 83 |
</li> |
| 84 |
<li>Implementing non-intrusive serialization is less transparent.</li> |
| 85 |
<li>There is no explicit support for solving the pointer aliasing problem |
| 86 |
— pointer management is left completely up to the user. In "geners", <span style="font-style: italic;"></span>every pointer serialization results in deep save and restore. Multiple saves |
| 87 |
of the same pointer result in multiple copies of the pointee object in |
| 88 |
the archive. |
| 89 |
Serialization of pointers to pointers is not supported and cyclic pointer arrangements are not detected.</li> |
| 90 |
|
| 91 |
</ul> |
| 92 |
<ol> |
| 93 |
|
| 94 |
|
| 95 |
|
| 96 |
|
| 97 |
</ol>It should be pointed out that, in scientific applications, storing |
| 98 |
multiple copies of an object is often the right thing to do — if the |
| 99 |
goal is to capture object evolution in time. The "no stored pointers" |
| 100 |
policy simplifies construction of archive APIs for scripting languages |
| 101 |
which do |
| 102 |
not have built-in support for pointers, such as Python or Tcl. For |
| 103 |
scientific applications that have to process significant amounts of |
| 104 |
data, "geners" advantages over boost serialization (in particular, |
| 105 |
random access to stored objects) |
| 106 |
easily outweigh the drawbacks. "Geners" is more tightly coupled to the |
| 107 |
C++ stream facilities than boost serialization, and the random access functionality |
| 108 |
does explicitly rely on the C++ streams interface.<br> |
| 109 |
<br> |
| 110 |
If you are a habitual <a href="http://root.cern.ch/">ROOT</a> user for |
| 111 |
object I/O, you will be pleasantly surprised by the fact that "geners" |
| 112 |
serialization does not rely on inheritance (nothing like <a href="http://root.cern.ch/root/html/TObject.html">TObject</a> |
| 113 |
is needed), so that addition of serialization capabilities to your high |
| 114 |
performance classes does not have to cripple them by imposing method |
| 115 |
dispatch via a virtual function table. Default constructor presence is |
| 116 |
not relied upon either.<br> |
| 117 |
<br> |
| 118 |
The easiest way to learn how to use "geners" is to take a look at the |
| 119 |
programs included in the "examples" directory of the "geners" |
| 120 |
distribution. Read the example code (it is reasonably well commented), |
| 121 |
run it, modify it and see what happens. To give you a glimpse of the |
| 122 |
"geners" API, a few code snippets are linked below:<br> |
| 123 |
<br><a href="http://geners.hepforge.org/svn/trunk/examples/hello_geners.cc"> |
| 124 |
hello_geners.cc</a> — illustrates very basic usage of the archive I/O<br><a href="http://geners.hepforge.org/svn/trunk/examples/SimpleSerializable1.hh"> |
| 125 |
SimpleSerializable1.hh</a>, <a href="http://geners.hepforge.org/svn/trunk/examples/SimpleSerializable1.cc">SimpleSerializable1.cc</a> — example serializable class<br> |
| 126 |
<br> |
| 127 |
The package code distribution comes with a number of command line <a href="tools.html">tools</a> which permit examination of "geners" archive catalogs and, with some limitations, of the archived objects.<br> |
| 128 |
<br><a href="http://www.hepforge.org/downloads/geners"> |
| 129 |
Download Geners</a><br> |
| 130 |
<br> |
| 131 |
Contact: <a href="mailto:[email protected]">Igor Volobouev</a><br> |
| 132 |
<br> |
| 133 |
<br> |
| 134 |
|
| 135 |
|
| 136 |
</body></html> |