| 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 |
} |