FLUIdS
API поиска:
Основные типы и структуры
flu_searcher_t - главная структура API поиска. Каждый вызов API
содержит в качестве первого параметра указатель на эту структуру.
В документации любой экземпляр этой структуры будет именоваться
поисковиком.
Структура flu_searcher_t описывается в заголовочном файле fluidss.h
таким образом:
struct flu_searcher_t
{
struct zcontext_t *context;
unsigned zint_t errorCode;
int allocCount;
/* User info */
flu_searcher_printerror_t printError;
flu_searcher_memfail_t memoryFail;
unsigned int searchArea;
unsigned int searchFlags;
int startNumber;
int resultCount;
void *info;
int step;
const char *query;
/* Index list */
struct flu_searcher_indexfile_t *indexes;
int indexCount;
/* Search data */
struct expression_t *q;
struct ztimeval_t *startTime;
struct ztimeval_t *endTime;
int foundCount;
int printCount;
float maxRank;
/* Main pointer */
struct flu_searcher_data_t *ptr;
};
Не следует напрямую изменять значения полей этой структуры. Для этого
используются вызовы
fluSearcherInit,
fluSearcherSetParams и
fluSearcherSetQuery.
Каждое поле структуры означает следующее:
- struct zcontext_t *context
- Контекст текущей задачи; устанавливается при вызове
fluSearcherInit. Для многопоточных
приложений контекст задачи должен задаваться отдельно для каждого потока,
поэтому один и тот же поисковик не должен применяться в
различных потоках.
- unsigned zint_t errorCode
- Код последней случившейся ошибки. Сами коды (константы zer* и err*)
задаются также в заголовочном файле fluidss.h.
- int allocCount
- Число неотмененных вызовов malloc() и пр. по запросу на выделение памяти.
По окончании работы с поисковиком (т.е. после вызова
fluSearcherFree) должно иметь
нулевое значение. Применяется для контроля за выделением памяти (должен быть
установлен параметр компиляции
ALLOCATION_TEST).
- flu_searcher_printerror_t printError
- Подпрограмма вывода сообщений об ошибках; устанавливается при вызове
fluSearcherInit.
- flu_searcher_memfail_t memoryFail
- Подпрограмма обработки "нештатной" ситуации нехватки свободной
оперативной памяти; устанавливается при вызове
fluSearcherInit.
Обработка подобного события может заключаться, например, в возбуждении
исключительной ситуации.
- unsigned int searchArea
- Область поиска; устанавливается при вызове
fluSearcherSetParams.
- unsigned int searchFlags
- Флаги поиска; устанавливаются при вызове
fluSearcherSetParams.
- int startNumber
- Начальный номер результата поиска, с которого следует начать накопление
результатов поиска (если нумерацию начинать с нуля; иными словами,
startNumber - число первых результатов поиска, которые следует
отбросить).
- int resultCount
- Максимальное число результатов поиска, которые желательно
зарегистрировать; устанавливается при вызове
fluSearcherSetParams.
Реальное число зарегистрированных результатов поиска определяется
printCount.
- void *info
- Пользовательские данные поисковика; устанавливается при вызове
fluSearcherInit. Это могут быть
абсолютно любые данные, которые могут быть востребованы в подпрограммах
printError, memoryFail или printResult.
- int step
- Определяет, на каком этапе поиска находится поисковик. Может
понадобиться при возникновении ошибочных ситуаций (функции printError
и memoryFail).
- step может принимать пять значений:
- const char *query
- Копия пользовательского запроса; устанавливается при вызове
fluSearcherSetQuery.
- struct flu_searcher_indexfile_t *indexes
- Список индексных файлов, участвующих в поиске; устанавливается при вызове
fluSearcherMakeSearch.
- int indexCount
- Число индексных файлов, участвующих в поиске; устанавливается при вызове
fluSearcherMakeSearch.
- struct expression_t *q
- Откомпилированный пользовательский запрос; устанавливается при вызове
fluSearcherSetQuery.
- struct ztimeval_t *startTime
- Указатель на момент времени, в который начался процесс поиска;
устанавливается при вызове
fluSearcherMakeSearch.
- struct ztimeval_t *endTime
- Указатель на момент времени, в который закончился процесс поиска;
устанавливается при вызове
fluSearcherMakeSearch.
- Разница между endTime и startTime составляет время поиска.
- int foundCount
- Общее число результатов поиска, удовлетворяющих пользовательскому
запросу; устанавливается при вызове
fluSearcherMakeSearch.
- int printCount
- Число зарегистрированных результатов поиска (т.е. тех, чей порядковый
номер больше startCount и меньше или равен
startCount + resultCount); устанавливается при вызове
fluSearcherMakeSearch.
- Может равняться нулю, если число результатов поиска меньше или равно
startCount (или они вообще отсутствуют); максимальное значение -
resultCount (если результатов поиска достаточно много).
- Именно это число результатов поиска будет передано вызывами
fluSearcherPrintResults и
fluSearcherNextResult.
- float maxRank
- Максимальный ранг результата поиска (среди всех результатов поиска,
отвечающих пользовательскому запросу); устанавливается при вызове
fluSearcherMakeSearch.
Необходим для нормирования результатов поиска.
- Может равняться нулю, если запросу не отвечает ни один документ в
индекных файлах, участвующих в поиске. Результат поиска с максимальным
рангом не обязан находится в списке регистрируемых результатов поиска.
- struct flu_searcher_data_t *ptr
- Скрытые данные поисковика.
Структура flu_searcher_indexfile_t описывает индексный файл,
участвующий в поиске:
struct flu_searcher_indexfile_t
{
/* Index file */
struct indexfile_t *pif;
Boolean isOpen;
Boolean wasOpen;
Boolean wasError;
/* Other */
int number;
void *info;
int foundCount;
};
Здесь:
- struct indexfile_t *pif
- Структура для низкоуровневых функций, работающих с индексным файлом.
- Boolean isOpen
- Определяет, открыт ли до сих пор этот индексный файл. Не следует
производить каких-либо операций чтения с закрытым файлом :)
- Boolean wasOpen
- Определяет, был ли вообще открыт данный индексный файл. Если был, то
в indexFile сохранились данные заголовка индекса.
- Boolean wasError
- Произошла ли какая-либо ошибка при работе с данным индексом (тогда о
нем лучше всего позабыть).
- int number
- Порядковый номер индекса в списке индексных файлов, участвующих в поиске.
- void *info
- Пользовательские данные, индивидуальные для этого индекса. Если не
заданы, то это поле устанавливается в NULL.
- int foundCount
- Сколько результатов поиска принадлежит именно этому индексу (из общего
числа результатов поиска, отвечающих пользовательскому запросу).
Структура flu_searcher_result_t непосредственно описывает результат
поиска. С экземплярами этой структуры работают вызовы
fluSearcherPrintResults и
fluSearcherNextResult.
Определение структуры представлено ниже:
struct flu_searcher_result_t
{
/* External data */
Boolean wasError;
int number;
struct flu_searcher_indexfile_t *indexFile;
/* Internal data */
int rank;
char *url;
char *title;
char *content;
int urlLength;
int titleLength;
int contentLength;
zoff_t size;
ztime_t lastModified;
Boolean allContent;
};
- Boolean wasError
- Определяет, возникла ли ошибка при чтении данных из индексного файла,
относящихся к данному результату поиска. Если таковая произошла, то из всех
полей структуры flu_searcher_result_t можно полагаться только на
number, indexFile и rank.
- int number
- Порядковый номер результата поиска (в общем списке результатов поиска).
Отсчет ведется от нуля (т.е. самый первый результат поиска имеет номер "ноль").
- struct flu_searcher_indexfile_t *indexFile
- Индексный файл, которому принадлежит данный результат поиска.
- int rank
- Ранг результата поиска. Представляет собой число от 0 до 1000. Чем выше
ранг, тем релевантнее результат поиска запросу.
- char *url
- Интернет-адрес документа, отвечающего результату поиска.
- char *title
- Заглавие документа, отвечающего результату поиска. Представляет собой
пустую строку, если у документа отсутствует заглавие.
-
- char *content
- Фрагмент текта (первые
MAX_CONTENT_LENGTH
значащих символов) документа, отвечающего результату поиска. Представляет
собой пустую строку, если документ пустой или нетекстовый.
- int urlLength
- Длина url в байтах.
- int titleLength
- Длина title в байтах.
- int contentLength
- Длина content в байтах.
- zoff_t size
- Размер документа, отвечающего результату поиска.
- ztime_t lastModified
- Дата последней модификации документа, отвечающего результату поиска.
ztime_t представляет собой битовый массив, с которым работают
макросы zTime* (где * заменяет Year, Month и т.д.)
Сейчас дата последней модификации хранится в индексных файлах как местное
время; предполагается, что в дальнейшем эта дата будет пониматься как
время по Гринвичу.
-
- Boolean allContent
- Определяет, что все содержимое проиндексированного документа,
отвечающего данному результату поиска, помещается в content.
Тип flu_searcher_printerror_t определяет пользовательскую функцию,
которая будет вызываться при возникновении какой-либо ошибки в вызывах API
(кроме ситуации нехватки памяти) - ошибки чтения/записи файлов, некоректности
индекных файлов, ошибок в запросе и т.д. Сама функция обработки ошибок
установливется при инициальзации поисковика (вызов
fluSearcherInit).
Тип определен как
typedef void (*flu_searcher_printerror_t)
(
struct flu_searcher_t *fs,
unsigned zint_t errorCode,
const char *name
);
Первый параметр функции - непосредственно поисковик, поэтому при
написании конкретной функции обработки ошибочных ситуаций возможно
использование собственных данных (поле info
поисковика).
Второй параметр функции - собственно код ошибки, который представляет собой
смесь битов и численого значения кода ошибки. name задает
дополнительный строковый параметр к коду ошибки. Это может быть, например,
имя файла, при работе с которым произошла ошибка.
Сами по себе errorCode и name мало пригодны для написания
функции обработки ошибок. Однако с помощью вызова
fluSearcherErrorString
можно получить строку, описывающую возникшую ошибку, например:
void myPrintError( struct flu_searcher_t *fs, unsigned zint_t errorCode, const char *name)
{
const char *errorString = fluSearcherErrorString( fs, errorCode, name);
fprintf( stderr, "ERROR: %s\n", errorString);
}
Внимание! Вызов
fluSearcherErrorString
можно осуществлять только изнутри printError, поскольку он помимо
name использует дополнительные параметры, запасенные в fs->context,
и которые будут являться действительными только на момент выполнения функции
printError.
flu_searcher_memfail_t задает прототип пользовательской фукнкции,
вызываемой при возникновении ситуации нехватки свободной оперативной памяти:
typedef void (*flu_searcher_memfail_t)
(
struct flu_searcher_t *fs,
const char *name
);
Первый параметр, fs, как обычно, задает поисковик, второй
(name) - имя библиотечной функции, при вызове которой возникла
ситуация нехватки памяти (обычно это malloc). Реакцией на нехватку
памяти может являться, например, возбуждение исключительной ситуации или же
вывод простого сообщения на экран.
Необходимо отметить, что сам поисковик достаточно корректно
обрабатывает подобную ситуацию. В начале каждого вызыва API поиска
сохраняется состояние программы через библиотечную функцию setjmp.
В дальнейшем, при возникновении ситуации нехватки памяти, библиотечная
функция longjmp восстанавливает первоначальное состояние программы,
сигнализируя о возникновении ошибки, и вызов API заканчивается неудачно
(возвращается False с установленным
errorCode в zerNoMemory).
Тип flu_searcher_printresult_t определяет пользовательскую функцию
по выводу данных зарегистрированных результатов поиска (на экран, в память
и пр.):
typedef Boolean (*flu_searcher_printresult_t)
(
struct flu_searcher_t *fs,
struct flu_searcher_result_t *pr
);