API.md

RC-singularity API

версия 1.0.x

[[TOC]]

Управление конфигурацией

Структура конфигурации отвечает за такие параметры, как путь к дисковым копиям, флаги соединения по умолчанию, разделитель столбцов в значениях при создании набора. Также в нем сохраняется текстовое сообщение о последней ошибке при создании/подключении набора.

sing_config_get_default

FSingConfig *sing_config_get_default(void) 

создает конфигурацию по умолчанию из файла /etc/rc_singularity.cnf. Если не найден - создает пустую конфигурацию.
Возвращаемое значение:
Возвращает структуру конфигурации для подключения или создания наборов данных. Может вернуть NULL, если не удается выделить память.

sing_config_get_empty

FSingConfig *sing_config_get_empty(void)

создает пустую конфигурацию: без флагов, копии в рабочей директории, разделитель - табуляция.
Возвращаемое значение:
Возвращает структуру конфигурации для подключения или создания наборов данных. Может вернуть NULL, если не удается выделить память.

sing_config_get_error

const char *sing_config_get_error(FSingConfig *config)

Параметры:
config - конфигурация
Возвращаемое значение:
Возвращает указатель на буфер с текстом ошибки создания или подключения набора данных (нуль-завершенная строка)

sing_config_set_connection_flags

void sing_config_set_connection_flags(FSingConfig *config,unsigned flags)

задает флаги соединения. Ничем не отличается от задания их в вызове соединения
Параметры:
config - конфигурация
flags - флаги соединения (см. sing_link_set)

sing_config_set_value_delimiter

void sing_config_set_value_delimiter(FSingConfig *config,char delimiter)

задает разделитель столбцов для хранения значений внутри набора (при парсинге CSV файлов указанный для файла разделитель будет заменяться на этот символ)
Параметры:
config - конфигурация
delimiter - символ разделения столбцов

sing_config_set_base_path

void sing_config_set_base_path(FSingConfig *config,const char *base_path)

задает путь к дисковым копиям данных для разделяемых наборов.
Параметры:
config - конфигурация
base_path - относительный или абсолютный путь к директории. Слеш в конце допустим но не обязателен.

sing_delete_config

void sing_delete_config(FSingConfig *config)

удаляет конфигурацию и освобождает память.
Параметры:
config - конфигурация. После вызова невалиден.

Создание, подключение и удаление key-value наборов данных

Если набор удаляется из памяти целиком каким-либо процессом (пересоздание, выгрузка, удаление), все остальные подключенные к нему процессы при первом вызове API пробуют переподключиться, и в случае неудачи (дисковой копии нет или удалена), вернут ошибку SING_ERROR_CONNECTION_LOST. Для переподключения будут использованы те-же флаги SING_CF_.., что и при имеющемся подключении.
Несколько одновременных подключений к одному и тому-же набору в одном потоке вызывает неопределенное поведение. Несколько подключений в разных потоках одного процесса допустимо, тогда они рассматриваются библиотекой как разные процессы.

sing_create_set

FSingSet *sing_create_set(const char *setname,const char *codec,const FSingCSVFile *csv_file,unsigned keys_count,unsigned flags,unsigned lock_mode,FSingConfig *config)

создает новый kv-набор данных.
Параметры:
setname - имя набора для разделенного доступа. Если не задано (NULL), набор недоступен для других процессов (приватный набор данных). Если задано, набор доступен для локальных процессов на машине под этим именем (разделяемый набор данных).
codec - имя используемого кодека. NULL - используется встроенный кодек [A-Z0-9-.]
csv_file - описание csv файла с данными, используемыми для инициализации набора. См. работа с файлами. Может быть NULL, в этом случае набор создается пустым.
keys_count - планируемое количество ключей. Если указано 0 и задан csv файл, число ключей будет примерно определено по его содержанию. Если указано меньше 512 или 0 и csv-файл не задан, таблица будет иметь место для 512 ключей.
flags - флаги из следующего списка:
Флаги набора

• SING_UF_COUNTERS - создать счетчики для ускорения сравнивания наборов. Этот флаг значительно ускоряет поиск различий между двумя наборами ценой небольшого замедления операций модификации. Если сравнивание набора на регулярной основе не планируется, устанавливать его не надо.
• SING_UF_NOT_PERSISTENT - не создавать дисковую копию набора. Этот флаг имеет смысл только для разделяемых наборов, для приватных он установлен по умолчанию. Наборы, созданные с этим флагом:
  • не сохранятся после выключения машины и выгрузки из памяти. Вызов sing_unload_set уничтожает набор.
  • для них недоступно восстановление после ошибок.
  • операции модификации выполняются быстрее (без учета времени самой синхронизации с диском)
  • используют 1 открытый файловый дескриптор (без флага 3 открытых дескриптора)
• SING_UF_PHANTOM_KEYS - набор может содержать удаленные (фантомные) ключи и фантомные значения в обычных ключах - может описывать разницу между двумя состояниями. Это полезно для схлопывания списков последовательных изменений набора в один без наличия исходного состояния. Для такого набора недоступна операция сравнения с другим набором.

Флаги подключения - cм. sing_link_set:

• SING_CF_MULTICORE_PARSE
• SING_CF_PARSE_ERRORS
• SING_CF_FULL_LOAD
• SING_CF_READER
• SING_CF_UNLOAD_ON_CLOSE
• SING_CF_KEEP_LOCK

lock-mode - режим блокировок, в котором будет использоваться данный набор. См. Режимы блокировок
0 - дефолтный режим, SING_LM_SIMPLE для разделенных наборов и SING_LM_NONE для приватных
config - указатель на конфигурацию. Данные конфигурации копируются, структура может быть переиспользована для других наборов. Может быть NULL, в этом случае будет использована дефолтная конфигурация (при создании/подключении нескольких наборов это приведет к избыточному перечитыванию конфигурационного файла) и не будет возможности диагностировать причину ошибки.
Возвращаемое значение:
Возвращает структуру подключения в случае успеха. В случае ошибки возвращает NULL и текстовое описание ошибки в config, которое можно получить вызовом sing_config_get_error (это удобно для диагностики неверных путей к файлам и т.п.)

sing_link_set

FSingSet *sing_link_set(const char *setname,unsigned flags,FSingConfig *config)

подключается к существующему разделяемому набору данных.
Параметры:
setname - имя набора. Обязательный.
flags - флаги подключения из следующего списка (набор флагов складывается с флагами config):

• SING_CF_MULTICORE_PARSE - допустимо использовать дополнительные потоки при парсинге файлов. Вызовы работы с файлами (в т.ч. sing_create_set) будут выполняться быстрее.
• SING_CF_PARSE_ERRORS - выводить в STDERR сообщения о строках, в которых не удалось распарсить ключ.
• SING_CF_FULL_LOAD - если набора нет в памяти, загрузить с дисковой копии целиком. Другие процессы, пытающиеся подключиться к набору, будут ожидать окончания операции. Без этого флага данные с диска грузятся по необходимости, что снижает время старта и нагрузку на диск.
• SING_CF_READER - открытие в режиме только для чтения, с уменьшением количества открытых файловых дескрипторов. Флаг SING_CF_FULL_LOAD устанавливается автоматически. На набор используется 1 дескриптор. Модифицирующие вызовы возвращают ошибку. Флаг полезен когда много процессов читают из большого количества небольших наборов.
• SING_CF_UNLOAD_ON_CLOSE - выгрузить набор из памяти при отключении. Несовместим с флагом SING_CF_READER
• SING_CF_KEEP_LOCK - сохранить эксклюзивную блокировку (sing_lock_W) на наборе после завершения. При создании позволяет выполнить ряд операций с набором до того, как он станет доступен другим пользователям. При подключении просто накладывает блокировку. Несовместим с флагом SING_CF_READER и режимами SING_LM_READ_ONLY и SING_LM_NONE

config - указатель на конфигурацию. См. sing_create_set
Возвращаемое значение
Возвращает структуру подключения в случае успеха. В случае ошибки возвращает NULL и текстовое описание ошибки в config, которое можно получить вызовом sing_config_get_error

