25.1. Обзор

25.1. Обзор

qdbm предлагает несколько различных API-интерфейсов. Самый основной из них, Depot, является низкоуровневым API, который мы и рассмотрим в этой главе. Интерфейс Curia позволяет разбивать базу данных на несколько файлов (для повышения масштабируемости или с целью работы в файловой системе с ограничениями), а функции Villa предлагают две модели: модель B-деревьев и модель транзакций. API-интерфейс Odeon позволяет работать с инвертированными индексами[175]. Два последних API, Relic и Hovel, предлагают реализацию таких интерфейсов, как ndbm и qdbm.

Функции Depot обеспечивают выполнение основных операций по схеме "ключ-значение", при этом ключ используется для извлечения значения. Ключ и значение представляют собой произвольные бинарные потоки, размер которых передается отдельно от данных; библиотеке ничего не нужно знать об их структуре. Однако у интерфейса Depot имеется пара функциональных средств, благодаря которым применение строк в качестве ключей и элементов данных становится более удобным. Во-первых, всякий раз при передаче размера ключа или элемента данных в библиотеку вместо них может быть передано значение -1, на основании которого Depot будет использовать функцию strlen() для вычисления используемого размера. Во-вторых, большинство функций чтения ключей и элементов данных автоматически добавляют к возвращаемому значению байт 0. Этот дополнительный символ не включается в возвращаемый размер, поэтому его можно проигнорировать, если значение не является строкой. Если же это строка, то возвращаемое значение может быть обработано как строка, и приложению не нужно будет завершать ее с помощью NULL.

Depot использует глобальную целочисленную переменную dpecode для хранения кодов ошибок. Когда функции Depot возвращают сбой, dpecode сообщает о том, что произошло (это почти то же самое, что и в случае с переменной errno, которая относится к системным вызовам и библиотеке С). За текстовые сообщения об ошибках отвечает функция dperrmsg().

#include <depot.h>

const char * dperrmsg(int ecode);

Подобно strerror(), функция dperrmsg() принимает код ошибки (обычно из dpecode) и возвращает строку, в которой приводится описание возникшей ошибки.

Функции в API-интерфейсе Depot используют указатель на структуру DEPOT. Это непрозрачная структура (программы, использующие Depot, не могут самостоятельно проверять значения в структуре), однако в ней содержится вся информация, используемая библиотекой для обслуживания файла, хранящегося на диске.