Debian Codegraph @

doc/index.html

raw
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 &#8212; Generic Serialization for C++</title></head><body>
10 <h2 style="text-align: center;">Geners &#8212; 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 &#8212; 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 &#8212; 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 &#8212; 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> &#8212; 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> &#8212; 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>