% AUTORIGHTS
% Copyright (C) 2007 Princeton University
%       
% This file is part of Ferret Toolkit.
% 
% Ferret Toolkit is free software; you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation; either version 2, or (at your option)
% any later version.
% 
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
% 
% You should have received a copy of the GNU General Public License
% along with this program; if not, write to the Free Software Foundation,
% Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
\section {Storage Interface}
We provide a storage interface (datalog) which support append-only/read many
operations. The main user of the storage interface is the cass\_table
and cass\_map, where the items are appended to the storage in a
sequential order. We will also need to have checkpointing and
recovery capability. Note: The checkpoint/recovery information are
stored in the cass\_env rather than the datalog. 

\subsection {Checkpointing}
The checkpointing is done in the following manner: we would only support
checkpointing the full system. The checkpoint is done whenever the
system need to do so. (For the current sample application
implementation, we will checkpoint the system after every successful
import of feature file. So when the end user issued an import command,
the system will not return until the import and checkpointing is
successful. This way, the user will know easily where to restart if
the import failed.)

When the checkpointing is needed, the management code will freeze the
whole system and start checkpointing process. It will sync all
cass\_tables, cass\_maps to datalog and record the current maxlsn and
etc; it will save all the indexes to disk\_locx and 
finally it will save the management information to disk\_locx. The next
checkpoint will checkpoint all the cass\_tables, cass\_map, save
the indexes and management information to disk\_locy. By alternate the
disk\_locx and disk\_locy, we can always pick up the latest clean copy
and restore the full system to that stage. 

After all data are checkpointed (synced to disk), the cass\_env is
saved to a temporary file and ``atomically'' switched to a statically
defined file name called ``cass\_env.dat'' using rename system
call. This way the cass\_env.dat is always pointing to the latest
sucessful checkpoint. Upon system startup, we will check the
cass\_env, and restore the system to the consistent state.

\subsection {Storage API}
\begin{verbatim}
/*
 * All log records must be less than DataLogItemMax in size.
 *
 * All functions returning an int return 0 on success and -1 on
 failure.
 *
 * DataLogclose closes at log handle.
 * DataLogtruncate truncates the log to the specified LSN.
 * DataLogappend appends a cass_datum_t to the log and sets the new LSN.
 * DataLogmaxlsn returns the current maximum LSN.
 *
 * Mkdatalogiter creates a new log iterator; datalogiterclose closes
 it.
 * Datalogitersetlsn positions a log iterator at the specified LSN.
 * Datalogiternext returns the next log record and associated LSN.
 */
enum {
        DataLogVersion  = 1,
        DataLogItemMax  = 1<<22,
};

DataLog         *datalogopen(int omode, char *fname, int cr, 
                  void (*panic)(char*, ...), uint64_t lsn, uint64_t offset);
int             datalogclose(DataLog*);
int             datalogsync(DataLog*);  // Sync datalog to disk.
int             datalogtruncate(DataLog*, uint64_t offset);
int             datalogappend(DataLog*, cass_datum_t* data);
int             datalogmaxlsn(DataLog*, uint64_t* lsn, uint64_t* offset);
                  // Return current LSN and offset.

DataLogIter     *mkdatalogiter(DataLog*);
void            datalogiterclose(DataLogIter*);
//int           datalogitersetlsn(DataLogIter*, uint64_t); // Not supported.
int             datalogiternext(DataLogIter*, uint64_t*, cass_datum_t*);
\end{verbatim}