unlocked-io-internal: New module.

* m4/unlocked-io.m4 (gl_FUNC_GLIBC_UNLOCKED_IO): Don't define
USE_UNLOCKED_IO here.
* modules/unlocked-io-internal: New file, based on modules/unlocked-io.
* modules/unlocked-io (Description): Clarify.
(Files, Depends-on): Just use the unlocked-io-internal module.
(configure.ac): Define GNULIB_STDIO_SINGLE_THREAD and USE_UNLOCKED_IO
here.
* doc/multithread.texi: Clarify when the 'unlocked-io' module can be
used.

1 files changed, 11 insertions, 5 deletions

diff --git a/doc/multithread.texi b/doc/multithread.texi
index 9b1bc2e174..7fe19a7817 100644
--- a/doc/multithread.texi
+++ b/doc/multithread.texi
@@ -258,11 +258,17 @@ if (mt) gl_lock_lock (some_lock);
 if (mt) gl_lock_unlock (some_lock);
 @end smallexample
 @item
-The @code{unlocked-io} module is applicable only if all the programs in your
-package are single-threaded.  It optimizes the operations on @code{FILE}
-streams.  You need extra code for this: include the @code{"unlocked-io.h"}
-header file.  Some Gnulib modules that do operations on @code{FILE} streams
-have these preparations already included.
+You may use the @code{unlocked-io} module if you want the @code{FILE} stream
+functions @code{getc}, @code{putc}, etc.@: to use unlocked I/O if available,
+throughout the package.  Unlocked I/O can improve performance, sometimes
+dramatically.  But unlocked I/O is safe only in single-threaded programs,
+as well as in multithreaded programs for which you can guarantee that
+every @code{FILE} stream, including @code{stdin}, @code{stdout}, @code{stderr},
+is used only in a single thread.
+
+You need extra code for this optimization to be effective: include the
+@code{"unlocked-io.h"} header file.  Some Gnulib modules that do operations
+on @code{FILE} streams have these preparations already included.
 @item
 You may define the C macro @code{GNULIB_WCHAR_SINGLE}, if all the programs in
 your package are single-threaded and won't change the locale after it has