sing_unlink_set

void sing_unlink_set(FSingSet *kvset)

отключается от набора данных. Разделяемый набор при этом остается в памяти машины, приватный набор данных уничтожается. Если на наборе есть блокировка sing_lock_W, она снимается, и выполняется откат к дисковой копии при ее наличии (это удобно для отмены изменений при обработке исключений). Если подключение создавалось с флагом SING_CF_UNLOAD_ON_CLOSE, вызов аналогичен sing_unload_set.
Параметры:
kvset - подключенный набор данных. После вызова невалиден.

sing_unload_set

int sing_unload_set(FSingSet *kvset)

выгружает разделяемый набор данных из памяти машины (наборы, созданные без дисковой копии уничтожаются). Если на наборе есть блокировка sing_lock_W, она снимается, и выполняется откат к дисковой копии при ее наличии (это удобно для отмены изменений при обработке исключений). Эта операция невозможна при подключении с флагом CF_READER
Параметры:
kvset - подключенный набор данных. После вызова невалиден.
Возвращаемые значения:
0 - успех
SING_ERROR_DATA_CORRUPTED - обнаружен сбой, дисковой копии нет или откат к ней выполнить не удалось
SING_ERROR_IMPOSSIBLE_OPERATION - подключение только для чтения
SING_ERROR_CONNECTION_LOST - набор удален
SING_ERROR_SYNC_FAILED - не удается завершить синхронизацию с диском после предыдущей операции

sing_delete_set

int sing_delete_set(FSingSet *kvset)

выгружает разделяемый набор данных из памяти машины и удаляет дисковую копию, если она есть. В остальном аналогична sing_unload_set.
Параметры:
kvset - подключенный набор данных. После вызова невалиден.
Возвращаемые значения:
0 - успех
SING_ERROR_IMPOSSIBLE_OPERATION - подключение только для чтения
SING_ERROR_CONNECTION_LOST - набор удален

Работа с блокировками, синхронизация с диском

sing_lock_W

int sing_lock_W(FSingSet *kvset)
int sing_try_lock_W(FSingSet *kvset)

sing_lock_W накладывает эксклюзивную блокировку записи для вызывающего процесса (в режиме SING_LM_FAST - треда). Для режимов SING_LM_SIMPLE и SING_LM_PROTECTED если предыдущий владелец не освободил блокировку и завершился, откатывается к дисковой копии (или досохраняет данные в дисковую копию, если тот завершился во время синхронизации с диском). Выполняет группировку операций между накладыванием и снятием блокировки в одну транзакцию, которая затем может быть сохранена на диск или откачена. В SING_LM_PROTECTED вызов является обязательным для доступа тредов этого процесса к операциям записи (все операции записи ожидают получения эксклюзивной блокировки одним из тредов) и не синхронизирует треды между собой. В SING_LM_FAST вызов синхронизирует и треды и процессы. В SING_LM_NONE вызов возвращает ошибку. См. Режимы блокировок
sing_try_lock_W не ожидает снятия чужой эксклюзивной блокировки, а возвращает SING_RESULT_LOCKED
Параметры:
kvset - подключенный набор данных.
Возвращаемые значения:
0 - успех
SING_RESULT_LOCKED - возвращает sing_try_lock_W, если набор заблокирован другим процессом/тредом.
SING_ERROR_DATA_CORRUPTED - обнаружен сбой, дисковой копии нет или откат к ней выполнить не удалось
SING_ERROR_IMPOSSIBLE_OPERATION - набор или подключение только для чтения, либо попытка выполнить повторную блокировку, либо sing_lock_W в режиме SING_LM_NONE
SING_ERROR_CONNECTION_LOST - набор удален
SING_ERROR_SYNC_FAILED - не удается завершить синхронизацию с диском после предыдущей операции

sing_unlock_commit

int sing_unlock_commit(FSingSet *kvset,uint32_t *saved)

Выполняет синхронизацию с дисковой копией, если она есть, и снимает блокировку, наложенную sing_lock_W.
Параметры:
kvset - подключенный набор данных.
saved - указатель на беззнаковое целое, в котором сохраняется размер сохраненных на диск данных в килобайтах. Может быть NULL.
Возвращаемые значения:
0 - успех
SING_ERROR_IMPOSSIBLE_OPERATION - набор не был заблокирован, либо попытка снять блокировку другим тредом.
SING_ERROR_SYNC_FAILED - сбой при синхронизации с диском (возможно кончилось место на диске). Синхронизация может быть завершена любым другим процессом, пока набор находится в памяти. После выгрузки из памяти использование набора станет невозможным.

sing_unlock_revert

int sing_unlock_revert(FSingSet *kvset)

Выполняет откат к дисковой копии, если она есть, и снимает блокировку, наложенную sing_lock_W.
Параметры:
kvset - подключенный набор данных.
Возвращаемые значения:
0 - успех
SING_ERROR_IMPOSSIBLE_OPERATION - у набора нет дисковой копии либо он не был заблокирован ранее, либо попытка снять блокировку другим тредом.
SING_ERROR_INTERNAL - не удалось выполнить чтение данных с диска. Использование набора невозможно

sing_flush

int sing_flush(FSingSet *kvset,uint32_t *saved)

Выполняет синхронизацию с диском для режимов SING_LM_FAST и SING_LM_NONE. В остальных возвращает ошибку. В режиме SING_LM_FAST конкурентные модифицирующие вызовы блокируются на время сихронизации.
Параметры:
kvset - подключенный набор данных.
saved - указатель на беззнаковое целое, в котором сохраняется размер сохраненных на диск данных в килобайтах. Может быть NULL.
Возвращаемые значения:
0 - успех
SING_ERROR_CONNECTION_LOST - набор удален
SING_ERROR_IMPOSSIBLE_OPERATION - у набора нет дисковой копии или режим не SING_LM_FAST и не SING_LM_NONE, или подключение только для чтения, или набор заблокирован sing_lock_W.
SING_ERROR_SYNC_FAILED - сбой при синхронизации с диском (возможно кончилось место на диске). Синхронизация может быть завершена любым другим процессом, пока набор находится в памяти. После выгрузки из памяти использование набора станет невозможным.

sing_revert

int sing_revert(FSingSet *kvset)

Выполняет откат к дисковой копии, если она есть, в режимах SING_LM_FAST и SING_LM_NONE. В остальных возвращает ошибку. В режиме SING_LM_FAST конкурентные модифицирующие вызовы блокируются на время сихронизации.
Параметры:
kvset - подключенный набор данных.
Возвращаемые значения:
0 - успех
SING_ERROR_CONNECTION_LOST - набор удален
SING_ERROR_IMPOSSIBLE_OPERATION - у набора нет дисковой копии или режим не SING_LM_FAST и не SING_LM_NONE, или подключение только для чтения, или набор заблокирован sing_lock_W.
SING_ERROR_INTERNAL - не удалось выполнить чтение данных с диска. Использование набора невозможно

Служебные вызовы

sing_total_count

unsigned sing_total_count(FSingSet *kvset)

Параметры:
kvset - подключенный набор данных.
Возвращаемое значение:
Количество ключей в наборе. Для наборов с фантомами, удаленные также считаются.

sing_get_error

const char *sing_get_error(FSingSet *kvset)

Параметры:
kvset - подключенный набор данных.
Возвращаемое значение:
Возвращает последнюю текстовую ошибку

sing_get_memsize

unsigned sing_get_memsize(FSingSet *kvset)

Возвращает размер набора в памяти в килобайтах. Для разделенных наборов это количество использованной разделенной памяти, для приватных - памяти процесса. Кроме того в обоих случаях на набор расходуется около 100Кб в памяти процесса.
Параметры:
kvset - подключенный набор данных.
Возвращаемое значение:
Размер набора в памяти в килобайтах.

sing_check_set

int sing_check_set(FSingSet *kvset)

