Add client_exit_on_error and client_infinite_start docs #153

Open
koolkhel wants to merge 1 commits from koolkhel/vitastor:docs-client-exit-on-error into master
3 changed files with 128 additions and 0 deletions

View File

@@ -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

View File

@@ -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
- Тип: целое число

View File

@@ -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