1
0
mirror of https://github.com/samba-team/samba.git synced 2024-12-22 13:34:15 +03:00

docs-xml: rewrite the vfs_aio_pthread manpage to reflect the >= 4.0.0 behavior

Signed-off-by: Stefan Metzmacher <metze@samba.org>
Reviewed-by: Volker Lendecke <vl@samba.org>
This commit is contained in:
Stefan Metzmacher 2018-04-20 11:04:20 +02:00 committed by Volker Lendecke
parent 74590c6795
commit 7ba243f3e7

View File

@ -13,7 +13,7 @@
<refnamediv>
<refname>vfs_aio_pthread</refname>
<refpurpose>implement async I/O in Samba vfs using a pthread pool</refpurpose>
<refpurpose>implement async open in Samba vfs using a pthread pool</refpurpose>
</refnamediv>
<refsynopsisdiv>
@ -30,40 +30,18 @@
<manvolnum>7</manvolnum></citerefentry> suite.</para>
<para>The <command>aio_pthread</command> VFS module enables asynchronous
I/O for Samba on platforms which have the pthreads API available,
without using the Posix AIO interface. Posix AIO can suffer from severe
limitations. For example, on some Linux versions the
real-time signals that it uses are broken under heavy load.
Other systems only allow AIO when special kernel modules are
loaded or only allow a certain system-wide amount of async
requests being scheduled. Systems based on glibc (most Linux
systems) only allow a single outstanding request per file
descriptor which essentially makes Posix AIO useless on systems
using the glibc implementation.</para>
<para>To work around all these limitations, the aio_pthread module
was written. It uses a pthread pool instead of the
internal Posix AIO interface to allow read and write calls
to be process asynchronously. A pthread pool is created
which expands dynamically by creating new threads as work is
given to it to a maximum of 100 threads per smbd process.
To change this limit see the "aio num threads" parameter
below. New threads are not created if idle threads are
available when a new read or write request is received,
the new work is given to an existing idle thread. Threads
terminate themselves if idle for one second.
opens (for new files) with <smbconfoption name="aio_pthread:aio open">yes</smbconfoption>
on platforms which have the pthreads API available,
support the openat() syscall and support per thread credentials (modern Linux kernels).
</para>
<para>
Note that the smb.conf parameters <command>aio read size</command>
and <command>aio write size</command> must also be set appropriately
for this module to be active.
</para>
<para>The module makes use of the global thread pool which uses the
<smbconfoption name="aio max threads"/> option.</para>
<para>This module MUST be listed last in any module stack as
the Samba VFS pread/pwrite interface is not thread-safe. This
module makes direct pread and pwrite system calls and does
NOT call the Samba VFS pread and pwrite interfaces.</para>
the Samba VFS open interface is not thread-safe. This
module makes direct openat() system calls and does
NOT call the Samba VFS open interfaces.</para>
</refsect1>
@ -76,9 +54,8 @@
<programlisting>
<smbconfsection name="[cooldata]"/>
<smbconfoption name="path">/data/ice</smbconfoption>
<smbconfoption name="aio read size">1024</smbconfoption>
<smbconfoption name="aio write size">1024</smbconfoption>
<smbconfoption name="vfs objects">aio_pthread</smbconfoption>
<smbconfoption name="aio_pthread:aio open">yes</smbconfoption>
</programlisting>
</refsect1>
@ -89,17 +66,17 @@
<variablelist>
<varlistentry>
<term>aio_pthread:aio num threads = INTEGER</term>
<term>aio_pthread:aio open = BOOL</term>
<listitem>
<para>Limit the maximum number of threads per smbd that
will be created in the thread pool to service IO requests.
<para>Try async opens for creating new files.
</para>
<para>By default this is set to 100.</para>
<para>The default is 'no'.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>VERSION</title>