.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
.. use this file except in compliance with the License. You may obtain a copy of
.. the License at
..
..   http://www.apache.org/licenses/LICENSE-2.0
..
.. Unless required by applicable law or agreed to in writing, software
.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
.. License for the specific language governing permissions and limitations under
.. the License.

.. default-domain:: config
.. highlight:: ini

.. _config/ioq:

========
IO Queue
========

CouchDB has an internal subsystem that can prioritize IO associated with certain
classes of operations. This subsystem can be configured to limit the resources
devoted to background operations like internal replication and compaction
according to the settings described below.

.. config:section:: ioq :: IO Queue Configuration

    .. config:option:: concurrency :: Number of in-flight IO requests

        Specifies the maximum number of concurrent in-flight IO requests that
        the queueing system will submit::

            [ioq]
            concurrency = 10

    .. config:option:: ratio :: Preference for selecting background over interactive IO

        The fraction of the time that a background IO request will be selected
        over an interactive IO request when both queues are non-empty::

            [ioq]
            ratio = 0.01

.. config:section:: ioq.bypass :: Bypass Selected IO Classes

    System administrators can choose to submit specific classes of IO directly
    to the underlying file descriptor or OS process, bypassing the queues
    altogether. Installing a bypass can yield higher throughput and lower
    latency, but relinquishes some control over prioritization. The following
    classes are recognized:

    .. config:option:: os_process :: Bypass IO messages to external processes

        Messages on their way to an external process (e.g., ``couchjs``).

    .. config:option:: read :: Bypass Disk IO read requests

        Disk IO fulfilling interactive read requests.

    .. config:option:: write :: Bypass Disk IO write requests

        Disk IO required to update a database.

    .. config:option:: view_update :: Bypass Disk IO view update requests

        Disk IO required to update views and other secondary indexes.

    .. config:option:: shard_sync :: Bypass Disk IO for shard syncing requests

        Disk IO issued by the background replication processes that fix any
        inconsistencies between shard copies.

    .. config:option:: compaction :: Bypass Disk IO for compaction job requests

        Disk IO issued by compaction jobs.

    .. config:option:: reshard :: Bypass Disk IO for resharding jobs

        Disk IO issued by resharding jobs.

    Without any configuration CouchDB will enqueue all classes of IO. The
    default.ini configuration file that ships with CouchDB activates a bypass
    for each of the interactive IO classes and only background IO goes into the
    queueing system::

        [ioq.bypass]
        os_process = true
        read = true
        write = true
        view_update = true
        shard_sync = false
        compaction = false
        reshard = false

Recommendations
===============

The default configuration protects against excessive IO from background
operations like compaction disrupting the latency of interactive operations,
while maximizing the overall IO throughput devoted to those interactive
requests. There are certain situations where this configuration could be
sub-optimal:

* An administrator may want to devote a larger portion of the overall IO
  bandwidth to compaction in order to stay ahead of the incoming write load. In
  this it may be necessary to disable the bypass for ``write`` (to help with
  database compaction) and/or ``view_update`` (to help with view index compaction)
  and then increase the ``ratio`` to give compaction a higher priority.

* A server with a large number of views that do not need to be comlpetely
  up-to-date may benefit from removing the bypass on ``view_update`` in order to
  optimize the latency for regular document read and write operations, and build
  the views during quieter periods.