Seastar
High performance C++ framework for concurrent servers
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Modules Pages
Public Types | Public Member Functions | Public Attributes | List of all members
seastar::reactor_options Struct Reference

Detailed Description

Configuration for the reactor.

#include <seastar/core/reactor_config.hh>

Inheritance diagram for seastar::reactor_options:
seastar::program_options::option_group

Public Types

using value_list_type = boost::intrusive::list< basic_value, boost::intrusive::base_hook< list_base_hook >, boost::intrusive::constant_time_size< false > >
 
using option_group_list_type = boost::intrusive::list< option_group, boost::intrusive::base_hook< list_base_hook >, boost::intrusive::constant_time_size< false > >
 

Public Member Functions

 operator bool () const
 Does the option group has any values contained in it?
 
bool used () const
 
const std::string & name () const
 
const value_list_type & values () const
 
value_list_type & values ()
 
void describe (options_descriptor &descriptor) const
 
void mutate (options_mutator &mutator)
 

Public Attributes

program_options::selection_value< network_stack_factory > network_stack
 Select network stack to use. More...
 
program_options::value poll_mode
 Poll continuously (100% cpu use).
 
program_options::value< unsigned > idle_poll_time_us
 Idle polling time in microseconds. More...
 
program_options::value< bool > poll_aio
 Busy-poll for disk I/O. More...
 
program_options::value< double > task_quota_ms
 Max time (ms) between polls. More...
 
program_options::value< double > io_latency_goal_ms
 Max time (ms) IO operations must take. More...
 
program_options::value< double > io_flow_ratio_threshold
 
program_options::value< unsigned > io_completion_notify_ms
 If an IO request is executed longer than that, this is printed to logs with extra debugging. More...
 
program_options::value< unsigned > max_task_backlog
 Maximum number of task backlog to allow. More...
 
program_options::value< unsigned > blocked_reactor_notify_ms
 Threshold in milliseconds over which the reactor is considered blocked if no progress is made. More...
 
program_options::value< unsigned > blocked_reactor_reports_per_minute
 Maximum number of backtraces reported by stall detector per minute. More...
 
program_options::value< bool > blocked_reactor_report_format_oneline
 Print a simplified backtrace on a single line. More...
 
program_options::value relaxed_dma
 Allow using buffered I/O if DMA is not available (reduces performance).
 
program_options::value< bool > linux_aio_nowait
 Use the Linux NOWAIT AIO feature, which reduces reactor stalls due to aio (autodetected).
 
program_options::value< bool > unsafe_bypass_fsync
 Bypass fsync(), may result in data loss. More...
 
program_options::value< bool > kernel_page_cache
 Use the kernel page cache. More...
 
program_options::value overprovisioned
 Run in an overprovisioned environment (such as docker or a laptop). More...
 
program_options::value abort_on_seastar_bad_alloc
 Abort when seastar allocator cannot allocate memory.
 
program_options::value< bool > force_aio_syscalls
 Force io_getevents(2) to issue a system call, instead of bypassing the kernel when possible. More...
 
program_options::value< memory::alloc_failure_kinddump_memory_diagnostics_on_alloc_failure_kind
 Dump diagnostics of the seastar allocator state on allocation failure. More...
 
program_options::selection_value< reactor_backend_selector > reactor_backend
 Internal reactor implementation. More...
 
program_options::value< bool > aio_fsync
 Use Linux aio for fsync() calls. More...
 
program_options::value< unsigned > max_networking_io_control_blocks
 Maximum number of I/O control blocks (IOCBs) to allocate per shard. More...
 
program_options::value< unsigned > reserve_io_control_blocks
 Leave this many I/O control blocks (IOCBs) as reserve. More...
 
program_options::value< unsigned > heapprof
 Enable seastar heap profiling. More...
 
program_options::value no_handle_interrupt
 Ignore SIGINT (for gdb).
 

Member Function Documentation

◆ describe()

void seastar::program_options::option_group::describe ( options_descriptor descriptor) const
inherited

Describe the content of this option group to the visitor.

The content is visited in a depth-first manner:

  • First the option groups itself is visited with options_descriptor::visit_group_start(). If this returns false the entire content of the group, including all its subgroups and values are skipped and options_descriptor::visit_group_end() is called immediately. Otherwise visiting the content of the group proceeds.
  • All the values contained therein are visited. For each value the following happens:
    • First options_descriptor::visit_value_metadata() is called with generic metadata that all values have. If this return false the value is skipped, otherwise visiting the value proceeds.
    • Then the appropriate overload of options_descriptor::visit_value() is called, with a pointer to the default value of the respective value. The pointer is null if there is no default value.
    • For selection_value, options_descriptor::visit_selection_value() will be called instead of options_descriptor::visit_value(). After the value is visited, the option_group instance belonging to each candidate (if set) will be visited.
  • All the nested option_group instances in the current group are visited.
  • Finally options_descriptor::visit_group_end() is called.

◆ mutate()

void seastar::program_options::option_group::mutate ( options_mutator mutator)
inherited

Mutate the content of this option group by the visitor.

The visiting algorithm is identical to that of describe(), with the following differences:

  • options_mutator::visit_value() is allowed to mutate the value through the passed-in reference. It should return true if it did so and false otherwise.
  • When visiting a selection value, only the nested group belonging to the selected value is visited afterwards.

