/*
* Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:
*
*/
#ifndef CPIX_CPIXINIT_H
#define CPIX_CPIXINIT_H
#include "cpixerror.h"
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* A POV instance that
*
* (a) initializes with the default Cpix runtime parameters
*
* (b) allows getting those values
*
* (c) allows setting those values with sanity checks performed.
*
* The only type of operations allowed before cpix_init() are
* cpix_InitParams creation and property set / get calls.
*/
struct cpix_InitParams_
{
// pointer to native (CLucene/Cpix) impl
void * ptr_;
// Last error, if any, that resulted from executing the
// last operation on this cpix_XXX object
// Use macros cpix_Failed, cpix_Succeeded and cpix_ClearError.
// Do not attempt releasing it.
cpix_Error * err_;
};
typedef cpix_InitParams_ cpix_InitParams;
/**
* Creates a cpix_InitParams instance (that can be used to call
* cpix_init()) that is initialized with the default runtime
* parameters.
*
* @param result error in creating the instance will be
* communicated via this
*
* @return new cpix_InitParams instance that can be used to
* initialize Cpix core.
*
* NOTE: once cpix_init is called, setting any values on the
* cpix_InitParams instance has no effect. The instance can
* (should) be safely destroyed after cpix_init().
*
* NOTE: Obviously, one does not need to set all the parameters,
* only the ones where one wishes to use values different to the
* default ones.
*/
cpix_InitParams * cpix_InitParams_create(cpix_Result * result);
/**
* Destroys this cpix_InitParams instance.
*/
void cpix_InitParams_destroy(cpix_InitParams * thisIp);
/**
* Gets / sets property "cpixDir".
*
* CpixDir is the path to the directory where cpix should store:
*
* (a) cpixreg.txt, the persisted qualified base app class ->
* volume (physical index database) path associations
*
* (b) all the volumes (physical index databases) with automatic
* paths (client does not care where it is)
*
* Must not be NULL or empty string.
*
* Default value is cf DEFAULT_CPIX_DIR in cfg/indevicecfg.h.
*/
const char * cpix_InitParams_getCpixDir(cpix_InitParams * thisIp);
void cpix_InitParams_setCpixDir(cpix_InitParams * thisIp,
const char * value);
/**
* Gets / sets property "resourceDir".
*
* ResourceDir is the path to the directory where cpix should look for:
*
* (a) Localization data
*
* Must not be NULL or empty string.
*
* Default value is cf DEFAULT_CPIX_DIR in cfg/indevicecfg.h.
*/
const char * cpix_InitParams_getResourceDir(cpix_InitParams * thisIp);
void cpix_InitParams_setResourceDir(cpix_InitParams * thisIp,
const char * value);
/**
* Gets / sets property "logFileBase".
*
* LogFileBase the base part of the path to the log file to be
* have the std output and error redirected to. Base: it does not
* have extension. For instance, a value "c:\data\libcpix" will
* produce log files like "c:\data\libcpix_N_log.txt" where N is
* the rotational number (0-4, that is, 5 log files are used
* ever).
*
* May be NULL, in which case no out/err redirection happens and
* nothing is logged to files. It also means that not only logs
* will not happen to log files but not even to STDOUT. If you
* want to have logs to appear on STDOUT but not on logfiles (in
* some console app, or unit test code) use cpix_dbgForceLogs()
* below.
*
* Default is NULL.
*/
const char * cpix_InitParams_getLogFileBase(cpix_InitParams * thisIp);
void cpix_InitParams_setLogFileBase(cpix_InitParams * thisIp,
const char * value);
/**
* Gets / sets property "logSizeLimit".
*
* How big the log files are allowed to grow, if logging occurs at
* all (cf logFileBase property). Actual log file size may be
* bigger, as it is not constantly checked for its size (cf
* property logSizeCheckRecurrency).
*
* Tradeoffs: bigger log files are likely to preserve more
* information (they are being rotated), but consume more disk
* space.
*/
size_t cpix_InitParams_getLogSizeLimit(cpix_InitParams * thisIp);
void cpix_InitParams_setLogSizeLimit(cpix_InitParams * thisIp,
size_t value);
/**
* Gets / sets property "logSizeCheckRecurrency".
*
* How many cpix operations are done between two checkups of log
* file sizes (cf property logSizeLimit), if logging happens at
* all (cf logFileBase property).
*
* Tradeoffs: more frequent checks will make sure that the log
* files don't grow significantly bigger than the limit set by
* property "logSizeLimit", but it slows down Cpix core.
*/
size_t cpix_InitParams_getLogSizeCheckRecurrency(cpix_InitParams * thisIp);
void cpix_InitParams_setLogSizeCheckRecurrency(cpix_InitParams * thisIp,
size_t value);
/**
* Gets / sets property "maxIdleSec".
*
* The time (in seconds) an IdxDb instance can be in an
* uncommitted state unused (idle) until it gets flushed to the
* disk and released (internally). Such flush & release does not
* concern clients (they can still hold active handles to indexes
* and searchers), except maybe the next operation will be slower
* as it requires re-load.
*
* For this setting to have any effect, the cpix_doHousekeeping()
* has to be called regularly.
*
* Tradeoffs: shorter idle time results in possibly more frequent
* disk operations (increased CPU load and battery use), but make
* information loss less likely.
*/
size_t cpix_InitParams_getMaxIdleSec(cpix_InitParams * thisIp);
void cpix_InitParams_setMaxIdleSec(cpix_InitParams * thisIp,
size_t value);
/**
* Gets / sets property "maxInsertBufSize".
*
* The size of insert buffer at which it gets committed to disk.
*
* Tradeoffs: smaller values result in more frequent commits
* (increasing CPU and battery use) but are less likely to lose
* information.
*
* NOTE: cf cpixidxdb.h, cpix_IdxDb_setMaxInsertBufSize() which
* sets the very same value for one particular index (cpix_IdxDb
* instance) only. This here manages the value generally used by
* default.
*/
size_t cpix_InitParams_getMaxInsertBufSize(cpix_InitParams * thisIp);
void cpix_InitParams_setMaxInsertBufSize(cpix_InitParams * thisIp,
size_t value);
/**
* Gets / sets property "insertBufMaxDocs".
*
* The max number of documents in the insert buf writer before it
* commits to its RAM index.
*
* The insert buf is technically an index stored in RAM and a
* writer that writes to it. How frequently the writer should
* commit to that RAM index is controlled by the CLucene
* IndexWriter::maxDocs property.
*
* Tradeoffs: it's kind of difficult to see in what way this
* parameter affects performance, but probably it does affect
* it. Guess: smaller value results in more RAM operations but is
* likely to reduce the peak-usage of RAM memory. To be confirmed
* by tuning tests.
*/
size_t cpix_InitParams_getInsertBufMaxDocs(cpix_InitParams * thisIp);
void cpix_InitParams_setInsertBufMaxDocs(cpix_InitParams * thisIp,
size_t value);
/**
* Gets / sets property "idxJobQueueSize".
*
* Controls how many jobs can be
* placed into the indexing job queue (async API, see
* cpix_async.h), before it gets full. At that point the
* producer thread (single master thread) is blocked until
* there is a job taken out and started processing.
*
* This value should be just big enough to allow ongoing
* harvesting with occasional odd indexing operations without
* blocking the master thread.
*/
size_t cpix_InitParams_getIdxJobQueueSize(cpix_InitParams * thisIp);
void cpix_InitParams_setIdxJobQueueSize(cpix_InitParams * thisIp,
size_t value);
/**
* Gets / sets property "qryJobQueueSize".
*
* Controls how many jobs can be
* placed into the query job queue (async API, see
* cpix_async.h), before it gets full. At that point the
* producer thread (single master thread) is blocked until
* there is a job taken out and started processing.
*
* This value should be just big enough to allow 2-3 clients to
* search simultaneously without blocking the master thread.
*/
size_t cpix_InitParams_getQryJobQueueSize(cpix_InitParams * thisIp);
void cpix_InitParams_setQryJobQueueSize(cpix_InitParams * thisIp,
size_t value);
/**
* Get / sets property "idxThreadPriorityDelta".
*
* Controls the thread priority of the indexer slave (worker)
* thread. Positive value mean increasing thread priority,
* negative value means decreasing it.
*
* NOTE: You have to know how much the default thread priority is
* in your platform, as well as what is the min and max value for
* POSIX thread priority. Cf sched_get_priority_min and
* sched_get_priority_max functions. On Symbian OS / OpenC, the
* min is 0, max is 255 and the default is 100.
*
* NOTE: if two competing threads, that sometimes lock on the same
* resources, have different priority, it is not always clear how
* much actual benefit such thread-prioritization will bring given
* a certain usage pattern. One should try and measure the gains
* of thread-priority settings.
*
* Default thread priority delta is 0, meaning that the thread
* priority of a slave thread is left unchanged.
*/
int cpix_InitParams_getIdxThreadPriorityDelta(cpix_InitParams * thisIp);
void cpix_InitParams_setIdxThreadPriorityDelta(cpix_InitParams * thisIp,
int value);
/**
* Get / sets property "qryThreadPriorityDelta".
*
* See comments above for property "idxThreadPriorityDelta". This
* property does the very same for qry slave thread.
*/
int cpix_InitParams_getQryThreadPriorityDelta(cpix_InitParams * thisIp);
void cpix_InitParams_setQryThreadPriorityDelta(cpix_InitParams * thisIp,
int value);
/**
* Gets / sets property "clHitsPageSize".
*
* Controls how many clucene hit documents are prefetched and
* wrapped in clucene queries (see LuceneHits class in
* cpixhits.h). In order to fetch subsequent documents in an
* environment where indexes can be modified simultaneously
* (overlapped AND concurrent access) re-committing a query can be
* very costly. To reduce the number of roundtrips, hit documents
* are pre-fetched in pages.
*
* Tradeoffs: having a greater page size increases RAM consumption
* but reduces overall time required for full
* search-and-enumerate-all-docs rounds.
*/
size_t cpix_InitParams_getClHitsPageSize(cpix_InitParams * thisIp);
void cpix_InitParams_setClHitsPageSize(cpix_InitParams * thisIp,
size_t value);
/**
* Gets / Sets property "CluceneLockDir".
*
* Clucene lock dir is the path to the directory to have
* the clucene lock dir.
*
* Default is c:\system\temp
*/
const char * cpix_InitParams_getCluceneLockDir(cpix_InitParams * thisIp);
void cpix_InitParams_setCluceneLockDir(cpix_InitParams * thisIp,
const char * value);
/************************************************************************
* General CPix init and shutdown functions.
*
* Initializes the CPix engine. No CPix calls should be made prior
* to initializing it (except the ones that create cpix_InitParams
* instance and set properties of it). With this call, it is
* possible to redirect std out and std err to set of rotating
* logfiles. If opening a logfile at initialization time did not
* succeed, it is as if no logging was specified, and
* initialization will still succeed. If the opening of the first
* logfile succeeds, then std out and std err (console) will be
* shut down, and their output will be redirected to the
* logfile. There is no recovering the console after this point -
* DON'T USE LOGs from console applications, only from daemons /
* servers.
*
* @param result the success or error (with the details) will be
* communicated via this
*
* @param initParams the instance that configures CPix core. May
* be NULL, in which case default initialization parameters
* will be used. The initParams instance can (should) be
* destroyed after a call to cpix_init, any changes made to
* the instance after the cpix_init() call are not taken
* into account.
*
* NOTE: Rotating and/or actual std redirection of logs may fail,
* in which case no logs will be produced.
*/
void cpix_init(cpix_Result * result,
cpix_InitParams * initParams);
/**
* Shuts down the CPix engine. No CPix calls can be made one
* it has been shut down.
*/
void cpix_shutdown();
/**
* @returns the version (and/or) revision of this CPix library.
*/
const char * cpix_version();
/**
* Performs regular housekeeping activities, like flushing and
* releasing resources associated to idle idx handles.
*/
void cpix_doHousekeeping();
/**
* For logging levels.
*/
enum cpix_LogLevel
{
CPIX_LL_ERROR = 0,
CPIX_LL_WARNING,
CPIX_LL_TRACE,
CPIX_LL_DEBUG
};
/**
* Sets the loglevel. Default is CPIX_LL_TRACE.
*
* @param logLevel the new log level.
*
* @return the current log level
*/
cpix_LogLevel cpix_setLogLevel(cpix_LogLevel logLevel);
/**
* If 'logFileBase' property given to cpix_InitParams at
* cpix_init() time was the default NULL, then no logging occurs
* at all. Now, some unit test code may want to re-enable logging
* (that happens to STDOUT) even if there is no
* log-redirection. By calling this function you can force CPix to
* send logs to STDOUT (even if they are not redirected to log
* files).
*
* Cf cpix_InitParams_getLogFileBase().
*/
void cpix_dbgForceLogs();
/**
* Dumps the internal state to the logs, with CPIX_LL_TRACE
* loglevel.
*
* NOTE: This function is NOT to be used in production code, with
* ASYNC API. It can deadlock the process. So use it only in
* console / regression tests in contexts where it cannot do harm.
*/
void cpix_dbgDumpState();
// See clucene/src/CLucene/debug/lucenebase.h and memtracking.cpp.
// This function relies on the modifications enabled over there.
#define DBG_MEM_USAGE 1
#ifdef DBG_MEM_USAGE
/**
* For debug / development / performance measurement
* purposes. Assumes CLucene being compiled with the DBG_MEM_USAGE
* flag (modification by us), which, when enabled, uses the
* already overloaded "operator new" operators to update the
* largest amount of dynamic memory in use.
*
* @returns the largest amount of dynamic memory in use since this
* process was started or since the last call to
* cpix_dbgResetMemUsage - based on the overloaded "operator new"
* stuff done in CLucene.
*/
uint32_t cpix_dbgPeakDynMemUsage();
/**
* For debug / development / performance measurement
* purposes. Resets the static global variable that stores the
* greatest amount of heap used snice the beginning of the process
* or the previous call to cpix_dbgResetMemUsage();
*/
void cpix_dbgResetDynMemUsage();
#endif
#ifdef __cplusplus
} /* extern "C" */
#endif /* __cplusplus */
#endif /* CPIX_CPIXINIT_H */