[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]


From: Bruno Haible
Date: Tue, 2 May 2006 16:32:50 +0200
User-agent: KMail/1.5

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

   # include "unlocked-io.h"

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

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

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
# include "unlocked-io.h"
@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

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

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
# include "unlocked-io.h"

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

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
# include "unlocked-io.h"

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


reply via email to

[Prev in Thread] Current Thread [Next in Thread]