Member Data Documentation

◆ aio_fsync

program_options::value<bool> seastar::reactor_options::aio_fsync

Use Linux aio for fsync() calls.

This reduces latency. Requires Linux 4.18 or later.

◆ blocked_reactor_notify_ms

program_options::value<unsigned> seastar::reactor_options::blocked_reactor_notify_ms

Threshold in milliseconds over which the reactor is considered blocked if no progress is made.

Default: 25.

◆ blocked_reactor_report_format_oneline

program_options::value<bool> seastar::reactor_options::blocked_reactor_report_format_oneline

Print a simplified backtrace on a single line.

Default: true.

◆ blocked_reactor_reports_per_minute

program_options::value<unsigned> seastar::reactor_options::blocked_reactor_reports_per_minute

Maximum number of backtraces reported by stall detector per minute.

Default: 5.

◆ dump_memory_diagnostics_on_alloc_failure_kind

program_options::value<memory::alloc_failure_kind> seastar::reactor_options::dump_memory_diagnostics_on_alloc_failure_kind

Dump diagnostics of the seastar allocator state on allocation failure.

See memory::alloc_failure_kind for allowed values. The diagnostics will be written to the seastar_memory logger, with error level. Default: memory::alloc_failure_kind::critical.

Note
Even if the seastar_memory logger is set to debug or trace level, the diagnostics will be logged irrespective of this setting.

◆ force_aio_syscalls

program_options::value<bool> seastar::reactor_options::force_aio_syscalls

Force io_getevents(2) to issue a system call, instead of bypassing the kernel when possible.

This makes strace output more useful, but slows down the application. Default: false.

◆ heapprof

program_options::value<unsigned> seastar::reactor_options::heapprof

Enable seastar heap profiling.

Allocations will be sampled every N bytes on average. Zero means off.

Default: 0

Note
Unused when seastar was compiled without heap profiling support.

◆ idle_poll_time_us

program_options::value<unsigned> seastar::reactor_options::idle_poll_time_us

Idle polling time in microseconds.

Reduce for overprovisioned environments or laptops.

◆ io_completion_notify_ms

program_options::value<unsigned> seastar::reactor_options::io_completion_notify_ms

If an IO request is executed longer than that, this is printed to logs with extra debugging.

Default: infinite (detection is OFF)

◆ io_flow_ratio_threshold

program_options::value<double> seastar::reactor_options::io_flow_ratio_threshold

\bried Dispatch rate to completion rate ratio threshold

Describes the worst ratio at which seastar reactor is allowed to delay IO requests completion. If exceeded, the scheduler will consider it's disk that's the reason for completion slow-down and will scale down

Default: 1.1

◆ io_latency_goal_ms

program_options::value<double> seastar::reactor_options::io_latency_goal_ms

Max time (ms) IO operations must take.

Default: 1.5 * task_quota_ms value

◆ kernel_page_cache

program_options::value<bool> seastar::reactor_options::kernel_page_cache

Use the kernel page cache.

This disables DMA (O_DIRECT). Useful for short-lived functional tests with a small data set. Default: false.

◆ max_networking_io_control_blocks

program_options::value<unsigned> seastar::reactor_options::max_networking_io_control_blocks

Maximum number of I/O control blocks (IOCBs) to allocate per shard.

This translates to the number of sockets supported per shard. Requires tuning /proc/sys/fs/aio-max-nr. Only valid for the linux-aio reactor backend (see reactor_backend).

Default: 10000.

◆ max_task_backlog

program_options::value<unsigned> seastar::reactor_options::max_task_backlog

Maximum number of task backlog to allow.

When the number of tasks grow above this, we stop polling (e.g. I/O) until it goes back below the limit. Default: 1000.

◆ network_stack

program_options::selection_value<network_stack_factory> seastar::reactor_options::network_stack

Select network stack to use.

Each network stack has it corresponding program_options::option_group to further tune it. The available stacks are:

◆ overprovisioned

program_options::value seastar::reactor_options::overprovisioned

Run in an overprovisioned environment (such as docker or a laptop).

Equivalent to:

◆ poll_aio

program_options::value<bool> seastar::reactor_options::poll_aio

Busy-poll for disk I/O.

Reduces latency and increases throughput.

◆ reactor_backend

program_options::selection_value<reactor_backend_selector> seastar::reactor_options::reactor_backend

Internal reactor implementation.

Available backends:

  • linux-aio
  • epoll
  • io_uring

Default: linux-aio (if available).

◆ reserve_io_control_blocks

program_options::value<unsigned> seastar::reactor_options::reserve_io_control_blocks

Leave this many I/O control blocks (IOCBs) as reserve.

This is to allows leaving a (small) reserve aside so other applications also using IOCBs can run alongside the seastar application. The reserve takes precedence over max_networking_io_control_blocks.

Default: 0

See also
max_networking_io_control_blocks

◆ task_quota_ms

program_options::value<double> seastar::reactor_options::task_quota_ms

Max time (ms) between polls.

Default: 0.5.

◆ unsafe_bypass_fsync

program_options::value<bool> seastar::reactor_options::unsafe_bypass_fsync

Bypass fsync(), may result in data loss.

Use for testing on consumer drives. Default: false.


The documentation for this struct was generated from the following file: