Frequently Asked Questions
1 - Algorithms - what algorithms are available in DOL?
In general, DOL does not provide algorithms like LEDA. DOL provides building blocks with which you can code your own algorithms more efficiently. However, DOL provides some basic algorithms: Many data organization can be sorted, and all linked-list based organizations can split or be merged.
2 - Classes in DOL - what classes are available?
Link-lists and rings, collections, aggregates (one-to-many), many-to-many, graphs, trees, self-adjusting arrays, LIFO, FIFO, binary heap, hash table,NAME (variable-length string attached to an object), Java-like REFERENCE, text-labelled attributes, PAGER (similar to PPF), plus UTILITIES (saving to disk, access to meta class information, allocation, automatic free lists).
3 - Classes in PPF - what classes are available?
Just three smart pointer classes which make your application data automatically persistent:
PersistPtr<T> - pointer to an object of a simple class,
PersistVPtr<T> - pointer to an object of a class where inheritance (virtual functions) is involved,
PersistString - pointer to a variable length string.
4 - Classes in PTL - what classes are available?
Collections, aggregates (one-to-many), self-adjusting arrays, patterns Flyweight and Composite, and dynamically reconfigurable Finite State Machine.
5 - Compile errors when using DOL - too many errors.
DOL is set up so that the compiler performs an extensive check of your data structures (more than with other class libraries). It takes longer to get your application through the compiler, but once it compiles, it needs very little debugging. Hard to find pointer errors are practically eliminated in a better way than it is done in Java.
6 - Compile errors when using DOL - unable to resolve them.
If you get error messages which you are unable to clear, please check this:
- If you have file environ.h in your working directory, remove it. It is safer to depend on the default, which is orgc/lib/environ.h
- You should have #define ZZmain in one of your *.cpp files, but in one file only.
- You should have #include "zzincl.h" in all your files, and #include "zzfunc.c" in one of your source files, or you must compile zzfunc.c separately. Note that the call zzprep myFile file.h zzmaster file.c creates files file.h and file.c. The default names are zzincl.h, and zzfunc.c, zzmaster is always used. Therefore zzprep myfile has the same effect as zzprep myfile zzincl.h zzmaster zzfunc.c
- Above, file myFile must be a concatenation of all your header files, including the file where you have the definition of all relations (ZZ_HYPER... statements).
- Look at the regression script in the orgc/test directory, and see that you link to the correct library from the orgc/lib directory.
- NEVER attempt to debug and modify DOL. Most likely you are not using the library in the correct way. Send email to info@codefarms.com if you are stuck, we will help you.
7 - Depth-first traversal of trees - is it available in DOL?
DOL trees provide iterators which traverse children of the given node. With these iterators, other traversals are easy to arrange. For example:
class Node {
ZZ_EXT_Node
public:
void depthFirst();
};
ZZ_HYPER_SINGLE_TREE(myTree,Node);
void Node::depthFirst(){
Node *node;
myTree_iterator it(this);
ITERATE(it,node){
// access or print 'node' here
depthFirst(node);
}
}
8 - Debugger - may I use regular debugger when programming with your libraries?
For PPF and PTL - yes, with no restrictions.
For DOL, yes, but do not attempt to traverse or debug DOL code. This code is solid and tested by regression tests and years of use. It is our responsibility to fix it if you can prove there is an error in it.
Note that, under ZZ_HYPER_UTILITIES(util), DOL provides an unusual, very useful tool. If you place a call to util.debug() anywhere in your code, when your reach that point the program will switch to an interactive mode, in which you can traverse the entire data structure, pointer by pointer, and examine individal objects, their links and attributes.
For more details, see Chapl.14 in the DOL User Guide.
9 - DLL or Shared Object libraries - can they be used?
No problem with PPF or PTL. DOL can be used with some restrictions and precautions. In particular, if several subprojects use DOL independently, and these subprojects are compiled as S.O. or DLL, then only one of the subprojects may save data to disk. The other may only use the DOL data structures. Also, each subproject must be coded in a single file - not in a multitude of *.h and *.cpp files as recommended today. Note that these special requirements apply only when DLL or S.O. are used.
10 - DOL, PTL, PPF - which library is best for my application?
The following algorithm will help you to make the decision. The most critical question is whether you need persistence (storage of data and relations to disk). We often often contacted by customers who thought that they will not need persistent data, but now they deserately need it.
if(persistence required){
if(moving data among different platforms) use DOL;
if(shema migration or version control needed) use DOL;
if(data fit the virtual memory, storing and restoring the entire data){
use DOL;
}
if(mixed case of primary storage: some data in memory, some on disk){
// use the Pager class for the disk-stored data
use DOL;
}
// primary data storage on disk, paging data to memory on demand
if(simple data structures){
// code the data structure yourself, or use existing library
// but replace all pointers by PersistPtr
use PPF;
}
else {
if(data fits virtual memory without excessive paging){
// forget about PPF, it would be too much work
use DOL;
}
else {
// you have no choice, apply PPF to your complex data structure
use PPF;
}
}
}
else { // no persistence
if(design patterns are used) use PTL;
if(complex data structures) use DOL;
switch(what do you prefer){
case (no code generator): use PTL; break;
case (clarity, ease of coding): use DOL; break;
default: use DOL; break;
}
}
11 - Installing the free software - how do I do that?
Just unzip the file - it will create a subdirectory tree with all the files in it. No compilation or installation is required for the binaries of DOL and PPF, nor for the source of PTL.
Example: Installing DOL for Win98/VC++ after downloading file bindol.zip
pkunzip -d bindol.zip
... creates subdirectory 'orgc'
Example: Installing PPF for Solaris/g++ after downloading file gnuppf.zip
unzip -D -L gnuppf.zip
... creates subdirectory 'ppf'
12 - Intrusive data structures - why are they good?
Because they are closer to our way of thinking - they are the data structures you see in data structure textbooks. They run faster, require less memory and fewer objects - which implies less allocation and destruction overhead. The compiler catches most errors, and a simple if() statement protects the data integrity in run time. For more details see "Taming C++"
13 - Labelled attributes - are they available in DOL?
Labelled class attributes are called PROPERTY in DOL, and provide a great flexibility in working with data structures. The attribute can be an int, float, char, or an array of these. In many situations these attributes significantly reduce the size of objects, and also allow a smoother transfer to a new version of your software. For details, see the DOL User Guide, Chap.11 (PROPERTY) and Appendix A (PROPERTY).
14 - Mixing DOL and other class libraries (such as STL, tools.h++, or LEDA)
This is not recommended, and definitely will not work when persistence is used. You also lose the clear, central control of all data structures, which is one of the advantages of DOL.
15 - Mixing DOL and PPF in the same program - can it be done?
There is a better solution: DOL includes a special class called PAGER which, for selected classes or strings, provides a similar service as PPF does for all classes. Actually, PPF is just a smart pointer hiding the PAGER class from
DOL.
Typical application where this may be used is an abstract service system, which allows readers to search for books and other publicatins. In edition to an in-memory data structure for fast searches, the system keeps a large volume of text (e.g. abstracts) on disk, using PAGER.
16 - Mixing persistent and non-persistent objects in PPF, can it be done?
Yes, it can. For example:
class A { // non-persistent object
.... anything here as usual, but PersistClass(A) must not be used.
};
class B {
PersistClass(TreeIndex); // persistent class
A *aPtr; // pointer to non-persistent information
...
};
The use of PersistPtr<B> in your program automatically pages B objects in and out of disk, with aPtr copied as a raw number. This means that, within the same run, the reference remains valid.
17 - Multi-threading - is it supported?
None of the three products (DOL, PPF, PTL) has built-in support for multi-threading. However, these programs are often used in multi-threaded environments. Typically, DOL or PPF are used to build a database engine with the interface, which controls its access in the multi-threaded style.
18 - Persistence, adding it to a project coded with another class library
We frequently encounter this situation. People code with STL or tools.h++, and then they want to make the data persistent. This is not a simple addition (why didn't they think about it in the first place?). You have three options:
a. Replace your collections, arrays, or other data structures by classes from DOL. This is easy if your data structures and their access are not spread all over the code. The problem is that DOL uses intrusive data, therefore interfaces are different. The replacement must be done carefully, and with a good knowledge of how the two libraries work.
b. From your current data structure library, extract the classes needed for your application, and replace all pointer references by the persistent pointers from PPF. This is practical only if your data structure is not complex.
c. Re-code the project with DOL. This may sound ridiculous, but it is usually the safest and fastest solution. Every redesign improves software, and you will see how DOL will improve the clarity of the code, and the run-time performance.
19 - PersistPtr<>, PersistString - how to use them
If you are not used to working with smart pointers, note that most of the time they behave as pointers, but they still are objects even though operator '->' is overloaded. In particular:
class A;
A *aPtr;
PersistPtr<A> ap; // do not use '*'
PersistString ps;
...
aPtr=NULL;
ap=NULL; // is the same
if(aPtr).. // testing whether it is NULL
if(ap).. // compiles, but does not work !!
if(ap!=NULL).. // should be used instead
if(ap==NULL).. // also works fine
delete aPtr; // deletes the object
delete ap; // do NOT use, deletes smart pointer, not the object
ap.delObj(); // use instead
delete as; // do NOT use, deletes smart pointer, not the string
as.delString(); // use for deleting the string itself
20 - Run-time errors in PPF - what to do?
Make sure that you delete all *.ppf files before the first run. Old incorrect data files may cause weird errors.
Also, technical news sections describes a problem with unexpected behaviour of ~PersistString() in PPF Ver.2.0 and earlier. This problem is corrected in Ver.2.1.
21 - Saving data in DOL - what method should I use?
It does not matter much which method you start coding. It is easy to switch from one method to another. Also, a program may use different methods during the same run.
The ASCII and binary mode are based on serialization, but you don't have to code serialization functions. They are generated automatically. The ASCII mode is less efficient (slower, needs more disk space) but even if your classes and their relations change, the old data files are still usable. Also, data stored in this mode can move between different platforms.
The binary mode is more efficient, but less flexible. The classes and relations must not change, and the data can be restored only on the same platform. Coding with the binary saving to disk is easier, because it does not need ZZ_FORMAT statements, one for each class, required for the ASCII mode.
Memory blasting allocates objects from memory pages, and then stores entire pages as a fast binary write-operation. It is much faster than the other two modes. Coding with memory blasting requires more experience though, and debugging is more difficult.
When we develop a new program, we usually code as if saving the data in the binary mode, and only later switch to the ASCII mode or memory blasting later, when the program is safely running.
22 - Saving data in PPF - what is the algorithm?
Each class stores all its objects in a separate file, one file is kept for all strings. For example, objects of class myClass are stored in file myClass.ppf, and all strings always in file string.ppf. As you can imagine, this gets a bit more complicated whenmember objects or inheritance are used. Each class manages its file, including a list of free objects and allocation and deallocation of arrays.
You control the paging of the data individually for each class by calling
myClass::startPager(pageSz,numPagesInMemory,totalSpace);
where totalSpace is a rough upper bound (not a critical value) on the possible total space the program may need for myClass.
This allows you, for some classes, to keep only a few objects in memory at any given time, while objects of another class may all reside in memory until the end of the run.
When you call myClass::closePager(), all pages of myClass move to disk, and file myClass.ppf is closed.
23 - Saving data in sections, possibly to different files. Can it be done in DOL?
This can be done, but it involves the advanced use of the library. If you are starting with DOL, just remember that it is possible. For the details, see the DOL User Guide, Chap.13.3, advanced features around the paragraph with the title "Multiple Files".
The idea is to disconnect pointers in some narrow bottleneck of the data-structure, ask the DOL saving utility to save each section to a different file, and reconnect the two parts together.
Note that in PPF, each class saves its objects to a different file, so this question does not arise.
24 - Sorted Collection - is it available in DOL?
No, it is not. You can sort most of the data organizations by calling their sort() function, but when adding new elements to them, the sorted order is not maintained. The reason is that in performance sensitive applications, other methods of storage are usually preferred, e.g. hashing.
25 - Sorting - is sorting of linked lists in DOL efficient?
Most of DOL classes have a sort function, which uses a compare function in the same style as qsort() does. Most programmers are not aware that linked lists can be efficiently sorted. The algorithm is essentialy the merge sort, and has the same complexity and performance comparable to qsort() for sorting arrays.
26 - SQL - does DOL or PPF support it?
No, they don't. DOL and PPF are designed to create framework-like databases, which are accessed by functions you design yourself. It usually takes only a day or a few to design such a database, and the improvement in performance is staggering.
27 - Templates - may I use templates when programming with DOL, PTL, PPF?
For PTL and PPF - yes, you can. For DOL - you can, but only for non-persistent classes. The input file for zzprep must not include templates, the code generator (zzprep) cannot handle them.
28 - Transactions - does DOL and PPF support transactional model?
DOL does not, but PPF does. However, you have to provide the code which controls the transactions.
29 - WinNT - why the free DOL for Windows does not run under WinNT?
DOL runs on any platform including WinNT, but in the free binary version the access to WinNT is blocked. You have to purchase the source in order to run under WinNT.
30 - ZZ_EXT_.. statement - does every class need it?
In DOL, usually all classes have this statement. In advanced applications, you may have some persistent classes (with ZZ_EXT_..) and some non-persistent classes (without ZZ_EXT_..). If you are starting with DOL, use ZZ_EXT_.. in every class
31 - zzmaster cannot be accessed - what does this error message mean?
Even if the orgc directory is in your path, you still have to call zzprep either with its full path, or with its relative path. c:\orgc\zzprep myFile ..\zzprep myFile zprep myFile // not enough, it will causes the above error