Debian Codegraph @

examples/geners_archives.cc

raw
1 //
2 // The following program illustrates the use of the three archives
3 // currently available in the "geners" package: StringArchive,
4 // BinaryFileArchive, and MultiFileArchive. All these archives are
5 // derived from the "AbsArchive" base class. For the code which writes
6 // C++ objects into the archives or reads them back, all archives are
7 // completely interchangeable.
8 //
9 // StringArchive -- Simple memory-based archive always open for both
10 // reading and writing. Fast, very useful for testing
11 // serialization of user-developed classes. This
12 // archive itself can be stored in binary files (just
13 // one object per file) using the API defined in the
14 // "geners/stringArchiveIO.hh" header. It can also be
15 // serialized and stored in other archives.
16 //
17 // BinaryFileArchive -- File-based archive. Creates two files: binary data
18 // file (possibly compressed) and binary catalog file
19 // (not compressed). The data is stored in binary form.
20 // Very large archives of this type can be created if
21 // the operating system supports large files.
22 //
23 // MultiFileArchive -- File-based archive using multiple binary data
24 // files. Catalog is still stored in one file only.
25 // Very large archives of this type can be created
26 // even if the operating system does not support
27 // large files. In particular, older linux systems
28 // (as well as older versions of NFS) have 2 GB file
29 // size limitation.
30 //
31 // Only memory-resident metadata catalogs are supported at this time.
32 // This can become a limitation for data samples with large quantities
33 // of small objects. In this situation one would have to create several
34 // archives and work with them one at a time.
35 //
36 // Due to the complete archive interchangeability, all other "geners"
37 // examples use the StringArchive class for archive-based I/O.
38 //
39 #include <iostream>
40
41 #include "geners/StringArchive.hh"
42 #include "geners/stringArchiveIO.hh"
43 #include "geners/BinaryFileArchive.hh"
44 #include "geners/MultiFileArchive.hh"
45 #include "geners/Record.hh"
46 #include "geners/Reference.hh"
47
48 using namespace gs;
49 using namespace std;
50
51 int main(int, char**)
52 {
53 // The archives to use. String archives can be unnamed (or give
54 // it a name using a C-string as a constructor argument).
55 StringArchive sar;
56
57 // The first argument of any binary file archive constructor
58 // is the name of the archive. The names of files included in
59 // the archive will be derived from this argument. For example,
60 // if the name of the archive is "arch1", the following files
61 // will be made: arch1.0.gsbd and arch1.gsbmf. Extension "gsbd"
62 // stands for "generic serialization binary data", and extension
63 // "gsbmf" stands for "generic serialization binary metafile".
64 // The metafile contains the all-important archive catalog.
65 //
66 // The second constructor argument, "mode", specifies the opening
67 // mode of the archive data files as well as certain archive
68 // options. The "mode" string can have one or more sections,
69 // separated by ":". The first section has the same meaning as
70 // in the "fopen" call (see "man 3 fopen"). Additional sections
71 // can specify other aspects of the archive behavior using the
72 // format "option=value" if the default settings are not suitable.
73 // The available options are:
74 //
75 // "z" -- compression type. Possible option values are
76 // "n" -- no compression (default)
77 // "z" -- compress with zlib
78 // "b" -- compress with bzlib2
79 //
80 // "cl" -- compression level (an integer between -1 and 9,
81 // -1 is default. Meanigful for zlib compression
82 // only. See zlib documentation for details.
83 //
84 // "cb" -- compression buffer size in bytes (unsigned integer).
85 // Default is 1 MB.
86 //
87 // "cm" -- minimum object size in bytes to compress (unsigned
88 // integer). Objects whose serialized size is below
89 // this limit are not compressed. Default is 1 KB.
90 //
91 // "cat" -- if the value is set to "i" (which means "internal"
92 // or "injected"), the catalog data will be injected
93 // into the data stream in addition to having it in
94 // a separate catalog file. This allows for catalog
95 // recovery from the data stream in cases of program
96 // failure but also increases the data file size.
97 // The default value of this option is "s" which means
98 // that the catalog data will be stored separately.
99 // This option is meaningful for new archives only,
100 // for existing archives the value of this option is
101 // taken from the archive header record.
102 //
103 // Example: "w+:z=z:cl=9:cm=2048:cat=s". This will compress
104 // objects with 2 KB or larger size using level 9 zlib compression
105 // (the best compression ratio possible in zlib which is also
106 // the slowest). The archive will be open for reading and writing.
107 // If an archive with the same name already exists, it will be
108 // overwritten. The catalog will be stored in a separate file
109 // created when the archive is closed, catalog recovery from the
110 // data file(s) in case of a catastrophic program failure will
111 // not be possible.
112 //
113 // Empty mode string is equivalent to "r".
114 //
115 // The third archive constructor argument is an arbitrary archive
116 // annotation string which will be stored together with the archive
117 // catalog. This argument is optional (empty string is the default).
118 //
119 const char* mode = "w"; // Here, open write-only archive, with
120 // default values for all other setting
121 BinaryFileArchive bfar("arch1", mode, "single file archive");
122
123 // If a multi file archive is named "arch2", its binary data
124 // files will be named arch2.N.gsbd, with N = 0, 1, 2, ...
125 // The second and the third contructor arguments have the same
126 // meaning as for the BinaryFileArchive. The fourth argument
127 // is the approximate maximum file size in MB (default value
128 // of that argument corresponds to the maximum file size of
129 // about 1 GB). The value used here, 0, will force every new
130 // object to be written into a new data file. THIS SETTING IS
131 // USEFUL FOR ILLUSTRATIVE PURPOSES ONLY, LARGER VALUES SHOULD
132 // BE USED IN PRACTICE (or just omit this argument altogether
133 // in order to use the default value).
134 //
135 MultiFileArchive mfar("arch2", mode, "multi file archive", 0);
136
137 // The objects which we want to store in the archives
138 const string st1 = "Hello, world!";
139 const string st2 = "Goodbye world";
140
141 // Store the objects in the archives. Note that records can not
142 // be reused, so we have to create a new record every time.
143 sar << Record(st1, "hello", "Greetings")
144 << Record(st2, "goodbye", "Greetings");
145
146 bfar << Record(st1, "hello", "Greetings")
147 << Record(st2, "goodbye", "Greetings");
148
149 mfar << Record(st1, "hello", "Greetings")
150 << Record(st2, "goodbye", "Greetings");
151
152 // Write out the string archive. See comments in the
153 // "stringArchiveIO.hh" header file on how to configure
154 // compression for storing and retrieving string archives.
155 //
156 if (!writeStringArchive(sar, "arch3.gssa"))
157 std::cerr << "Failed to write the string archive" << std::endl;
158
159 // The archives will be automatically flushed to disk and closed
160 // when they go out of scope. Therefore, do not use the "exit"
161 // function to terminate the program! If "exit" is called here,
162 // destructors of objects created inside "main" will not be executed.
163 //
164 // Once the program completes, you can examine the catalog files
165 // using the "cdump" tool.
166 //
167 return 0;
168 }