include/idzebra/isam.h

   1 /* $Id: isam.h,v 1.2 2005-01-15 19:38:24 adam Exp $
   2    Copyright (C) 1995-2005
   3    Index Data ApS
   4
   5 This file is part of the Zebra server.
   6
   7 Zebra is free software; you can redistribute it and/or modify it under
   8 the terms of the GNU General Public License as published by the Free
   9 Software Foundation; either version 2, or (at your option) any later
  10 version.
  11
  12 Zebra is distributed in the hope that it will be useful, but WITHOUT ANY
  13 WARRANTY; without even the implied warranty of MERCHANTABILITY or
  14 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  15 for more details.
  16
  17 You should have received a copy of the GNU General Public License
  18 along with Zebra; see the file LICENSE.zebra.  If not, write to the
  19 Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
  20 02111-1307, USA.
  21 */
  22
  23 /**
  24 isam.h - a generalized interface to the isam systems
  25
  26 The isam system consists of a number of isam lists. Physically it is
  27 stored in a file, or a group of related files. It is typically used
  28 for storing all the occurrences of a given word, storing the document
  29 number and position for each occurrence.
  30
  31 An isam list is indentified by an isam_position. This is a number (zint).
  32 It can be seen as a mapping from an isam_position to an ordered list of isam_
  33 entries.
  34
  35 An isam list consists of one or more isam entries. We do not know the
  36 structure of those entries, but we know the (maximum) size of such, and
  37 that they can be memcpy'ed around.
  38
  39 The entries can be seen to consist of a key and a value, although we
  40 have no idea of their internal structure. We know that we have a compare
  41 function that can look at a part (or whole) of the isam entry (the 'key').
  42 The part not looked at (if any) will count as 'value' or 'payload'.
  43
  44 The entries are stored in increasing order (as defined by the compare
  45 function), and no duplicates are allowed.
  46
  47 There is an effective mass-insert routine that takes a stream of values,
  48 each accompanied by an insert/delete flag.
  49
  50 For reading we have cursors, that can read through an isam list in order.
  51 They have a fast-forward function to skip values we are not interested in.
  52
  53 */
  54
  55
  56 #ifndef ISAM_H
  57 #define ISAM_H
  58
  59 #include <idzebra/bfile.h>
  60
  61 #ifdef __cplusplus
  62 extern "C" {
  63 #endif
  64
  65
  66 /**
  67  * key_control contains all there is to know about the keys (entries) stored
  68  * in an isam, (and therefore operated by the rsets). Other than this info,
  69  * all we assume is that all keys are the same size, and they can be
  70  * memcpy'd around.
  71  */
  72 struct key_control {
  73     /** (max) size of a key */
  74     int key_size;
  75
  76     /** Default for what level we operate on (book/chapter/verse).
  77      * for typical zebra, this is always 2 (sysno/seqno). Not used in
  78      * isam context, but the rsets make use of this. */
  79     int scope;
  80
  81     /** Compare function, returning -1,0,1, if p1 is less/equal/greater
  82      * than p2 */
  83     int (*cmp) (const void *p1, const void *p2);
  84
  85     /** Debug function to write a key in the log, with a message */
  86     void (*key_logdump_txt) (int logmask, const void *p, const char *txt);
  87
  88     /** Return the sequence number of a key, to see if we are on the same
  89      * record. FIXME - this makes less sense with higher-scope keys. */
  90     zint (*getseq)(const void *p);
  91
  92     /** Codec to pack key values into a disk page (delta-compression etc) */
  93     ISAM_CODEC *codec;
  94 };
  95
  96 typedef struct key_control KEY_CONTROL;
  97
  98 const KEY_CONTROL *default_key_control();
  99   /* FIXME - in zrpn.c, time being. Needs to be moved out */
 100
 101
 102 /** isam_data_stream is a callback function for the mass-insert (merge)
 103  * it provides another item to insert/delete, in proper order */
 104 struct isam_data_stream {
 105     int (*read_item)(void *clientData, char **dst, int *insertMode);
 106     void *clientData;
 107 };
 108
 109 typedef struct isam_data_stram ISAM_DATA_STREAM;
 110
 111
 112 /** ISAM_POS is a number the ISAM translates from */
 113 typedef zint ISAM_POS;
 114
 115 /** ISAM is a translation from POS to a set of values */
 116 typedef struct ISAM_s *ISAM;
 117
 118 /** ISAM_CUR is a pointer into an ISAM */
 119 typedef struct ISAM_CUR_s *ISAM_CUR;
 120
 121 /** isam_control is the interface to the operations an ISAM supports */
 122 struct isam_conrol {
 123     /** text description of the type, for debugging */
 124     char *desc;
 125     /** default filename, if none given to isam_open */
 126     const char *def_filename;
 127
 128     /* there is an isam_open function, but it is not part of this */
 129     /* dynamic table, as it is what provides this table */
 130
 131     /** close the isam system */
 132     void (*f_close)(ISAM i);
 133
 134     /** Insert an entry into the isam identified by pos. If pos==0,
 135      * create a new isam list */
 136     ISAM_POS (*f_put)(ISAM is, ISAM_POS pos, const void *buf);
 137
 138     /** Locate and delete an entry from an isam list. If not there
 139      * do nothing, and return 0*/
 140     int (*f_del)(ISAM is, ISAM_POS pos, const void *buf);
 141
 142     /** Find an entry in the isam list. return 0 if not found. buf must
 143      * contain enough to identify the item, and will be overwritten by it */
 144     int (*f_get)(ISAM is, ISAM_POS pos, void *buf );
 145
 146     /** Mass-insert data from incoming stream into the isam */
 147     ISAM_POS (*f_merge)(ISAM is, ISAM_POS pos, ISAM_DATA_STREAM *data);
 148
 149     /** Open a cursor to the isam list identified by pos */
 150     ISAM_CUR (*f_cur_open)(ISAM is, ISAM_POS pos);
 151
 152     /** Read an item at the cursor (and forward to next). return 0 at eof */
 153     int (*f_read)(ISAM_CUR cur, void *buf);
 154
 155     /** Forward until item >= untilbuf, and read that item. Skips effectively*/
 156     int (*f_forward)(ISAM_CUR cur, void *buf, const void *untilbuf);
 157
 158     /** Get (an estimate of) the current position and total size of the entry*/
 159     void (*f_pos)(ISAM_CUR cur, double *current, double *total);
 160
 161     /** Close a cursor */
 162     void (*f_cur_close)(ISAM_CUR cur);
 163
 164     /** Delete the isam list from the isam system.*/
 165     int (*f_unlink)(ISAM is, ISAM_POS pos);
 166
 167 };
 168
 169 /** ISAM_s is the generic isam structure */
 170 struct ISAM_s {
 171     const struct isam_control *ictrl;  /* the functions */
 172     const KEY_CONTROL *kctrl; /* all about the keys stored in the isam */
 173     BFiles bfs;  /* The underlying block file system */
 174     void *priv; /* various types of ISAMs hand their private parts here */
 175 };
 176
 177 /** ISAM_CUR is a cursor to an ISAM, used for reading the next value, etc. */
 178 struct ISAM_CUR {
 179     ISAM is;
 180     void *priv;
 181 };
 182
 183
 184
 185 /** Open the isam system */
 186 ISAM isam_open (BFiles bfs,
 187                 const char *isamtype, /* usually "b" */
 188                 const char *filename,  /* optional, use default from control ?? */
 189                 int flags, /* FIXME - define read/write, and some special ones */
 190                 const KEY_CONTROL *key_control);
 191
 192
 193 /** Shortcut defines to access the functions through the key_control block */
 194
 195 #define isam_close(is) (*(is)->ictrl->f_close)(is)
 196
 197 #define isam_puf(is,pos,buf) (*(is)->ictrl->f_put)((is),(pos)(buf))
 198
 199 #define isam_del(is,pos,buf) (*(is)->ictrl->f_del)((is),(pos)(buf))
 200
 201 #define isam_get(is,pos,buf) (*(is)->ictrl->f_get)((is),(pos)(buf))
 202
 203 #define isam_merge(is,pos,data) (*(is)->ictrl->f_merge)((is),(pos)(data))
 204
 205 #define isam_cur_open(is,pos) (*(is)->ictrl->f_cur_open)((is),(pos))
 206
 207 #define isam_read(cur,buf) (*(is)->ictrl->f_read)((cur),(buf))
 208
 209 #define isam_forward(cur,buf,untilbuf) (*(is)->ictrl->f_forward)((cur),(buf)(untilbuf))
 210
 211 #define isam_pos(cur,current,total) (*(is)->ictrl->f_pos)((cur),(current),(total))
 212
 213 #define isam_cur_close(cur) (*(is)->ictrl->f_cur_close)(cur)
 214
 215 #define isam_unlink(is,pos) (*(is)->ictrl->f_unlink)((is),(pos))
 216
 217
 218 #ifdef __cplusplus
 219 }
 220 #endif
 221
 222 #endif  /* ISAM_H */