USE_UNLOCKED_IO

[Bruno Haible]

Hi Jim,

I'm trying to write documentation for the unlocked-io module.

The trigger for the unlocked-io module was already discussed long ago; the
current recommendation is, as far as I can see,
  - that USE_UNLOCKED_IO is defined to 1 by default in m4/unlocked-io.m4,
  - that multithread programs should define USE_UNLOCKED_IO to 0 themselves.

But what should a gnulib module author do who opens a FILE and uses it
locally in a single thread? Like exclude.c, getloadavg.c, getusershell.c,
localcharset.c, mountlist.c do. If they use

   #if USE_UNLOCKED_IO
   # include "unlocked-io.h"
   #endif

the optimization is not available to multithreaded programs. If they use

   #include "unlocked-io.h"

then we get a dependency on the module 'unlocked-io' which some people
considered unwelcome.

The documentation I've come up so far is:
=========================================================================
@node unlocked-io
@section unlocked-io

The FILE primitives defined in <stdio.h> on glibc systems are multithread-safe.
Unfortunately, the locking in @code{getc()} and @code{putc()} slows down
applications a lot that perform their I/O character by character.  This
locking is actually unnecessary when

@enumerate
@item
the application is unithreaded (does not use more than one thread) anyway, or

@item
the FILE object is only known to one particular thread and not stored in
global variables.
@end @enumerate

In these cases it is desirable to use the "unlocked" variants of the FILE
primitives, also provided by glibc.

The @code{unlocked-io} module provides a header file that defines the
FILE primitives to the "unlocked" ones. It also defines @code{USE_UNLOCKED_IO}
to 1.

To activate it for unithreaded applications, simply add the gnulib module
@code{unlocked-io} to your application.

To activate it locally for a module that operates on FILE objects known to a
single thread only, include "unlocked-io.h" unconditionally, and add the
gnulib module @code{unlocked-io} to your application.

Gnulib module authors should use the idiom
@smallexample
#if USE_UNLOCKED_IO
# include "unlocked-io.h"
#endif
@end smallexample
in all modules that use <stdio.h>.  This idiom ensures that unithreaded
programs are not penalized by FILE locking.
=============================================================================

As you can see, a single #if USE_UNLOCKED_IO is not enough, and different
recommendations should be given to
   - modules that use FILE in a single thread, opening it themselves, and to
   - all other modules that use <stdio.h>.

The problem that we have now is that a module that wants to optimize only
itself must include "unlocked-io.h", which requires the use of
gl_FUNC_GLIBC_UNLOCKED_IO, which defines USE_UNLOCKED_IO to 1, which
enables the optimization in all other modules and defeats multithreaded
programs.

I can see two solutions, depending on the meaning that you attach to the
macro USE_UNLOCKED_IO.


Solution A:

USE_UNLOCKED_IO means "unlocked-io.h is present in the surrounding package".

Modules that open a FILE on their own and use it in a single thread should do
#if USE_UNLOCKED_IO
# include "unlocked-io.h"
#endif

All other modules should do
#if USE_UNLOCKED_IO && UNITHREADED
# include "unlocked-io.h"
#endif

Add a module 'unithreaded' that does  #define UNITHREADED 1.


Solution B:

USE_UNLOCKED_IO means "the program is unithreaded".

Modules that open a FILE on their own and use it in a single thread should do
#include "unlocked-io.h"

All other modules should do
#if USE_UNLOCKED_IO
# include "unlocked-io.h"
#endif

Remove the setting of USE_UNLOCKED_IO from gl_FUNC_GLIBC_UNLOCKED_IO.

Add a module 'unithreaded' that does  #define USE_UNLOCKED_IO 1.

Recommend to people who don't want gnulib's unlocked-io.h to use
"gnulib-tool --avoid=unlocked-io" and create an empty unlocked-io.h in their
package.


Bruno