PMEMKV — хранилище данных «ключ-значение» для постоянной памяти

Содержание:

1. NAME
2. DESCRIPTION
3. ENGINES
4. BINDINGS
5. SEE ALSO

NAME

pmemkv — хранилище данных типа «ключ-значение», оптимизированное для постоянной памяти. Предоставляет нативный C API и заголовки C++. Поддержка других языков описана в разделе BINDINGS ниже.

Оно имеет несколько механизмов хранения, каждый из которых оптимизирован для разных сценариев использования. Они различаются по реализации и возможностям:

• Постоянство. Это компромисс между сохранением данных и производительностью. Постоянные механизмы сохраняют своё содержимое и устойчивы к сбоям питания и сбоям системы, но работают медленнее. Нестойкие механизмы работают быстрее, но сохраняют своё содержимое только до закрытия базы данных (или сбоя приложения; сбоя питания).

• Параллелизм. Механизмы обеспечивают разную степень масштабируемости записи в многопоточных рабочих нагрузках. Параллельные механизмы поддерживают неблокирующие выборки и в среднем высокомасштабируемые обновления. Подробности см. в описании отдельных механизмов.

• Упорядочивание ключей. «Сортированные» механизмы поддерживают запросы выше или ниже заданного ключа. Большинство сортированных механизмов также поддерживают передачу пользовательского объекта компаратора (см. libpmemkv_config(3)). По умолчанию pmemkv хранит элементы в двоичном порядке (сравнение выполняется с использованием функции, эквивалентной std::string::compare).

Постоянные механизмы обычно используют libpmemobj++ и PMDK для доступа к NVDIMM. Они могут работать с файлами в файловой системе DAX (fsdax) или устройстве DAX.

ENGINES

Наиболее зрелый и рекомендуемый механизм для постоянных сценариев использования — это cmap. Он обеспечивает хорошие результаты производительности и стабильность.

Каждый механизм можно вручную включить и выключить во время сборки, используя параметры CMake. Все перечисленные здесь механизмы включены и готовы к использованию.

Для настройки механизма используется pmemkv_config (libpmemkv_config(3)). Ниже приведён список механизмов вместе с параметрами конфигурации, которые они ожидают. Каждый параметр имеет соответствующую функцию (pmemkv_config_put_path, pmemkv_config_put_comparator и т. д.), которая гарантирует безопасность типов. Например, чтобы вставить параметр path в конфигурацию, пользователь должен вызвать pmemkv_config_put_path(). В некоторых случаях, например при создании конфигурации из проанализированного ввода, может быть удобнее вставлять параметры по их типу, а не по имени. Каждый параметр имеет определённый тип и может быть вставлен в конфигурацию с помощью соответствующей функции (pmemkv_config_put_string, pmemkv_config_put_int64 и т.д.). Например, для вставки параметра типа string можно использовать функцию pmemkv_config_put_string. Эти два способа вставки параметров в конфигурацию можно использовать взаимозаменяемо.

Описание основного API pmemkv см. в libpmemkv(3).

cmap

Постоянный параллельный механизм, поддерживаемый хэш-картой, которая позволяет вызывать get, put и remove одновременно из нескольких потоков и обеспечивает хорошую масштабируемость. Остальные методы (например, методы запроса диапазона) не являются потокобезопасными и не должны вызываться более чем из одного потока. Данные, хранящиеся с использованием этого механизма, являются постоянными и гарантированно будут согласованными в случае любого прерывания (сбой / потеря питания и т. д.).