Выполняет полную проверку консистентности набора данных.
Параметры:
kvset - подключенный набор данных.
Возвращаемые значения:
0 - ошибок не обнаружено
1 - обнаружена ошибка, ее описание можно получить вызовом sing_get_error

sing_get_mode

unsigned sing_get_mode(FSingSet *kvset)  

Возвращает режим блокировок набора
Параметры:
kvset - подключенный набор данных.
Возвращаемое значение:
режим блокировок набора

sing_unload_on_close

int sing_unload_on_close(FSingSet *kvset)  

Устанавливает или снимает флаг SING_CF_UNLOAD_ON_CLOSE Параметры:
kvset - подключенный набор данных.
Возвращаемые значения:
0 - успех
SING_ERROR_IMPOSSIBLE_OPERATION - установлен флаг SING_CF_READER.

Работа с файлами

Файлы представляют собой либо наборы данных (csv,tsv и др), либо разницу между наборами (diff файлы). В последнем случае перед ключом стоит символ операции. Возможные символы:
"+" - ключ был добавлен
"-" - ключ был удален
"=" - ключ был изменен на это значение.
"!" - ключ был изменен с этого значения.
Используя такую запись можно как добавлять так и вычитать diff файлы к наборам, переходя между различными состояниями.
Все вызовы работы с файлами допускают параллельную модификацию набора, если это разрешено режимом блокировок (для SING_LM_PROTECTED из потоков того-же процесса, для SING_LM_FAST из любых потоков, для SING_LM_NONE параллельная модификация хоть и разрешена технически но приведет к повреждению данных). Дамп является читающим вызовом и разрешает ее безусловно, для ее запрета (только для других процессов) необходимо вручную вызвать sing_lock_W
Исключение составляют вызовы sing_diff_... и sing_intersect_, которые могут выполняться только в одном экземпляре в единицу времени (ожидают завершения предыдущего).
При обнаружении нехватки памяти (SING_ERROR_NO_SET_MEMORY) при операциях с файлами в режиме SING_LM_SIMPLE и наличии дисковой копии, будет выполнен автоматический возврат к ней. Если дисковой копии нет, набор останется частично измененным.

sing_add_file, sing_sub_file

int sing_add_file(FSingSet kvset,const FSingCSVFile csv_file)
int sing_sub_file(FSingSet kvset,const FSingCSVFile csv_file)

sing_add_file добавляет данные из файла в набор. Если ключ начинается с символа "-" - он удаляется из набора, ключи с символами "+" и "=" в начале и без символа операции добавляются, с символом "!" не обрабатываются. Если ключ уже есть в наборе, данные меняются на данные из файла. sing_sub_file инвертирует операции (добавляет ключи с "-" и "!", игнорирует с "=", удаляет остальные)
В наборах с фантомами удаление ключа создает фантомный ключ со следующими данными в порядке приоритета: имеющееся фантомное, имеющееся нормальное, данные из файла), добавление уже существующего ключа запоминает его старое значение как фантомное, если фантомного в нем нет. Другими словами самое старое из доступных в момент операции значений становится фантомным, самое новое - обычным.
Параметры:
kvset - подключенный набор данных.
csv_file - имя и формат csv файла.
Возвращаемые значения:
0 - успех
SING_ERROR_NO_SET_MEMORY - не удается выделить страницу для новых данных. Для разделяемых наборов это происходит из-за нехватки места в tmpfs (/dev/shm). Для приватных - нехватка оперативной памяти
SING_ERROR_FILE_NOT_FOUND - не удается открыть CSV файл для чтения
SING_ERROR_CONNECTION_LOST - набор удален

sing_remove_file

int sing_remove_file(FSingSet *kvset,const FSingCSVFile *csv_file);

sing_remove_file удаляет из набора все ключи из файла (если файл в diff-формате, символ операции игнорируется). Удаляются и обычные ключи и фантомные. Это полезно, чтобы убрать изменения определенных ключей из diff-файла, представленного как набор с фантомами.
Параметры:
kvset - подключенный набор данных.
csv_file - имя и формат csv файла.
Возвращаемые значения:
0 - успех
SING_ERROR_FILE_NOT_FOUND - не удается открыть CSV файл для чтения
SING_ERROR_CONNECTION_LOST - набор удален

sing_diff_file, sing_diff_replace_file

int sing_diff_file(FSingSet *kvset,const FSingCSVFile *csv_file,const char *outfile)
int sing_diff_replace_file(FSingSet *kvset,const FSingCSVFile *csv_file,const char *outfile)

sing_diff_file сравнивает содержание набора с csv файлом и выводит разницу. Со знаком минус выводятся ключи и значения, которые есть в наборе но нет в файле, со знаком плюс - которые есть в файле но нет в наборе. Если данные отличаются значением - будут выведены две строки - с "!" и "=".
sing_diff_replace_file аналогична sing_diff_file но заменяет содержимое набора на содержимое файла.
Вызовы недоступны для наборов с фантомными ключами.
Параметры:
kvset - подключенный набор данных.
csv_file - имя и формат csv файла.
outfile - файл для сохранения результата сравнения (если NULL - будет выведен в STDOUT)
Возвращаемые значения:
0 - успех
SING_ERROR_NO_MEMORY - не удалось выделить память для служебных структур.
SING_ERROR_NO_SET_MEMORY - не удается выделить страницу для новых данных. Эта ошибка может возникнуть в процессе загрузки недостающих данных из дисковой копии.
SING_ERROR_FILE_NOT_FOUND - не удается открыть CSV файл для чтения
SING_ERROR_IMPOSSIBLE_OPERATION - набор с фантомными ключами
SING_ERROR_OUTPUT_NOT_FOUND - не удается открыть файл outfile для записи
SING_ERROR_CONNECTION_LOST - набор удален

sing_intersect_file, sing_intersect_replace_file

int sing_intersect_file(FSingSet *kvset,const FSingCSVFile *csv_file)
int sing_intersect_replace_file(FSingSet *kvset,const FSingCSVFile *csv_file)

вызовы удаляют из набора ключи, которых нет в файле. sing_intersect_file оставляет значения из данных набора, а sing_intersect_replace_file заменяет значения на данные из файла. Вызовы недоступны для наборов с фантомными ключами.
Параметры:
kvset - подключенный набор данных.
csv_file - имя и формат csv файла.
Возвращаемые значения:
0 - успех
SING_ERROR_NO_MEMORY - не удалось выделить память для служебных структур.
SING_ERROR_NO_SET_MEMORY - не удается выделить страницу для новых данных.
SING_ERROR_FILE_NOT_FOUND - не удается открыть CSV файл для чтения
SING_ERROR_IMPOSSIBLE_OPERATION - набор с фантомными ключами
SING_ERROR_OUTPUT_NOT_FOUND - не удается открыть файл outfile для записи
SING_ERROR_CONNECTION_LOST - набор удален

sing_dump

int sing_dump(FSingSet *kvset,const char *outfile)

записывает содержание набора в файл.
Параметры:
kvset - подключенный набор данных.
outfile - файл для сохранения результата сравнения (если NULL - будет выведен в STDOUT) Набор с фантомными ключами выводится в diff формате (см. Работа с файлами).
Возвращаемые значения:
0 - успех
SING_ERROR_NO_SET_MEMORY - не удается выделить страницу для новых данных. Эта ошибка может возникнуть в процессе загрузки недостающих данных из дисковой копии.
SING_ERROR_OUTPUT_NOT_FOUND - не удается файл outfile для записи
SING_ERROR_CONNECTION_LOST - набор удален

Работа с данными

