fastdb.htm

用于嵌入式环境的数据库

A cursor for class T contains an instance of class T, used for fetching the
current record. That is why table classes should have a default constructor
(constructor without parameters), which has no side effects. 
FastDB optimizes fetching records from the database, copying only data from
fixed parts of the object. String bodies are not copied, instead
of this  the correspondent field points directly into the database. The same is
true for arrays: their components have the same representation in the
database as in the application (arrays of scalar types or arrays of nested 
structures of scalar components).<P>

An application should not change
elements of strings and arrays in a database directly.
When an array method needs to update an array body,
it creates an in-memory copy of the array and updates this 
copy. If the programmer wants to update a string field, she/he should assign
to the pointer a new value, 
but don't change the string directly in the database.
It is recommended to use the <code>char const*</code> type instead of the
<code>char*</code> type for string components, 
to enable the compiler to detect the illegal usage of strings.<P>

The cursor class provides the 
<code>get()</code> method for obtaining a pointer to 
the current record (stored inside the cursor). Also the overloaded 
'<code>operator-&gt;</code>'
can be used to access components of the current record.
If a cursor is opened for update,
the current record can be changed and stored in the database
by the <code>update()</code> method or can be removed.
If the current record is removed, the next record becomes the
current. If there is no next record, then the previous record
(if it exists)  becomes the current. The method <code>removeAll()</code>
removes all records in the table.
Whereas the method <code>removeAllSelected</code> only removes 
all records selected by the cursor.<P>

When records are updated, the size of the database may increase.
Thus an extension of the database section in the virtual memory 
is needed. As a result of such remapping, base addresses of the section can be
changed and all pointers to database fields kept by applications will become 
invalid. FastDB automatically updates current records in all opened 
cursors when a database section is remapped. So, when a database is updated, 
the programmer should access record fields only through the cursor 
<code>-&gt;</code> method. She/he should  not use pointer variables.<P>

Memory used for the current selection can be released by the
<code>reset()</code> method.
This method is automatically called by the <code>select(), 
dbDatabase::commit(), dbDatabase::rollback()</code> methods
and the cursor destructor, so in most cases there is no need to
call the <code>reset()</code> method explicitly.<P>

Cursors can also be used to access records by reference. The method
<code>at(dbReference&lt;T&gt; const& ref)</code> sets the cursor to the record
pointed to by the reference. In this case, the selection consists exactly of
one record and the <code>next(), prev()</code> methods will always return 
<code>NULL</code>. Since cursors and references in FastDB are strictly 
typed, all necessary checking can be done statically by the compiler and 
no dynamic type checking is needed. The only kind of checking,
which is done at runtime, is checking for null references.
The object identifier of the current record in the cursor can be obtained by
the <code>currentId()</code> method.<P> 

It is possible to restrict the number of records returned by a select statement.
The cursor class has the two methods
<code>setSelectionLimit(size_t lim)</code> and
<code>unsetSelectionLimit()</code>,
which can be used to set/unset the limit
of numbers of records returned by the query. In some situations,
a  programmer may want to receive
only one record or only few first records;  so the query execution
time and size of consumed memory can be reduced by limiting the size of 
selection. But if you specify an order for selected records, 
the query with the restriction to 
<I>k</I> records will not return the first <I>k</I> records
with the smallest value of the key. Instead of this, arbitrary <I>k</I>
records will be taken and then sorted.<P>

So all operations with database data can be performed by means of
cursors. The only exception is the insert operation, for which 
FastDB provides an overloaded insert function:

<PRE>
        template&lt;class T&gt;
        dbReference&lt;T&gt; insert(T const& record);
</PRE>

This function will insert a record at the end of the table and return
a reference of the created object.
The order of insertion is strictly specified in FastDB
and applications can use this assumption about the record order in the
table. For applications widely using references for navigation between
objects, it is necessary to have some <I>root</I> object, from which a
traversal by references can be made. A good candidate for such root object
is the first record in the table (it is also the oldest record in the 
table). This record can be accessed by execution of the <code>select()</code>
method without parameter. The current record in the cursor will
be the first record in the table.<P>


