xapian-core/include/xapian/constants.h

   1 /** @file constants.h
   2  * @brief Constants in the Xapian namespace
   3  */
   4 /* Copyright (C) 2012,2013,2014,2015,2016 Olly Betts
   5  *
   6  * This program is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU General Public License as
   8  * published by the Free Software Foundation; either version 2 of the
   9  * License, or (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program; if not, write to the Free Software
  18  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301
  19  * USA
  20  */
  21
  22 #ifndef XAPIAN_INCLUDED_CONSTANTS_H
  23 #define XAPIAN_INCLUDED_CONSTANTS_H
  24
  25 #if !defined XAPIAN_IN_XAPIAN_H && !defined XAPIAN_LIB_BUILD
  26 # error "Never use <xapian/constants.h> directly; include <xapian.h> instead."
  27 #endif
  28
  29 namespace Xapian {
  30
  31 /** Create database if it doesn't already exist.
  32  *
  33  *  If no opening mode is specified, this is the default.
  34  */
  35 const int DB_CREATE_OR_OPEN      = 0x00;
  36
  37 /** Create database if it doesn't already exist, or overwrite if it does. */
  38 const int DB_CREATE_OR_OVERWRITE = 0x01;
  39
  40 /** Create a new database.
  41  *
  42  *  If the database already exists, an exception will be thrown.
  43  */
  44 const int DB_CREATE              = 0x02;
  45
  46 /** Open an existing database.
  47  *
  48  *  If the database doesn't exist, an exception will be thrown.
  49  */
  50 const int DB_OPEN                = 0x03;
  51
  52 #ifdef XAPIAN_LIB_BUILD
  53 /** @internal Bit mask for action codes. */
  54 const int DB_ACTION_MASK_        = 0x03;
  55 #endif
  56
  57 /** Don't attempt to ensure changes have hit disk.
  58  *
  59  *  By default, Xapian ask the OS to ensure changes have hit disk (by calling
  60  *  fdatasync(), fsync() or similar functions).  If these calls do their job,
  61  *  this should mean that when WritableDatabase::commit() returns, the changes
  62  *  are durable, but this comes at a performance cost, and if you don't mind
  63  *  losing changes in the case of a crash, power failure, etc, then this option
  64  *  can speed up indexing significantly.
  65  */
  66 const int DB_NO_SYNC             = 0x04;
  67
  68 /** Try to ensure changes are really written to disk.
  69  *
  70  *  Generally fsync() and similar functions only ensure that data has been sent
  71  *  to the drive.  Modern drives have large write-back caches for performance,
  72  *  and a power failure could still lose data which is in the write-back cache
  73  *  waiting to be written.
  74  *
  75  *  Some platforms provide a way to ensure data has actually been written and
  76  *  setting DB_FULL_SYNC will attempt to do so where possible.  The downside is
  77  *  that committing changes takes longer, and other I/O to the same disk may be
  78  *  delayed too.
  79  *
  80  *  Currently only Mac OS X is supported, and only on some filing system types
  81  *  - if not supported, Xapian will use fsync() or similar instead.
  82  */
  83 const int DB_FULL_SYNC           = 0x08;
  84
  85 /** Update the database in-place.
  86  *
  87  *  Xapian's disk-based backends use block-based storage, with copy-on-write
  88  *  to allow the previous revision to be searched while a new revision forms.
  89  *
  90  *  This option means changed blocks get written back over the top of the
  91  *  old version.  The benefits of this are that less I/O is required during
  92  *  indexing, and the result of indexing is more compact.  The downsides are
  93  *  that you can't concurrently search while indexing, transactions can't be
  94  *  cancelled, and if indexing ends uncleanly (i.e. without commit() or
  95  *  WritableDatabase's destructor being called) then the database won't be
  96  *  usable.
  97  *
  98  *  Currently all the base files will be removed upon the first modification,
  99  *  and new base files will be written upon commit.  This prevents new
 100  *  readers from opening the database while it unsafe to do so, but there's
 101  *  not currently a mechanism in Xapian to handle notifying existing readers.
 102  */
 103 const int DB_DANGEROUS           = 0x10;
 104
 105 /** When creating a database, don't create a termlist table.
 106  *
 107  *  For backends which support it (currently glass), this will prevent creation
 108  *  of a termlist table.  This saves on the disk space that would be needed to
 109  *  store it, and the CPU and I/O needed to update it, but some features either
 110  *  inherently need the termlist table, or the current implementation of them
 111  *  requires it.
 112  *
 113  *  The following probably can't be sensibly implemented without it:
 114  *
 115  *   - Database::termlist_begin()
 116  *   - Document::termlist_begin()
 117  *   - Document::termlist_count()
 118  *   - Enquire::get_eset()
 119  *
 120  *  And the following currently require it:
 121  *
 122  *   - Enquire::matching_terms_begin() - we could record this information
 123  *     during the match, though it might be hard to do without a speed penalty.
 124  *   - WritableDatabase::delete_document() - we could allow this with inexact
 125  *     statistics (like how Lucene does).
 126  *   - WritableDatabase::replace_document() if the document exists already
 127  *     (again, possible with inexact statistics).
 128  *   - Currently the list of which values are used in each document is stored
 129  *     in the termlist table, so things like iterating the values in a document
 130  *     require it (which is probably reasonable since iterating the terms in
 131  *     a document requires it).
 132  *
 133  *  You can also convert an existing database to not have a termlist table
 134  *  by simply deleting termlist.*.
 135  */
 136 const int DB_NO_TERMLIST         = 0x20;
 137
 138 /** If the database is already locked, retry the lock.
 139  *
 140  *  By default, if the database is already locked by a writer, trying to
 141  *  open it again for writing will fail by throwing Xapian::DatabaseLockError.
 142  *  If this flag is specified, then Xapian will instead wait for the lock
 143  *  (indefinitely, unless it gets an error trying to do so).
 144  */
 145 const int DB_RETRY_LOCK          = 0x40;
 146
 147 /** Use the glass backend.
 148  *
 149  *  When opening a WritableDatabase, this means create a glass database if a
 150  *  new database is created.  If there's an existing database (of any type)
 151  *  at the specified path, this flag has no effect.
 152  *
 153  *  When opening a Database, this flag means to only open it if it's a glass
 154  *  database.  There's rarely a good reason to do this - it's mostly provided
 155  *  as equivalent functionality to that provided by the namespaced open()
 156  *  functions in Xapian 1.2.
 157  */
 158 const int DB_BACKEND_GLASS       = 0x100;
 159
 160 /** Use the chert backend.
 161  *
 162  *  When opening a WritableDatabase, this means create a chert database if a
 163  *  new database is created.  If there's an existing database (of any type)
 164  *  at the specified path, this flag has no effect.
 165  *
 166  *  When opening a Database, this flag means to only open it if it's a chert
 167  *  database.  There's rarely a good reason to do this - it's mostly provided
 168  *  as equivalent functionality to Xapian::Chert::open() in Xapian 1.2.
 169  */
 170 const int DB_BACKEND_CHERT       = 0x200;
 171
 172 /** Open a stub database file.
 173  *
 174  *  When opening a Database, this flag means to only open it if it's a stub
 175  *  database file.  There's rarely a good reason to do this - it's mostly
 176  *  provided as equivalent functionality to Xapian::Auto::open_stub() in
 177  *  Xapian 1.2.
 178  */
 179 const int DB_BACKEND_STUB        = 0x300;
 180
 181 /** Use the "in memory" backend.
 182  *
 183  *  The filename is currently ignored when this flag is used, but an empty
 184  *  string should be passed to allow for future expansion.
 185  *
 186  *  A new empty database is created, so when creating a Database object this
 187  *  creates an empty read-only database - sometimes useful to avoid special
 188  *  casing this situation, but otherwise of limited use.  It's more useful
 189  *  when creating a WritableDatabase object, though beware that the current
 190  *  inmemory backend implementation was not built for performance and
 191  *  scalability.
 192  *
 193  *  This provides an equivalent to Xapian::InMemory::open() in Xapian 1.2.
 194  */
 195 const int DB_BACKEND_INMEMORY    = 0x400;
 196
 197 #ifdef XAPIAN_LIB_BUILD
 198 /** @internal Bit mask for backend codes. */
 199 const int DB_BACKEND_MASK_       = 0x700;
 200
 201 /** @internal Used internally to signify opening read-only. */
 202 const int DB_READONLY_           = -1;
 203 #endif
 204
 205
 206 /** Show a short-format display of the B-tree contents.
 207  *
 208  *  For use with Xapian::Database::check().
 209  */
 210 const int DBCHECK_SHORT_TREE = 1;
 211
 212 /** Show a full display of the B-tree contents.
 213  *
 214  *  For use with Xapian::Database::check().
 215  */
 216 const int DBCHECK_FULL_TREE = 2;
 217
 218 /** Show the bitmap for the B-tree.
 219  *
 220  *  For use with Xapian::Database::check().
 221  */
 222 const int DBCHECK_SHOW_FREELIST = 4;
 223
 224 /** Show statistics for the B-tree.
 225  *
 226  *  For use with Xapian::Database::check().
 227  */
 228 const int DBCHECK_SHOW_STATS = 8;
 229
 230 /** Fix problems.
 231  *
 232  *  For use with Xapian::Database::check().
 233  *
 234  *  Currently this is supported for chert, and will:
 235  *
 236  *  @li regenerate the "iamchert" file if it isn't valid (so if it is lost, you
 237  *      can just create it empty and then "fix problems").
 238  *
 239  *  @li regenerate base files (currently the algorithm for finding the root
 240  *      block may not work if there was a change partly written but not
 241  *      committed).
 242  */
 243 const int DBCHECK_FIX = 16;
 244
 245
 246 /** Use the same document ids in the output as in the input(s).
 247  *
 248  *  By default compaction renumbers the document ids in the output database,
 249  *  currently by applying the same offset to all the document ids in a
 250  *  particular source database.  If this flag is specified, then this
 251  *  renumbering doesn't happen, but all the document ids must be unique over
 252  *  all source databases.  Currently the ranges of document ids in each source
 253  *  must not overlap either, though this restriction may be removed in the
 254  *  future.
 255  */
 256 const int DBCOMPACT_NO_RENUMBER = 4;
 257
 258 /** If merging more than 3 databases, merge the postlists in multiple passes.
 259  *
 260  *  This is generally faster but requires more disk space for temporary files.
 261  */
 262 const int DBCOMPACT_MULTIPASS = 8;
 263
 264 /** Produce a single-file database.
 265  *
 266  *  Only supported by the glass backend currently.
 267  */
 268 const int DBCOMPACT_SINGLE_FILE = 16;
 269
 270 /** Assume document id is valid.
 271  *
 272  *  By default, Database::get_document() checks that the document id passed is
 273  *  actually in use and throws DocNotFoundError if not.  This flag can be used
 274  *  to disable this check - useful to save a bit of work when you know for sure
 275  *  that the document id is valid.
 276  *
 277  *  Some database backends may check anyway - the remote backend currently
 278  *  does.
 279  */
 280 const int DOC_ASSUME_VALID = 1;
 281
 282 }
 283
 284 #endif /* XAPIAN_INCLUDED_CONSTANTS_H */