Вызовы чтения делятся на три группы. Группа с коллбеками вызывает коллбек выделения памяти для копирования значения. Эта группа самая быстрая с точки зрения вызывающего потока, но может замедлить пишущие потоки. Копирующие вызовы копируют значения в заранее выделенную память. Это может вызвать дополнительные расходы в вызывающем потоке на повторное копирование (например в интерфейсах для интерпретаторов), но не замедляет пишущие потоки. Простые вызовы возвращают значение встроенного типа или наличие ключа и никак не влияют на остальные потоки.
Ключ может передаваться в вызовы как нуль-завершенная строка (вызовы без суффикса _n) или как ссылка на буфер и его размер (вызовы с суффиксом _n), что удобно при поиске ключей в длинном наборе байт. Все вызовы работы с данными имеют версию для работы с набором ключей. Она значительно (в разы) быстрее не только за счет экономии на вызовах, но и за счет конвеерной обработки нескольких ключей одновременно с предзагрузкой требуемых данных в кеш CPU. Параллельная модификация при таких вызовах работает аналогично вызовам работы с файлами. Модифицирующие вызовы для нескольких ключей при нехватке памяти в процессе работы в режиме LM_SIMPLE выполняют автоматический возврат к дисковой копии, если она есть.

CSingValueAllocator

typedef void *(* CSingValueAllocator)(unsigned size);

Описание коллбека выделения памяти для передачи в функции с суффиксом _cb. Использование вызовов библиотеки из коллбека вызывает неопределенное поведение.
Параметры:
size - размер требуемой памяти в байтах. Коллбек может выделять больше памяти (например для добавления нулевого байта в конец)
Возвращаемое значение:
Возвращает ссылку на выделенную память. Может вернуть NULL, что приведет к ошибке SING_ERROR_NO_MEMORY

sing_get_value_cb

int sing_get_value_cb(FSingSet kvset,const char *key,CSingValueAllocator vacb,void **value,unsigned *vsize)
int sing_get_value_cb_n(FSingSet kvset,const char *key,unsigned ksize,CSingValueAllocator vacb,void **value,unsigned *vsize)

находит ключ и размер его значения, вызывает коллбек выделения памяти, копирует значение в выделенную память, сохраняет указатель на нее в *value и размер в *vsize.
Параметры:
kvset - подключенный набор данных.
key - имя ключа
ksize - длина имени ключа
vacb - указатель на функцию выделения памяти
value - место для сохранения ссылки на значение. Должен указывать на память размером sizeof(void *)
vsize - место для сохранения размера значения. Должен указывать на память размером sizeof(unsigned)
Возвращаемые значения:
0 - ключ найден, в этом случае *value и *vsize содержат ссылку на значение и его размер (возможно NULL и 0 если значения нет)
SING_RESULT_KEY_NOT_FOUND - ключ не найден (или фантомный), в этом случае *value = NULL и *vsize = 0
SING_RESULT_IMPOSSIBLE_KEY - невозможный для используемого кодека ключ, *value = NULL и *vsize = 0
SING_ERROR_NO_MEMORY - коллбек вернул NULL, *value и *vsize не меняются
SING_ERROR_NO_SET_MEMORY - не удается выделить страницу для новых данных. Эта ошибка может возникнуть в процессе загрузки недостающих данных из дисковой копии. *value и *vsize не меняются
SING_ERROR_CONNECTION_LOST - набор удален, *value и *vsize не меняются

sing_get_phantom_cb

int sing_get_phantom_cb(FSingSet kvset,const char *key,CSingValueAllocator vacb,void **value,unsigned *vsize)
int sing_get_phantom_cb_n(FSingSet kvset,const char *key,unsigned ksize,CSingValueAllocator vacb,void **value,unsigned *vsize)

находит фантомный ключ или значение и размер значения, вызывает коллбек выделения памяти, копирует значение в выделенную память, сохраняет указатель на нее в *value и размер в *vsize.
Параметры:
kvset - подключенный набор данных.
key - имя ключа
ksize - длина имени ключа
vacb - указатель на функцию выделения памяти
value - место для сохранения ссылки на значение. Должен указывать на память размером sizeof(void *)
vsize - место для сохранения размера значения. Должен указывать на память размером sizeof(unsigned)
Возвращаемые значения:
0 - ключ найден, в этом случае *value и *vsize содержат ссылку на значение и его размер (возможно NULL и 0 если значения нет)
SING_RESULT_KEY_NOT_FOUND - ключ не найден (или не фантомный и не имеет фантомного значения), в этом случае *value = NULL и *vsize = 0
SING_RESULT_IMPOSSIBLE_KEY - невозможный для используемого кодека ключ, *value = NULL и *vsize = 0
SING_ERROR_NO_MEMORY - коллбек вернул NULL, *value и *vsize не меняются
SING_ERROR_NO_SET_MEMORY - не удается выделить страницу для новых данных. Эта ошибка может возникнуть в процессе загрузки недостающих данных из дисковой копии. *value и *vsize не меняются
SING_ERROR_IMPOSSIBLE_OPERATION - набор без фантомных ключей
SING_ERROR_CONNECTION_LOST - набор удален, *value и *vsize не меняются

sing_get_values_cb

int sing_get_values_cb(FSingSet *kvset,const char *const *keys,unsigned count,CSingValueAllocator vacb,void **values,unsigned *vsizes,int *results)
int sing_get_values_cb_n(FSingSet *kvset,const char *const *keys,const unsigned *ksizes,unsigned count,CSingValueAllocator vacb,void **values,unsigned *vsizes,int *results)

по очереди находит ключи, размер их значений, вызывает коллбек выделения памяти, копирует значение в выделенную память, сохраняет указатель на нее в *(values + n) и размер в *(vsizes + n). Использование вызовов библиотеки из колбека вызывает неопределенное поведение.
Параметры:
kvset - подключенный набор данных.
keys - указатель на массив имен ключей
ksizes - указатель на массив с длинами имен ключей для sing_get_values_cb_n. Если NULL, вызов аналогичен sing_get_values_cb
count - число ключей
vacb - указатель на функцию выделения памяти
values - место для сохранения ссылок на значение. Должен указывать на память размером sizeof(void *) * count
vsizes - место для сохранения размера значения. Должен указывать на память размером sizeof(unsigned) * count
results - место для сохранения наличия ключей. Должен указывать на память размером sizeof(int) * count
Возвращаемые значения:
n >= 0 - число найденных ключей. в этом случае:
  *(results + i) содержит 0 если ключ найден *(value + i), тогда содержит ссылку на значение, *(vsize + i) - размер значения (возможно NULL,0)
  *(results + i) содержит SING_RESULT_KEY_NOT_FOUND если ключ не найден (или фантомный), *(value + i) = NULL, *(vsize + i) = 0
  *(results + i) содержит SING_RESULT_IMPOSSIBLE_KEY если ключ невозможен для кодека, *(value + i) = NULL, *(vsize + i) = 0
  *(results + i) содержит SING_ERROR_NO_MEMORY или SING_ERROR_NO_SET_MEMORY если в процессе выполнения запроса произошла одна из этих ошибок. *(value + i) = NULL, *(vsize + i) = 0
SING_ERROR_NO_MEMORY - коллбек вернул NULL, *(value + i) и *(vsize + i) содержат данные, которые удалось получить до ошибки, остальные содержат NULL и 0
SING_ERROR_NO_SET_MEMORY - не удается выделить страницу для новых данных. Эта ошибка может возникнуть в процессе загрузки недостающих данных из дисковой копии. *(value + i) и *(vsize + i) содержат данные, которые удалось получить до ошибки, остальные содержат NULL и 0
SING_ERROR_CONNECTION_LOST - набор удален. В этом случае ошибки содержание *value и *vsize не меняется

sing_get_value

int sing_get_value(FSingSet *kvset,const char *key,void *value,unsigned *vsize)
int sing_get_value_n(FSingSet *kvset,const char *key,unsigned ksize,void *value,unsigned *vsize)