The C++ API of FastDB defines a special <code>null</code> variable
of reference type.
It is possible to compare the <code>null</code> variable with references 
or assign it to the reference:<P>

<PRE>
        void update(dbReference&lt;Contract&gt; c) {
            if (c != null) { 
	        dbCursor&lt;Contract&gt; contract(dbCursorForUpdate);
		contract.at(c);
		contract-&gt;supplier = null;
            }
        }
</PRE>

<A NAME="relative-parameter-binding">
Query parameters usually are bound to C++ variables. In most cases in is convenient and 
flexible mechanism. But in multithreaded application, there is no warranty that the same 
query will not be executed at the same moment of time by another thread with different values
of parameters. One solution is to use synchronization primitives (critical sections or mutexes)
to prevent concurrent execution of the query. But this will lead to performance degradation.
FastDB is able to perform read requests in parallel, increasing total system throughput.
The other solution is to use delayed parameter binding. This approach is illustrated by the 
following example:<P>  

<PRE>
dbQuery q;

struct QueryParams { 
    int         salary;
    int         age;
    int         rank;
};

void open()
{
    QueryParams* params = (QueryParams*)NULL;
    q = "salary > ", params->salary, "and age < ", params->age, "and rank =", params->rank;
}

void find(int salary, int age, int rank) 
{ 
    QueryParams params;
    params.salary = salary;
    params.age = age;
    params.rank = rank;
    dbCursor&lt;Person&gt; cusor;
    if (cursor.select(q, &params) &gt; 0) { 
        do { 
	    cout &lt;&lt; cursor->name &lt;&lt; NL;
        } while (cursor.next());
    }
}
</PRE>

So in this example function <code>open</code> binds query parameters just to offsets of 
fields in structure. Later in <code>find</code> functions, actual pointer to the structure
with parameters is passed to the <code>select</code> structure. Function <code>find</code>
can be concurrently executed by several threads and only one compiled version of the query
is used by all these threads. This mechanism is available since version 2.25.<P>
</A>

<H3><A NAME = "database">Database</A></H3>
The class <code>dbDatabase</code> controls the application interactions
with the database. It performs synchronization of concurrent accesses to the
database, transaction management, memory allocation, error handling,...<P>

The constructor of <code>dbDatabase</code> objects allows programmers to specify
some database parameters:

<PRE>
    dbDatabase(dbAccessType type = dbAllAccess,
	       size_t dbInitSize = dbDefaultInitDatabaseSize,
	       size_t dbExtensionQuantum = dbDefaultExtensionQuantum,
	       size_t dbInitIndexSize = dbDefaultInitIndexSize,
	       int nThreads = 1);
</PRE>

The following database access type are supported:<P>

<TABLE BORDER>
<TR><TH>Access type</TH><TH>Description</TH></TR>
<TR><TD><code>dbDatabase::dbReadOnly</code></TD><TD>Read only mode</TD></TR>
<TR><TD><code>dbDatabase::dbAllAccess</code></TD><TD>Normal mode</TD></TR>
<TR><TD><code>dbDatabase::dbConcurrentRead</code></TD><TD>Read only mode in which application can access the database 
concurrently with application updating the same database in <code>dbConcurrentUpdate</code> mode</TD></TR>
<TR><TD><code>dbDatabase::dbConcurrentUpdate</code></TD><TD>Mode to be used in conjunction with
<code>dbConcurrentRead</code> to perform updates in the database without blocking read applications for a long time</TD></TR>
</TABLE><P>

When the database is opened in readonly  mode, no new class definitions can be added to the database and definitions
of existing classes and indices can not be altered.<P>

<code>dbConcurrentUpdate</code> and <code>dbConcurrentRead</code> modes should be used together when 
database is mostly accessed in readonly mode and updates should not block readers for a long time. 
In this mode update of the database can be performed concurrently with read accesses (readers will not see 
changed data until transaction is committed). Only at update transaction commit time, exclusive lock is set
but immediately released after incremental change of the current object index.<P>

So you can start one or more  applications using <code>dbConcurrentRead</code> mode and all their read-only
transactions will be executed concurrently. You can also start one or more applications using 
 <code>dbConcurrentUpdate</code> mode. All transactions of such applications will be synchronized using additional