Внутренне этот механизм использует постоянную параллельную хэш-карту и постоянную строку из библиотеки libpmemobj-cpp (подробности см. https://github.com/pmem/libpmemobj-cpp). Постоянная строка используется как тип ключа и значения. Функции механизма не должны быть... Конфигурация параметров движка

Вызывается в рамках транзакций libpmemobj (некорректный вызов пользователем приведёт к исключению).

Этому движку требуются следующие параметры конфигурации (подробную информацию о том, как их задать, см. в libpmemkv_config(3)):

• path — путь к файлу базы данных или к файлу пул сета (подробнее см. poolset(5)). Обратите внимание, что при использовании файла пул сета размер должен быть равен 0. Он используется для открытия или создания пула (макет «pmemkv»).
  • тип: строка;
• create_if_missing — если 1, pmemkv пытается открыть пул и, если это не удаётся, создаёт его. Если 0, pmemkv будет полагаться на настройку флага create_or_error_if_exists. Если оба флага create_* будут равны false — pmemkv откроет пул (если только путь не существует — тогда произойдёт сбой).
  • тип: uint64_t;
  • значение по умолчанию: 0;
• create_or_error_if_exists — если 1, pmemkv создаёт файл (но произойдёт сбой, если путь существует). Если 0, pmemkv будет полагаться на настройку флага create_if_missing. Если оба флага create_* будут равны false — pmemkv откроет пул (если только путь не существует — тогда произойдёт сбой).
  • тип: uint64_t;
  • значение по умолчанию: 0;
• size — требуется только в том случае, если любой из вышеуказанных флагов равен 1. Указывает размер базы данных [в байтах] для создания.
  • тип: uint64_t;
  • минимальное значение: 8388608 (8 МБ);
• oid — указатель на oid (для получения подробной информации см. libpmemobj(7)), который указывает на данные движка. Если oid равен нулю, движок выделит новые данные, в противном случае он будет использовать существующие.
  • тип: объект.

В следующей таблице показаны четыре возможные комбинации параметров (где «-» означает «не может быть установлен»):

ad 1: если ни один из флагов не установлен (значение по умолчанию равно false), pmemkv только попытается открыть файл и произойдёт сбой, если путь не существует. Размер игнорируется.

ad 2: если флаг create_if_missing установлен, pmemkv попытается открыть файл (на основе пути) и, если ему это не удастся, попытается создать файл. Флаг create_or_error_if_exists не может быть установлен (или он должен быть установлен в 0).

ad 3: если установлен флаг create_or_error_if_exists, pmemkv попытается создать файл (и произойдёт сбой, если он существует). Флаг create_if_missing не может быть установлен (или он должен быть установлен в 0).

ad 4: если oid установлен, путь не должен быть установлен. Оба флага и размер игнорируются.

Файл базы данных или файл пул сета также можно создать с помощью утилиты pmempool (см. pmempool-create(1)). При использовании pmempool create «pmemkv» следует передавать в качестве макета для движка cmap, а «pmemkv_<имя_движка>» — для других движков (например, «pmemkv_stree» для движка stree). Поддерживаются только пулы PMEMOBJ.

vcmap

Неустойчивый параллельный движок, поддерживаемый memkind. Данные, записанные с использованием этого движка, теряются после закрытия базы данных.

Этот движок построен на основе структуры данных tbb::concurrent_hash_map и использует PMEM C++ allocator для выделения памяти. В качестве типа ключа и значения используется std::basic_string. Требуются пакеты Memkind и TBB.

Этому движку требуются следующие параметры конфигурации (подробную информацию о том, как их установить, см. в libpmemkv_config(3)):

• path — путь к существующему каталогу;
  • тип: string;
• size — указывает размер базы данных [в байтах];
  • тип: uint64_t;
  • минимальное значение: 8388608 (8МБ).

vsmap

Неустойчивый однопоточный отсортированный движок, поддерживаемый memkind. Данные, записанные с использованием этого движка, теряются после закрытия базы данных.

Этот движок основан на std::map и использует PMEM C++ allocator для выделения памяти. В качестве типа ключа и значения используется std::basic_string. Требуется пакет Memkind.

Этому движку требуются следующие параметры конфигурации (подробную информацию о том, как их настроить, см. в libpmemkv_config(3)):

• path — путь к существующему каталогу;
  • тип: string;
• size — указывает размер... База данных [в байтах]
  • тип: uint64_t
  • минимальное значение: 8388608 (8 МБ)
• comparator — (необязательно) указанный компаратор, используемый механизмом
  • тип: объект

blackhole

Неустойчивый механизм, который принимает неограниченное количество данных, но никогда ничего не возвращает. Внутренне blackhole не использует постоянный пул или какую-либо устойчивую структуру. Предназначение этого механизма — профилирование и настройка высокоуровневых привязок, а также аналогичные случаи, когда постоянство следует намеренно пропустить. Дополнительные пакеты не требуются. Поддерживаемых параметров конфигурации нет.

Экспериментальные механизмы

Также есть и другие механизмы на разных стадиях разработки, подробнее см. https://github.com/pmem/pmemkv/blob/master/doc/ENGINES-experimental.md. Некоторые из них (radix, tree3, stree и csmap) требуют параметры конфигурации, такие как cmap, и, аналогично cmap, их не следует использовать в рамках транзакции(й) libpmemobj.

Привязки

Привязки для других языков доступны на GitHub. В настоящее время они поддерживают только подмножество нативного API.

Существующие привязки:

• Java — подробнее см. https://github.com/pmem/pmemkv-java

• Node.js — подробнее см. https://github.com/pmem/pmemkv-nodejs

• Python — подробнее см. https://github.com/pmem/pmemkv-python

• Ruby — подробнее см. https://github.com/pmem/pmemkv-ruby

См. также

libpmemkv(3), libpmemkv_config(3), libpmemkv_iterator(3), pmempool(1), libpmemobj(7) и https://pmem.io