находит ключ и размер его значения, копирует значение в *value, максмально *vsize байт, сохраняет полный размер значения в *vsize.
Параметры:
kvset - подключенный набор данных.
key - имя ключа
ksize - длина имени ключа
value - место для сохранения значения. Должен указывать на память размером *vsize
vsize - на входе *vsize равен размеру буфера value. На выходе - размеру значения. Должен указывать на память размером sizeof(unsigned)
Возвращаемые значения:
0 если ключ найден, в этом случае *value и *vsize содержат значение (возможно обрезанное) и его размер.
SING_RESULT_KEY_NOT_FOUND если ключ не найден (или фантомный), в этом случае *value не меняется, *vsize содержит 0
SING_RESULT_IMPOSSIBLE_KEY - невозможный для используемого кодека ключ, *value не меняется, *vsize содержит 0
SING_RESULT_SMALL_BUFFER - слишком маленький для значения буфер. *value содержит поместившуюся часть значения, *vsize - размер значения. SING_ERROR_NO_SET_MEMORY - не удается выделить страницу для новых данных. Эта ошибка может возникнуть в процессе загрузки недостающих данных из дисковой копии. *value и *vsize не меняются
SING_ERROR_CONNECTION_LOST - набор удален, *value и *vsize не меняются

sing_get_phantom

int sing_get_phantom(FSingSet *kvset,const char *key,void *value,unsigned *vsize)
int sing_get_phantom_n(FSingSet *kvset,const char *key,unsigned ksize,void *value,unsigned *vsize)

находит фантомный ключ или значение, копирует значение в *value, максмально *vsize байт, сохраняет полный размер значения в *vsize.
Параметры:
kvset - подключенный набор данных.
key - имя ключа
ksize - длина имени ключа
value - место для сохранения значения. Должен указывать на память размером *vsize
vsize - на входе *vsize равен размеру буфера value. На выходе - размеру значения. Должен указывать на память размером sizeof(unsigned)
Возвращаемые значения:
0 если ключ найден, в этом случае *value и *vsize содержат значение (возможно обрезанное) и его размер.
SING_RESULT_KEY_NOT_FOUND если ключ не найден (или не фантомный и не имеет фантомного значения), в этом случае *value не меняется, *vsize содержит 0
SING_RESULT_IMPOSSIBLE_KEY - невозможный для используемого кодека ключ, *value не меняется, *vsize содержит 0
SING_RESULT_SMALL_BUFFER - слишком маленький для значения буфер. *value содержит поместившуюся часть значения, *vsize - размер значения. SING_ERROR_NO_SET_MEMORY - не удается выделить страницу для новых данных. Эта ошибка может возникнуть в процессе загрузки недостающих данных из дисковой копии. *value и *vsize не меняются
SING_ERROR_IMPOSSIBLE_OPERATION - набор без фантомных ключей
SING_ERROR_CONNECTION_LOST - набор удален, *value и *vsize не меняются

sing_get_values

int sing_get_values(FSingSet *kvset,const char *const *keys,unsigned count,void *const *values,unsigned *vsizes,int *results)
int sing_get_values_n(FSingSet *kvset,const char *const *keys,const unsigned *ksizes,unsigned count,void *const *values,unsigned *vsizes,int *results)

по очереди находит ключи, копирует значение в **(values + n), максимально *(vsize + n) байт, сохраняет полные размеры значений в *(vsizes + n).
Параметры:
kvset - подключенный набор данных.
keys - указатель на массив имен ключей
ksizes - указатель на массив с размерами ключей для sing_get_values_n. Если NULL, вызов аналогичен sing_get_values
count - число ключей
values - массив ссылок на выделенную память. Должен указывать на память размером sizeof(void *) * count, каждый элемент которого *(values + i) - ссылка на участок памяти размером *(vsize + i). На выходе в эту память помещаются значения ключей (возможно обрезанные)
vsizes - место для сохранения размера значения. Должен указывать на память размером sizeof(unsigned) * count. На входе - размеры участков памяти *(values + i). На выходе - размеры значений.
results - место для сохранения наличия ключей. Должен указывать на память размером sizeof(int) * count
Возвращаемые значения:
n >= 0 - число найденных ключей (в том числе с обрезанными значениями). в этом случае:
  (results + i) содержит 0 если ключ найден, в **(value + i) скопировано значение, *(vsize + i) - размер значения, если 0 то **(value + i) не меняется
  (results + i) содержит SING_RESULT_KEY_NOT_FOUND если ключ не найден (или фантомный), *(vsize + i) = 0, **(value + i) не меняется
  (results + i) содержит SING_RESULT_SMALL_BUFFER если значение больше переданного буфера, *(vsize + i) содержит нужный размер буфера, **(value + i) содержит поместившуюся часть значения
  (results + i) содержит SING_RESULT_IMPOSSIBLE_KEY если ключ невозможен для кодека, *(vsize + i) = 0, **(value + i) не меняется
  *(results + i) содержит SING_ERROR_NO_SET_MEMORY если в процессе выполнения запроса произошла эта ошибка. *(value + i) не меняется, *(vsize + i) = 0
SING_ERROR_NO_SET_MEMORY - не удается выделить страницу для новых данных. Эта ошибка может возникнуть в процессе загрузки недостающих данных из дисковой копии. *(value + i) и *(vsize + i) содержат данные, которые удалось получить до ошибки, остальные *(vsize + i) содержат 0
SING_ERROR_CONNECTION_LOST - набор удален. В этом случае *(vsize + i) и **(value + i) не меняются

sing_get_values_simple

int sing_get_values_simple(FSingSet *kvset,const char *const *keys,unsigned count,void **values,unsigned *vsizes,int *results)
int sing_get_values_simple_n(FSingSet *kvset,const char *const *keys,const unsigned *ksizes,unsigned count,void **values,unsigned *vsizes,int *results)

Метод получения значений нескольких ключей в один участок памяти последовательно. На входе *values содержит ссылку на участок памяти, его размер в vsizes. На выходе *(values + i) содержит ссылки на значения, скопированные последовательно в переданный участок, их размеры в *(vsizes + n). Возвращаются только те значения, которые помещаются в буфер целиком
Параметры:
kvset - подключенный набор данных.
keys - указатель на массив имен ключей
ksizes - указатель на массив с размерами ключей для sing_get_values_simple_n. Если NULL, вызов аналогичен sing_get_values_simple
count - число ключей
values - На входе *values содержит ссылку на участок памяти размером *vsize. На выходе *(values + i) содержит ссылки на значения, скопированные последовательно в переданный участок.
vsizes - Должен указывать на память размером sizeof(unsigned) * count. На входе *vsize содержит размер участка памяти **values. На выходе - размеры значений *(values + i)
results - место для сохранения наличия ключей. Должен указывать на память размером sizeof(int) * count
Возвращаемые значения:
n >= 0 - число найденных ключей (в том числе не поместившихся в буффер). в этом случае:
  *(results + i) содержит 0 если ключ найден, в *(value + i) ссылка на значение, *(vsize + i) - размер значения, (возможно NULL,0)
  *(results + i) содержит SING_RESULT_KEY_NOT_FOUND если ключ не найден, *(vsize + i) = 0, *(value + i) = NULL
  *(results + i) содержит SING_RESULT_IMPOSSIBLE_KEY если ключ невозможен для кодека, *(vsize + i) = 0, *(value + i) = NULL
  *(results + i) содержит SING_RESULT_SMALL_BUFFER если ключ найден, но в переданном буфере недостаточно места для размещения значения, *(vsize + i) = размер значения, *(value + i) = NULL
  *(results + i) содержит SING_ERROR_NO_SET_MEMORY если в процессе выполнения запроса произошла эта ошибка. *(vsize + i) = 0, *(value + i) = NULL
SING_ERROR_NO_SET_MEMORY - не удается выделить страницу для новых данных. Эта ошибка может возникнуть в процессе загрузки недостающих данных из дисковой копии. *(value + i) и *(vsize + i) содержат данные, которые удалось получить до ошибки, остальные *(value + i) и *(vsize + i) содержат NULL и 0
SING_ERROR_CONNECTION_LOST - набор удален. В этом случае *(vsize + i) и **(value + i) не меняются

sing_get_values_same

int sing_get_values_same(FSingSet *kvset,const char *const *keys,unsigned count,void *values,unsigned vsize,int *results)
int sing_get_values_same_n(FSingSet *kvset,const char *const *keys,const unsigned *ksizes,unsigned count,void *values,unsigned vsize,int *results)

