From e6d9135d3881adee2d30150dee2e000ea69675f1 Mon Sep 17 00:00:00 2001 From: Yury Luneff Date: Sun, 22 Nov 2026 20:36:06 +0300 Subject: [PATCH] Add client_exit_on_error and client_infinite_start docs Both parameters are read by the client library but were not described anywhere, so a program embedding it had no way to learn how to avoid exit(1) on a fatal error. --- docs/config/client.en.md | 35 ++++++++++++++++++++++++ docs/config/client.ru.md | 37 +++++++++++++++++++++++++ docs/config/src/client.yml | 56 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 128 insertions(+) diff --git a/docs/config/client.en.md b/docs/config/client.en.md index f5dc3721..b04b5c91 100644 --- a/docs/config/client.en.md +++ b/docs/config/client.en.md @@ -14,6 +14,8 @@ affect their interaction with the cluster. - [client_eio_retry_interval](#client_eio_retry_interval) - [client_retry_enospc](#client_retry_enospc) - [client_wait_up_timeout](#client_wait_up_timeout) +- [client_exit_on_error](#client_exit_on_error) +- [client_infinite_start](#client_infinite_start) - [client_max_dirty_bytes](#client_max_dirty_bytes) - [client_max_dirty_ops](#client_max_dirty_ops) - [client_enable_writeback](#client_enable_writeback) @@ -88,6 +90,39 @@ in delete and merge-based commands ([vitastor-cli rm](../usage/cli.en.md#rm), me The default value is calculated as `1 + OSD lease timeout`, which is `1 + etcd_report_interval + max_etcd_attempts*2*etcd_quick_timeout`. +## client_exit_on_error + +- Type: boolean +- Default: true + +By default, the client library terminates the whole process with exit(1) +on a fatal error, for example when it fails to read the configuration +from etcd on start or when etcd cancels its watch. + +A program which embeds the client library can set this parameter to false +to handle such errors itself. Then the client doesn't exit. It stops +working instead: new operations fail with ECANCELED and operations which +are already in progress are never completed. The error is returned by +`vitastor_c_is_failed()` and passed to the handler set with +`vitastor_c_on_fatal_error()`. A failed client also becomes "ready", +so the program must check `vitastor_c_is_failed()` after waiting for it. + +The QEMU driver uses this mode to return client initialization errors +as image open errors instead of stopping the virtual machine. + +## client_infinite_start + +- Type: boolean +- Default: false + +By default, a client which can't read the configuration from etcd on +start after [max_etcd_attempts](network.en.md#max_etcd_attempts) attempts +treats it as a fatal error (see [client_exit_on_error](#client_exit_on_error)). + +When this parameter is set to true, the client repeats the attempts +every [etcd_slow_timeout](network.en.md#etcd_slow_timeout) until etcd +responds, so the start may take any amount of time. + ## client_max_dirty_bytes - Type: integer diff --git a/docs/config/client.ru.md b/docs/config/client.ru.md index 8c33cfbb..386fa215 100644 --- a/docs/config/client.ru.md +++ b/docs/config/client.ru.md @@ -14,6 +14,8 @@ - [client_eio_retry_interval](#client_eio_retry_interval) - [client_retry_enospc](#client_retry_enospc) - [client_wait_up_timeout](#client_wait_up_timeout) +- [client_exit_on_error](#client_exit_on_error) +- [client_infinite_start](#client_infinite_start) - [client_max_dirty_bytes](#client_max_dirty_bytes) - [client_max_dirty_ops](#client_max_dirty_ops) - [client_enable_writeback](#client_enable_writeback) @@ -90,6 +92,41 @@ RDMA и хотите повысить пиковую производитель Значение по умолчанию вычисляется как `1 + время lease OSD`, равное `1 + etcd_report_interval + max_etcd_attempts*2*etcd_quick_timeout`. +## client_exit_on_error + +- Тип: булево (да/нет) +- Значение по умолчанию: true + +По умолчанию клиентская библиотека при фатальной ошибке завершает весь +процесс вызовом exit(1). Пример такой ошибки - не удалось прочитать +конфигурацию из etcd при запуске или etcd отменил watch. + +Программа, в которую встроена клиентская библиотека, может установить +этот параметр в false, чтобы обрабатывать такие ошибки самостоятельно. +Тогда клиент не завершает процесс, а прекращает работу: новые операции +завершаются с ошибкой ECANCELED, а уже начатые не завершаются никогда. +Ошибку возвращает `vitastor_c_is_failed()`, она же передаётся в обработчик, +заданный через `vitastor_c_on_fatal_error()`. Клиент после ошибки тоже +считается "готовым", поэтому после ожидания готовности программа должна +проверить `vitastor_c_is_failed()`. + +Драйвер QEMU использует этот режим, чтобы ошибка инициализации клиента +возвращалась как ошибка открытия образа, а не останавливала виртуальную +машину. + +## client_infinite_start + +- Тип: булево (да/нет) +- Значение по умолчанию: false + +По умолчанию клиент, которому не удалось прочитать конфигурацию из etcd +при запуске за [max_etcd_attempts](network.ru.md#max_etcd_attempts) попыток, +считает это фатальной ошибкой (см. [client_exit_on_error](#client_exit_on_error)). + +Если установить этот параметр в true, клиент повторяет попытки каждые +[etcd_slow_timeout](network.ru.md#etcd_slow_timeout), пока etcd не ответит, +и запуск может длиться сколь угодно долго. + ## client_max_dirty_bytes - Тип: целое число diff --git a/docs/config/src/client.yml b/docs/config/src/client.yml index f8b86661..ec896020 100644 --- a/docs/config/src/client.yml +++ b/docs/config/src/client.yml @@ -79,6 +79,62 @@ Значение по умолчанию вычисляется как `1 + время lease OSD`, равное `1 + etcd_report_interval + max_etcd_attempts*2*etcd_quick_timeout`. +- name: client_exit_on_error + type: bool + default: true + online: false + info: | + By default, the client library terminates the whole process with exit(1) + on a fatal error, for example when it fails to read the configuration + from etcd on start or when etcd cancels its watch. + + A program which embeds the client library can set this parameter to false + to handle such errors itself. Then the client doesn't exit. It stops + working instead: new operations fail with ECANCELED and operations which + are already in progress are never completed. The error is returned by + `vitastor_c_is_failed()` and passed to the handler set with + `vitastor_c_on_fatal_error()`. A failed client also becomes "ready", + so the program must check `vitastor_c_is_failed()` after waiting for it. + + The QEMU driver uses this mode to return client initialization errors + as image open errors instead of stopping the virtual machine. + info_ru: | + По умолчанию клиентская библиотека при фатальной ошибке завершает весь + процесс вызовом exit(1). Пример такой ошибки - не удалось прочитать + конфигурацию из etcd при запуске или etcd отменил watch. + + Программа, в которую встроена клиентская библиотека, может установить + этот параметр в false, чтобы обрабатывать такие ошибки самостоятельно. + Тогда клиент не завершает процесс, а прекращает работу: новые операции + завершаются с ошибкой ECANCELED, а уже начатые не завершаются никогда. + Ошибку возвращает `vitastor_c_is_failed()`, она же передаётся в обработчик, + заданный через `vitastor_c_on_fatal_error()`. Клиент после ошибки тоже + считается "готовым", поэтому после ожидания готовности программа должна + проверить `vitastor_c_is_failed()`. + + Драйвер QEMU использует этот режим, чтобы ошибка инициализации клиента + возвращалась как ошибка открытия образа, а не останавливала виртуальную + машину. +- name: client_infinite_start + type: bool + default: false + online: false + info: | + By default, a client which can't read the configuration from etcd on + start after [max_etcd_attempts](network.en.md#max_etcd_attempts) attempts + treats it as a fatal error (see [client_exit_on_error](#client_exit_on_error)). + + When this parameter is set to true, the client repeats the attempts + every [etcd_slow_timeout](network.en.md#etcd_slow_timeout) until etcd + responds, so the start may take any amount of time. + info_ru: | + По умолчанию клиент, которому не удалось прочитать конфигурацию из etcd + при запуске за [max_etcd_attempts](network.ru.md#max_etcd_attempts) попыток, + считает это фатальной ошибкой (см. [client_exit_on_error](#client_exit_on_error)). + + Если установить этот параметр в true, клиент повторяет попытки каждые + [etcd_slow_timeout](network.ru.md#etcd_slow_timeout), пока etcd не ответит, + и запуск может длиться сколь угодно долго. - name: client_max_dirty_bytes type: int default: 33554432 -- 2.47.3