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.

5 files changed, 63 insertions, 16 deletions

diff --git a/ChangeLog b/ChangeLog
index cfa60e0cd1..80d97a0f05 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,18 @@
 2021-03-06  Bruno Haible  <bruno@clisp.org>
 
+	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.
+
+2021-03-06  Bruno Haible  <bruno@clisp.org>
+
 	posixtm: Remove unused includes.
 	* lib/posixtm.c: Don't include <stdio.h>, <sys/types.h>, unlocked-io.h.
 
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
diff --git a/m4/unlocked-io.m4 b/m4/unlocked-io.m4
index a2dc8a144a..b689020ff4 100644
--- a/m4/unlocked-io.m4
+++ b/m4/unlocked-io.m4
@@ -1,4 +1,4 @@
-# unlocked-io.m4 serial 15
+# unlocked-io.m4 serial 16
 
 # Copyright (C) 1998-2006, 2009-2021 Free Software Foundation, Inc.
 #
@@ -16,11 +16,6 @@ dnl on Solaris 2.6).
 
 AC_DEFUN([gl_FUNC_GLIBC_UNLOCKED_IO],
 [
-  AC_DEFINE([USE_UNLOCKED_IO], [1],
-    [Define to 1 if you want getc etc. to use unlocked I/O if available.
-     Unlocked I/O can improve performance in unithreaded apps,
-     but it is not safe for multithreaded apps.])
-
   dnl Persuade glibc and Solaris <stdio.h> to declare
   dnl fgets_unlocked(), fputs_unlocked() etc.
   AC_REQUIRE([gl_USE_SYSTEM_EXTENSIONS])
diff --git a/modules/unlocked-io b/modules/unlocked-io
index 000fe32c19..2ed3417e68 100644
--- a/modules/unlocked-io
+++ b/modules/unlocked-io
@@ -1,15 +1,24 @@
 Description:
-Enable faster, non-thread-safe stdio functions if available.
+Enable faster, non-thread-safe stdio functions if available,
+globally throughout the package.
 
 Files:
-lib/unlocked-io.h
-m4/unlocked-io.m4
 
 Depends-on:
-extensions
+unlocked-io-internal
 
 configure.ac:
-gl_FUNC_GLIBC_UNLOCKED_IO
+AC_DEFINE([GNULIB_STDIO_SINGLE_THREAD], [1],
+  [Define to 1 if you want the FILE stream functions getc, 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 FILE stream, including stdin, stdout, stderr, is used only
+   in a single thread.])
+
+AC_DEFINE([USE_UNLOCKED_IO], [GNULIB_STDIO_SINGLE_THREAD],
+  [An alias of GNULIB_STDIO_SINGLE_THREAD.])
 
 Makefile.am:
 
diff --git a/modules/unlocked-io-internal b/modules/unlocked-io-internal
new file mode 100644
index 0000000000..b78944cc9f
--- /dev/null
+++ b/modules/unlocked-io-internal
@@ -0,0 +1,24 @@
+Description:
+Allow use of faster, non-thread-safe stdio functions if available,
+in specific modules.
+
+Files:
+lib/unlocked-io.h
+m4/unlocked-io.m4
+
+Depends-on:
+extensions
+
+configure.ac:
+gl_FUNC_GLIBC_UNLOCKED_IO
+
+Makefile.am:
+
+Include:
+"unlocked-io.h"
+
+License:
+GPL
+
+Maintainer:
+Jim Meyering