Метод получения значений одинакового размера для нескольких ключей в один участок памяти последовательно. На входе *values содержит ссылку на участок памяти,
размер значений в vsize. Значения меньшего размера будут дополнены нулями справа. Значения большего размера будут обрезаны.
Параметры:
kvset - подключенный набор данных.
keys - указатель на массив имен ключей
ksizes - указатель на массив с размерами ключей для sing_get_values_same_n. Если NULL, вызов аналогичен sing_get_values_same
count - число ключей
values - *values содержит ссылку на участок памяти размером vsize * count для сохранения значений.
vsize - размер значений
results - место для сохранения наличия ключей. Должен указывать на память размером sizeof(int) * count
Возвращаемые значения:
n >= 0 - число найденных ключей. в этом случае:
  *(results + i) содержит 0 если ключ найден, *(value + i) содержит найденное значение
  *(results + i) содержит SING_RESULT_KEY_NOT_FOUND если ключ не найден, *(value + i) = 0
  *(results + i) содержит SING_RESULT_IMPOSSIBLE_KEY если ключ невозможен для кодека, *(value + i) = 0
  *(results + i) содержит SING_ERROR_NO_SET_MEMORY если в процессе выполнения запроса произошла эта ошибка. *(value + i) = 0
SING_ERROR_NO_SET_MEMORY - не удается выделить страницу для новых данных. Эта ошибка может возникнуть в процессе загрузки недостающих данных из дисковой копии. *(value + i) содержит значения, которые удалось получить до ошибки, остальные *(value + i) содержат 0
SING_ERROR_CONNECTION_LOST - набор удален. В этом случае *(value + i) содержат 0

sing_key_present

int sing_key_present(FSingSet *kvset,const char *key)
int sing_key_present_n(FSingSet *kvset,const char *key,unsigned ksize)

если ключ найден в наборе и не фантомный, возвращает 0.
Параметры:
kvset - подключенный набор данных.
key - имя ключа
ksize - длина имени ключа
Возвращаемые значения:
0 если ключ найден
SING_RESULT_KEY_NOT_FOUND если ключ не найден или фантомный
SING_RESULT_IMPOSSIBLE_KEY - невозможный для используемого кодека ключ
SING_ERROR_CONNECTION_LOST - набор удален

sing_phantom_present

int sing_phantom_present(FSingSet *kvset,const char *key)
int sing_phantom_present_n(FSingSet *kvset,const char *key,unsigned ksize)

если ключ найден в наборе и фантомный, или имеет фантомное значение, возвращает 0.
Параметры:
kvset - подключенный набор данных.
key - имя ключа
ksize - длина имени ключа
Возвращаемые значения:
0 если ключ найден
SING_RESULT_KEY_NOT_FOUND если ключ не найден (или не фантомный и не имеет фантомного значения)
SING_RESULT_IMPOSSIBLE_KEY - невозможный для используемого кодека ключ
SING_ERROR_IMPOSSIBLE_OPERATION - набор без фантомных ключей
SING_ERROR_CONNECTION_LOST - набор удален

sing_keys_present

int sing_keys_present(FSingSet *kvset,const char *const *keys,unsigned count,int *results)
int sing_keys_present_n(FSingSet *kvset,const char *const *keys,const unsigned *ksizes,unsigned count,int *results)

Проверяет последовательно несколько ключей. Если ключ найден в наборе, results[i] равен 0, иначе содержит код причины. Вызов не атомарен.
Параметры:
kvset - подключенный набор данных.
keys - указатель на массив имен ключей
ksizes - указатель на массив с размерами ключей для sing_keys_present_n. Если NULL, вызов аналогичен sing_keys_present
count - число ключей
results - место для сохранения наличия ключей. Должен указывать на память размером sizeof(int) * count
Возвращаемые значения:
n >= 0 - число найденных ключей. в этом случае:
  *(results + i) содержит 0 если ключ найден
  *(results + i) содержит SING_RESULT_KEY_NOT_FOUND если ключ не найден
  *(results + i) содержит SING_RESULT_IMPOSSIBLE_KEY если ключ невозможен для кодека
SING_ERROR_CONNECTION_LOST - набор удален

sing_value_equal

int sing_value_equal(FSingSet *kvset,const char *key,const void *value,unsigned vsize)
int sing_value_equal_n(FSingSet *kvset,const char *key,unsigned ksize,const void *value,unsigned vsize)

Проверяет наличие ключа и совпадение его значения с данными *value.
Параметры:
kvset - подключенный набор данных.
key - имя ключа
ksize - длина имени ключа
value - ссылка на значение для сравнения
vsize - размер значения
Возвращаемые значения:
0 - ключ найден и значение совпадает
SING_RESULT_KEY_NOT_FOUND если ключ не найден или фантомный SING_RESULT_IMPOSSIBLE_KEY - невозможный для используемого кодека ключ
SING_RESULT_VALUE_DIFFER - ключ найден но значение отличается
SING_ERROR_CONNECTION_LOST - набор удален

sing_phantom_equal

int sing_phantom_equal(FSingSet *kvset,const char *key,const void *value,unsigned vsize)
int sing_phantom_equal_n(FSingSet *kvset,const char *key,unsigned ksize,const void *value,unsigned vsize)

Проверяет наличие фантомного ключа или значения и совпадение с данными *value.
Параметры:
kvset - подключенный набор данных.
key - имя ключа
ksize - длина имени ключа
value - ссылка на значение для сравнения
vsize - размер значения
Возвращаемые значения:
0 - ключ найден и значение совпадает
SING_RESULT_KEY_NOT_FOUND если ключ не найден (или не фантомный и не имеет фантомного значения)
SING_RESULT_IMPOSSIBLE_KEY - невозможный для используемого кодека ключ
SING_RESULT_VALUE_DIFFER - ключ найден но значение отличается
SING_ERROR_IMPOSSIBLE_OPERATION - набор без фантомных ключей
SING_ERROR_CONNECTION_LOST - набор удален

sing_values_equal

int sing_values_equal(FSingSet *kvset,const char *const *keys,unsigned count,const void **values,const unsigned *vsizes,int *results)
int sing_values_equal_n(FSingSet *kvset,const char *const *keys,const unsigned *ksizes,unsigned count,const void **values,const unsigned *vsizes,int *results)

Проверяет последовательно наличие нескольких ключей и совпадение их значений с переданными. results[i] содержит результат поиска и сравнения. Вызов не атомарен.
Параметры:
kvset - подключенный набор данных.
keys - указатель на массив имен ключей
ksizes - указатель на массив с размерами ключей для sing_values_equal_n. Если NULL, вызов аналогичен sing_values_equal_n
count - число ключей
values - массив ссылок на значения для сравнения
vsizes - размеры значений для сравнения
results - место для сохранения наличия ключей. Должен указывать на память размером sizeof(int) * count
Возвращаемые значения:
n >= 0 - число совпавших ключей. в этом случае:
  *(results + i) содержит 0 если ключ найден
  *(results + i) содержит SING_RESULT_KEY_NOT_FOUND если ключ не найден
  *(results + i) содержит SING_RESULT_IMPOSSIBLE_KEY если ключ невозможен для кодека
  *(results + i) содержит SING_RESULT_VALUE_DIFFER если ключ найден, но значение отличается
SING_ERROR_CONNECTION_LOST - набор удален

sing_get_valueTYPE, sing_get_pointer

int sing_get_value32i(FSingSet *kvset,const char *key,int32_t *value)
int sing_get_value32i_n(FSingSet *kvset,const char *key,unsigned ksize,int32_t *value)
int sing_get_value32u(FSingSet *kvset,const char *key,uint32_t *value)
int sing_get_value32u_n(FSingSet *kvset,const char *key,unsigned ksize,uint32_t *value)
int sing_get_value32f(FSingSet *kvset,const char *key, float *value)
int sing_get_value32f_n(FSingSet *kvset,const char *key,unsigned ksize,float *value)
int sing_get_value64i(FSingSet *kvset,const char *key,int64_t *value)
int sing_get_value64i_n(FSingSet *kvset,const char *key,unsigned ksize,int64_t *value)
int sing_get_value64u(FSingSet *kvset,const char *key,uint64_t *value)
int sing_get_value64u_n(FSingSet *kvset,const char *key,unsigned ksize,uint64_t *value)
int sing_get_value64d(FSingSet *kvset,const char *key,double *value)
int sing_get_value64d_n(FSingSet *kvset,const char *key,unsigned ksize,double *value)
int sing_get_pointer(FSingSet *kvset,const char *key,void **pointer)
int sing_get_pointer_n(FSingSet *kvset,const char *key,unsigned ksize,void **pointer)