global mutex. So all these transactions (even read-only) will be executed exclusively. But transactions of the application
running in <code>dbConcurrentUpdate</code> mode can run concurrently with transaction of applications
running in <code>dbConcurrentRead</code> mode! Please look at <code>testconc.cpp</code> example, 
illustrating usage of these modes<P>

<B>Attension!</B> Do not mix <code>dbConcurrentUpdate</code> and <code>dbConcurrentRead</code> 
mode with other modes and do not use them together in one process (so it is
not possible to start two threads in one of which open database in
dbConcurrentUpdate mode and in other - in dbConcurrentRead). Do not 
use <code>dbDatabase::precommit</code> method in <code>dbConcurrentUpdate</code> mode.<P>

The parameter <code>dbInitSize</code> specifies the initial size of the database file.
The database file increases on demand; setting the initial size can only 
reduce the number of reallocations (which can take a lot of time).
In the current implementation of the FastDB database
the size is at least doubled at each extension.
The default value of this parameter is 4 megabytes.<P>

The parameter <code>dbExtensionQuantum</code>
specifies the quantum of extension of the
memory allocation bitmap. 
Briefly speaking, the value of this parameter specifies how much memory
will be allocated sequentially without attempt to reuse space of
deallocated objects. The default value of this parameter is 4 Mb.
See section <A HREF="#memory">Memory allocation</A> for more details.<P> 

The parameter <code>dbInitIndexSize</code> specifies the initial index size. 
All objects in FastDB are accessed through an object index.
There are two copies of this object index:
current and committed. Object indices are reallocated on 
demand; setting an initial index size can only reduce (or increase)
the number of reallocations. The default value of this parameter is 64K object 
identifiers.<P>

And the last parameter <code>nThreads</code> controls the level of query
parallelization. If it is greater than 1, then FastDB can start the parallel
execution of some queries (including sorting the result). 
The specified number of parallel threads will
be spawned by the FastDB engine in this case. Usually it does not make
sense to specify the value of this parameter to be greater than the
number of online CPUs in the system. It is also possible to pass zero
as the value of this parameter. In this case, FastDB will automatically detect
the number of online CPUs in the system. The number of threads also can be set 
by the <code>dbDatabase::setConcurrency</code> method at any moment of time.<P>

The class <code>dbDatabase</code> contains a static field 
<code>dbParallelScanThreshold</code>, which specifies a threshold for the
number of records in the table after which query parallelization
is used. The default value of this parameter is 1000.<P>

The database can be opened by the
<code>open(char const* databaseName, char const* fileName = NULL, unsigned waitLockTimeout = INFINITE)</code> method.
If the file name parameter is omitted, it is constructed from
the database name by appending the ".fdb" suffix. The database name should
be an arbitrary identifier consisting of any symbols except '\'.
The last parameter <code>waitLockTimeout</code> can be set to prevent locking of all
active processes working with the database when some of them is crashed.
If the crashed process had locked the database, then no other process can continue 
execution. To prevent it, you can specify maximal delay for waiting for the lock, 
after expiration of which system will try to perform recovery and continue execution
of active processes.
The method&nbsp;<code>open</code> returns <code>true</code> if the database was
successfully opened; or <code>false</code> if the open operation failed. 
In the last case, the database <code>handleError</code> method is called with a
<code>DatabaseOpenError</code> error code. A database session can be terminated
by the <code>close</code> method, which implicitly commits current transactions.<P>

In a multithreaded application each thread, which wants to access the database,
should first be attached to it. The method <code>dbDatabase::attach()</code>
allocates thread specific data and attaches the thread to the database.
This method is automatically called by the <code>open()</code> method, so
there is no reason to call the <code>attach()</code> method for the thread,
which opens the database. When the thread finishes work with the database, it should
call the <code>dbDatabase::detach()</code> method. The method 
<code>close</code> automatically invokes the <code>detach()</code> method. 
The method <code>detach()</code> implicitly commits current transactions.
An attempt to access a database by a detached thread causes an assertion f