docs-xml/manpages/vfs_aio_pthread.8.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
   3 <refentry id="vfs_aio_pthread.8">
   4
   5 <refmeta>
   6         <refentrytitle>vfs_aio_pthread</refentrytitle>
   7         <manvolnum>8</manvolnum>
   8         <refmiscinfo class="source">Samba</refmiscinfo>
   9         <refmiscinfo class="manual">System Administration tools</refmiscinfo>
  10         <refmiscinfo class="version">4.1</refmiscinfo>
  11 </refmeta>
  12
  13
  14 <refnamediv>
  15         <refname>vfs_aio_pthread</refname>
  16         <refpurpose>implement async I/O in Samba vfs using a pthread pool</refpurpose>
  17 </refnamediv>
  18
  19 <refsynopsisdiv>
  20         <cmdsynopsis>
  21                 <command>vfs objects = aio_pthread</command>
  22         </cmdsynopsis>
  23 </refsynopsisdiv>
  24
  25 <refsect1>
  26         <title>DESCRIPTION</title>
  27
  28         <para>This VFS module is part of the
  29         <citerefentry><refentrytitle>samba</refentrytitle>
  30         <manvolnum>7</manvolnum></citerefentry> suite.</para>
  31
  32         <para>The <command>aio_pthread</command> VFS module enables asynchronous
  33         I/O for Samba on platforms which have the pthreads API available,
  34         without using the Posix AIO interface. Posix AIO can suffer from severe
  35         limitations.  For example, on some Linux versions the
  36         real-time signals that it uses are broken under heavy load.
  37         Other systems only allow AIO when special kernel modules are
  38         loaded or only allow a certain system-wide amount of async
  39         requests being scheduled. Systems based on glibc (most Linux
  40         systems) only allow a single outstanding request per file
  41         descriptor which essentially makes Posix AIO useless on systems
  42         using the glibc implementation.</para>
  43
  44         <para>To work around all these limitations, the aio_pthread module
  45         was written. It uses a pthread pool instead of the
  46         internal Posix AIO interface to allow read and write calls
  47         to be process asynchronously. A pthread pool is created
  48         which expands dynamically by creating new threads as work is
  49         given to it to a maximum of 100 threads per smbd process.
  50         To change this limit see the "aio num threads" parameter
  51         below. New threads are not created if idle threads are
  52         available when a new read or write request is received,
  53         the new work is given to an existing idle thread. Threads
  54         terminate themselves if idle for one second.
  55         </para>
  56
  57         <para>
  58         Note that the smb.conf parameters <command>aio read size</command>
  59         and <command>aio write size</command> must also be set appropriately
  60         for this module to be active.
  61         </para>
  62
  63         <para>This module MUST be listed last in any module stack as
  64         the Samba VFS pread/pwrite interface is not thread-safe. This
  65         module makes direct pread and pwrite system calls and does
  66         NOT call the Samba VFS pread and pwrite interfaces.</para>
  67
  68 </refsect1>
  69
  70
  71 <refsect1>
  72         <title>EXAMPLES</title>
  73
  74         <para>Straight forward use:</para>
  75
  76 <programlisting>
  77         <smbconfsection name="[cooldata]"/>
  78         <smbconfoption name="path">/data/ice</smbconfoption>
  79         <smbconfoption name="aio read size">1024</smbconfoption>
  80         <smbconfoption name="aio write size">1024</smbconfoption>
  81         <smbconfoption name="vfs objects">aio_pthread</smbconfoption>
  82 </programlisting>
  83
  84 </refsect1>
  85
  86 <refsect1>
  87         <title>OPTIONS</title>
  88
  89         <variablelist>
  90
  91                 <varlistentry>
  92                 <term>aio_pthread:aio num threads = INTEGER</term>
  93                 <listitem>
  94                 <para>Limit the maximum number of threads per smbd that
  95                 will be created in the thread pool to service IO requests.
  96                 </para>
  97                 <para>By default this is set to 100.</para>
  98                 </listitem>
  99                 </varlistentry>
 100
 101         </variablelist>
 102 </refsect1>
 103 <refsect1>
 104         <title>VERSION</title>
 105
 106         <para>This man page is correct for version 4.0 of the Samba suite.
 107         </para>
 108 </refsect1>
 109
 110 <refsect1>
 111         <title>AUTHOR</title>
 112
 113         <para>The original Samba software and related utilities
 114         were created by Andrew Tridgell. Samba is now developed
 115         by the Samba Team as an Open Source project similar
 116         to the way the Linux kernel is developed.</para>
 117
 118 </refsect1>
 119
 120 </refentry>