Проверяет наличие ключа и если найден то сохраняет первые 32/64 бита значения в *value. Недостающие байты заполняются нулями справа (целочисленный беззнаковый результат можно приводить к 8-ми и 16-ти битовым значениям, если нужно).
Параметры:
kvset - подключенный набор данных.
key - имя ключа
ksize - длина имени ключа
value - ссылка на 4-х/8-ми байтную область памяти
Возвращаемые значения:
0 - ключ найден, *value содержит значение
SING_RESULT_KEY_NOT_FOUND если ключ не найден, *value содержит 0
SING_RESULT_IMPOSSIBLE_KEY - невозможный для используемого кодека ключ, *value содержит 0
SING_ERROR_CONNECTION_LOST - набор удален, *value содержит 0

sing_get_valuesTYPE, sing_get_pointers

int sing_get_values32i(FSingSet *kvset,const char *const *keys,unsigned count,int32_t *values,int *results)
int sing_get_values32i_n(FSingSet *kvset,const char *const *keys,const unsigned *ksizes,unsigned count,int32_t *values,int *results)
int sing_get_values32u(FSingSet *kvset,const char *const *keys,unsigned count,uint32_t *values,int *results)
int sing_get_values32u_n(FSingSet *kvset,const char *const *keys,const unsigned *ksizes,unsigned count,uint32_t *values,int *results)
int sing_get_values32f(FSingSet *kvset,const char *const *keys,unsigned count,float *values,int *results)
int sing_get_values32f_n(FSingSet *kvset,const char *const *keys,const unsigned *ksizes,unsigned count,float *values,int *results)
int sing_get_values64i(FSingSet *kvset,const char *const *keys,unsigned count,int64_t *values,int *results)
int sing_get_values64i_n(FSingSet *kvset,const char *const *keys,const unsigned *ksizes,unsigned count,int64_t *values,int *results)
int sing_get_values64u(FSingSet *kvset,const char *const *keys,unsigned count,uint64_t *values,int *results)
int sing_get_values64u_n(FSingSet *kvset,const char *const *keys,const unsigned *ksizes,unsigned count,uint64_t *values,int *results)
int sing_get_values64d(FSingSet *kvset,const char *const *keys,unsigned count,double *values,int *results)
int sing_get_values64d_n(FSingSet *kvset,const char *const *keys,const unsigned *ksizes,unsigned count,double *values,int *results)
int sing_get_pointers(FSingSet *kvset,const char *const *keys,unsigned count,void **pointers,int *results)
int sing_get_pointers_n(FSingSet *kvset,const char *const *keys,const unsigned *ksizes,unsigned count,void **pointers,int *results)

Проверяет последовательно наличие нескольких ключей и сохраняет первые 32/64 бита значения в *(values + i). Если ключ найден в наборе, results[i] равен 0, иначе содержит код причины. Вызов не атомарен.
Параметры:
kvset - подключенный набор данных.
keys - указатель на массив имен ключей
ksizes - указатель на массив с размерами ключей
count - число ключей
values - место для сохранения значений.
results - место для сохранения наличия ключей. Должен указывать на память размером sizeof(int) * count
Возвращаемые значения:
n >= 0 - число найденных ключей. в этом случае:
  *(results + i) содержит 0 если ключ найден, в *(value + i) значение
  *(results + i) содержит SING_RESULT_KEY_NOT_FOUND если ключ не найден, *(value + i)содержит 0
  *(results + i) содержит SING_RESULT_IMPOSSIBLE_KEY если ключ невозможен для кодека, *(value + i) содержит 0
SING_ERROR_CONNECTION_LOST - набор удален. В этом случае *(value + i) не меняется

sing_add_key

int sing_add_key(FSingSet *kvset,const char *key,void *value,unsigned vsize)
int sing_add_key_n(FSingSet *kvset,const char *key,unsigned ksize,void *value,unsigned vsize)

Добавляет ключ. Если ключ есть и не фантомный, никаких действий не выполняется. Если ключ фантомный, он становится обычным с фантомным значением.
Параметры:
kvset - подключенный набор данных.
key - имя ключа
ksize - длина имени ключа
value - ссылка на значение
vsize - размер значения
Возвращаемые значения:
0 - ключ добавлен
SING_RESULT_KEY_PRESENT - ключ уже есть в наборе.
SING_RESULT_IMPOSSIBLE_KEY - невозможный для используемого кодека ключ
SING_ERROR_NO_SET_MEMORY - не удается выделить страницу для новых данных
SING_ERROR_CONNECTION_LOST - набор удален

sing_add_phantom

int sing_add_phantom(FSingSet *kvset,const char *key,void *value,unsigned vsize)
int sing_add_phantom_n(FSingSet *kvset,const char *key,unsigned ksize,void *value,unsigned vsize)

Добавляет фантомный ключ или фантомное значение к уже имеющемуся. Если ключ уже есть, фантомный или имеет фантомное значение, никаких действий не выполняется.
Параметры:
kvset - подключенный набор данных.
key - имя ключа
ksize - длина имени ключа
value - ссылка на значение
vsize - размер значения
Возвращаемые значения:
0 - ключ добавлен
SING_RESULT_KEY_PRESENT - ключ уже есть в наборе, фантомный или имеет фантомное значение. SING_RESULT_IMPOSSIBLE_KEY - невозможный для используемого кодека ключ
SING_ERROR_NO_SET_MEMORY - не удается выделить страницу для новых данных
SING_ERROR_IMPOSSIBLE_OPERATION - набор без фантомных ключей
SING_ERROR_CONNECTION_LOST - набор удален

sing_set_key

int sing_set_key(FSingSet *kvset,const char *key,void *value,unsigned vsize)
int sing_set_key_n(FSingSet *kvset,const char *key,unsigned ksize,void *value,unsigned vsize)

Добавляет или заменяет ключ. Если ключ заменяется в наборе с фантомами и у него нет фантомного значения, его старое значение становится фантомным.
Параметры:
kvset - подключенный набор данных.
key - имя ключа
ksize - длина имени ключа
value - ссылка на значение
vsize - размер значения
Возвращаемые значения:
0 - ключ добавлен или заменен
SING_RESULT_IMPOSSIBLE_KEY - невозможный для используемого кодека ключ
SING_ERROR_NO_SET_MEMORY - не удается выделить страницу для новых данных
SING_ERROR_CONNECTION_LOST - набор удален

sing_set_phantom

int sing_set_phantom(FSingSet *kvset,const char *key,void *value,unsigned vsize)
int sing_set_phantom_n(FSingSet *kvset,const char *key,unsigned ksize,void *value,unsigned vsize)

Добавляет или заменяет фантомный ключ/значение. Если ключа не было, создается фантомный ключ. Если ключ был фантомным, его значение заменяется. Если ключ был нормальным - добавляется или заменяется фантомное значение.
Параметры:
kvset - подключенный набор данных.
key - имя ключа
ksize - длина имени ключа
value - ссылка на значение
vsize - размер значения
Возвращаемые значения:
0 - ключ добавлен или заменен
SING_RESULT_IMPOSSIBLE_KEY - невозможный для используемого кодека ключ
SING_ERROR_NO_SET_MEMORY - не удается выделить страницу для новых данных
SING_ERROR_IMPOSSIBLE_OPERATION - набор без фантомных ключей
SING_ERROR_CONNECTION_LOST - набор удален

sing_add_keys, sing_set_keys

int sing_add_keys(FSingSet *kvset,const char *const *keys,unsigned count,const void *const *values,const unsigned *vsizes,int *results)
int sing_add_keys_n(FSingSet *kvset,const char *const *keys,const unsigned *ksizes,unsigned count,const void *const *values,const unsigned *vsizes,int *results)
int sing_set_keys(FSingSet *kvset,const char *const *keys,unsigned count,const void *const *values,const unsigned *vsizes,int *results)
int sing_set_keys_n(FSingSet *kvset,const char *const *keys,const unsigned *ksizes,unsigned count,const void *const *values,const unsigned *vsizes,int *results)

добавляет или заменяет ключи. Ключи обрабатываются не в порядке следования, и дубликаты не проверяются - не определено, какое из значений попадет в набор при наличии одинаковых ключей.
Параметры:
kvset - подключенный набор данных.
keys - указатель на массив имен ключей
ksizes - указатель на массив с размерами ключей
count - число ключей
values - место для сохранения значений.
results - место для сохранения результата операции. Должен указывать на память размером sizeof(int) * count
Возвращаемые значения:
n >= 0 - число добавленных ключей. в этом случае:
  *(results + i) содержит 0 если ключ добавлен
  *(results + i) содержит SING_RESULT_KEY_PRESENT если ключ уже есть в наборе
  *(results + i) содержит SING_RESULT_IMPOSSIBLE_KEY если ключ невозможен для кодека
SING_ERROR_NO_SET_MEMORY - не удается выделить страницу для новых данных
SING_ERROR_CONNECTION_LOST - набор удален. В этом случае *(value + i) не меняется

sing_set_keyTYPE, sing_set_pointer

int sing_set_key32i(FSingSet *kvset,const char *key,int32_t value)
int sing_set_key32u(FSingSet *kvset,const char *key,uint32_t value)
int sing_set_key32f(FSingSet *kvset,const char *key,float value)
int sing_set_key64i(FSingSet *kvset,const char *key,int64_t value)
int sing_set_key64u(FSingSet *kvset,const char *key,uint64_t value)
int sing_set_key64d(FSingSet *kvset,const char *key,double value)
int sing_set_pointer(FSingSet *kvset,const char *key,void *value)

Добавляет или перезаписывает ключ, сохраняя значение указанного типа
Параметры:
kvset - подключенный набор данных.
key - имя ключа
value - значение
Возвращаемые значения:
0 - ключ добавлен
SING_RESULT_KEY_PRESENT если ключ уже есть.
SING_RESULT_IMPOSSIBLE_KEY - невозможный для используемого кодека ключ
SING_ERROR_NO_SET_MEMORY - не удается выделить страницу для новых данных
SING_ERROR_CONNECTION_LOST - набор удален

sing_del_key

int sing_del_key(FSingSet *kvset,const char *key) 
int sing_del_key_n(FSingSet *kvset,const char *key,unsigned ksize) 

Удаляет ключ из набора. В наборе с фантомами ключами, если ключ есть, создает из него фантомный ключ с имеющимся фантомным или нормальным значением. Если ключа нет, фантом не создается. Если ключ уже фантомный, возвращает SING_RESULT_KEY_NOT_FOUND.
Параметры:
kvset - подключенный набор данных.
key - имя ключа
ksize - длина имени ключа
Возвращаемые значения:
0 - ключ удален
SING_RESULT_KEY_NOT_FOUND - ключ не найден (или фантомный для набора с фантомами)
SING_RESULT_IMPOSSIBLE_KEY - невозможный для используемого кодека ключ
SING_ERROR_NO_SET_MEMORY - не удается выделить страницу для новых данных. Ошибка может возникнуть при загрузке данных из дисковой копии.
SING_ERROR_CONNECTION_LOST - набор удален

sing_del_phantom

int sing_del_phantom(FSingSet *kvset,const char *key) 
int sing_del_phantom_n(FSingSet *kvset,const char *key,unsigned ksize) 

Удаляет фантомный ключ или значение.
Параметры:
kvset - подключенный набор данных.
key - имя ключа
ksize - длина имени ключа
Возвращаемые значения:
0 - ключ удален
SING_RESULT_KEY_NOT_FOUND - ключ не найден, не фантомный, или не имеет фантомного значения
SING_RESULT_IMPOSSIBLE_KEY - невозможный для используемого кодека ключ
SING_ERROR_NO_SET_MEMORY - не удается выделить страницу для новых данных. Ошибка может возникнуть при загрузке данных из дисковой копии.
SING_ERROR_IMPOSSIBLE_OPERATION - набор без фантомных ключей
SING_ERROR_CONNECTION_LOST - набор удален

sing_del_full

int sing_del_full(FSingSet *kvset,const char *key) 
int sing_del_full_n(FSingSet *kvset,const char *key,unsigned ksize) 

Удаляет ключ из набора (в том числе фантомный). Для наборов без фантомов действует аналогично sing_del_key.
Параметры:
kvset - подключенный набор данных.
key - имя ключа
ksize - длина имени ключа
Возвращаемые значения:
0 - ключ удален
SING_RESULT_KEY_NOT_FOUND - ключ не найден
SING_RESULT_IMPOSSIBLE_KEY - невозможный для используемого кодека ключ
SING_ERROR_NO_SET_MEMORY - не удается выделить страницу для новых данных. Ошибка может возникнуть при загрузке данных из дисковой копии.
SING_ERROR_CONNECTION_LOST - набор удален

sing_del_keys

int sing_del_keys(FSingSet *kvset,const char *const *keys,unsigned count,int *results) 
int sing_del_keys_n(FSingSet *kvset,const char *const *keys,const unsigned *ksizes,unsigned count,int *results) 

удаляет ключи. Ключи обрабатываются не в порядке следования. В наборах с фантомами ключи обрабатываются аналогично sing_del_key
Параметры:
kvset - подключенный набор данных.
keys - указатель на массив имен ключей
ksizes - указатель на массив с размерами ключей
count - число ключей
results - место для сохранения результата операции. Должен указывать на память размером sizeof(int) * count
Возвращаемые значения:
n >= 0 - число удаленных ключей. в этом случае:
  *(results + i) содержит 0 если ключ удален
  *(results + i) содержит SING_RESULT_KEY_NOT_FOUND если ключ не найден
  *(results + i) содержит SING_RESULT_IMPOSSIBLE_KEY если ключ невозможен для кодека
SING_ERROR_NO_SET_MEMORY - не удается выделить страницу для новых данных
SING_ERROR_CONNECTION_LOST - набор удален. В этом случае *(value + i) не меняется

CSingIterateCallback

typedef int(* CSingIterateCallback)(const char *key,const void *value,unsigned *vsize,void *new_value,void *param)

Описание коллбека обработки ключа при переборе ключей набора. Использование вызовов библиотеки в коллбеке приводит к неопределенному поведению.
Параметры:
key - имя ключа
value - ссылка на значение
vsize - на входе ссылка размер старого значения. Если коллбек выполняет замену значения, размер нового нужно поместить в *vsize
new_value - буфер для размещения нового значения.
param - пользовательский параметр, передаваемый в коллбек
Возвращаемое значение:
0 - вызов успешен
> 0 - вызов успешен, нужно заменить значение на данные new_value (вызывает ошибку для read-only наборов)
< 0 - ошибка, нужно закончить перебор ключей

sing_iterate

int sing_iterate(FSingSet *kvset,CSingIterateCallback cb,void *param)

вызывает функцию cb для каждого ключа в наборе. Хотя это пишущий вызов, работающий под соответствующими блокировками, но его использование для read-only наборов не вызывает ошибки если cb не меняет значения у ключей.
Параметры:
kvset - подключенный набор данных.
cb - указатель на коллбек-функцию для обработки ключей
param - параметр, передаваемый в коллбек
Возвращаемые значения:
0 - все ключи обработаны
SING_ERROR_BREAK - коллбек вернул ошибку
SING_ERROR_CONNECTION_LOST - набор удален