Multithreading
**************

Multithreading is a programming paradigm.  In a multithreaded program, multiple threads execute concurrently (or quasi concurrently) at different places in the program.

There are three motivations for using multithreading in a program:

  * Exploiting CPU hardware with multiple execution units.  Nowadays, many CPUs have 2 to 8 execution cores in a single chip.  Additionally, often multiple CPU chips are combined in a single package.  Thus, some CPU packages support 64 or 96 simultaneous threads of execution.

  * Simplifying program architecture.  When a program has to read from different file descriptors, network sockets, or event channels at the same time, the classical single-threaded architecture is to have a main loop which uses select or poll on all the descriptors and then dispatches according to from which descriptor input arrived.  In a multi-threaded program, you allocate one thread for each descriptor, and these threads can be programmed and managed independently.

  * Offloading work from signal handlers.  A signal handler is not allowed to call malloc; therefore you are very limited in what you can do in a signal handler.  But a signal handler can notify a thread, and the thread can then do the appropriate processing, as complex as it needs to be.

A multithreading API offers

  * Primitives for creating threads, for waiting until threads are terminated, and for reaping their results.

  * Primitives through which different threads can operate on the same data or use some data structures for communicating between the threads.  These are called ``mutexes'' or ``locks''.

  * Primitives for executing a certain (initialization) code at most once.

  * Primitives for notifying one or more other threads.  These are called wait queues or ``condition variables''.

  * Primitives for allowing different threads to have different values for a variable.  Such a variable is said to reside in ``thread-local storage'' or ``thread-specific storage''.

  * Primitives for relinquishing control for some time and letting other threads go.

Note: Programs that achieve multithreading through OpenMP (cf. the gnulib module openmp) don't create and manage their threads themselves. Nevertheless, they need to use mutexes/locks in many cases.

The three multithreading APIs
=============================

Three multithreading APIs are available to Gnulib users:

  * POSIX multithreading,

  * ISO C multithreading,

  * Gnulib multithreading.

They are supported on all platforms that have multithreading in one form or the other.  Currently, these are all platforms supported by Gnulib, except for Minix.

The main differences are:

  * The exit code of a thread is a pointer in the POSIX and Gnulib APIs, but only an int in the ISO C API.

  * The POSIX API has additional facilities for detaching threads, setting the priority of a thread, assigning a thread to a certain set of processors, and much more.

  * In the POSIX and ISO C APIs, most functions have a return code, and you are supposed to check the return code; even locking and unlocking a lock can fail.  In the Gnulib API, many functions don't have a return code; if they cannot complete, the program aborts.  This sounds harsh, but such aborts have not been reported in 12 years.

  * In the ISO C API, the initialization of a statically allocated lock is clumsy: You have to initialize it through a once-only function.

Choosing the right multithreading API
=====================================

Here are guidelines for determining which multithreading API is best for your code.

In programs that use advanced POSIX APIs, such as spin locks, detached threads (pthread_detach), signal blocking (pthread_sigmask), priorities (pthread_setschedparam), processor affinity (pthread_setaffinity_np), it is best to use the POSIX API.  This is because you cannot convert an ISO C thrd_t or a Gnulib gl_thread_t to a POSIX pthread_t.

In code that is shared with glibc, it is best to use the POSIX API as well.

In libraries, it is best to use the Gnulib API.  This is because it gives the person who builds the library an option --enable-threads={isoc,posix,windows}, that determines on which native multithreading API of the platform to rely.  In other words, with this choice, you can minimize the amount of glue code that your library needs to contain.

In the other cases, the POSIX API and the Gnulib API are equally well suited.

The ISO C API is never the best choice, as of this writing (2020).

The POSIX multithreading API
============================

The POSIX multithreading API is documented in POSIX https://pubs.opengroup.org/onlinepubs/9699919799/.

To make use of POSIX multithreading, even on platforms that don't support it natively (most prominently, native Windows), use the following Gnulib modules:

Purpose   Module
For thread creation and management:    pthread-thread
For simple and recursive locks:    pthread-mutex
For read-write locks:    pthread-rwlock
For once-only execution:    pthread-once
For ``condition variables'' (wait queues):    pthread-cond
For thread-local storage:    pthread-tss
For relinquishing control:    sched_yield
For spin locks:    pthread-spin

There is also a convenience module named pthread which depends on all of these (except sched_yield); so you don't need to enumerate these modules one by one.

The ISO C multithreading API
============================

The ISO C multithreading API is documented in ISO C 11 http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf.

To make use of ISO C multithreading, even on platforms that don't support it or have severe bugs, use the following Gnulib modules:

Purpose   Module
For thread creation and management:    thrd
For simple locks, recursive locks, and read-write locks:
mtx
For once-only execution:    mtx
For ``condition variables'' (wait queues):    cnd
For thread-local storage:    tss

There is also a convenience module named threads which depends on all of these; so you don't need to enumerate these modules one by one.

The Gnulib multithreading API
=============================

The Gnulib multithreading API is documented in the respective include files:

  * <glthread/thread.h>

  * <glthread/lock.h>

  * <glthread/cond.h>

  * <glthread/tls.h>

  * <glthread/yield.h>

To make use of Gnulib multithreading, use the following Gnulib modules:

Purpose   Module
For thread creation and management:    thread
For simple locks, recursive locks, and read-write locks:
lock
For once-only execution:    lock
For ``condition variables'' (wait queues):    cond
For thread-local storage:    tls
For relinquishing control:    yield

The Gnulib multithreading supports a configure option --enable-threads={isoc,posix,windows}, that chooses the underlying thread implementation.  Currently (2020):

  * --enable-threads=posix is supported and is the best choice on all platforms except for native Windows.  It may also work, to a limited extent, on mingw with the winpthreads library, but is not recommended there.

  * --enable-threads=windows is supported and is the best choice on native Windows platforms (mingw and MSVC).

  * --enable-threads=isoc is supported on all platforms that have the ISO C multithreading API.  However, --enable-threads=posix is always a better choice.

Optimizations of multithreaded code
===================================

Despite all the optimizations of multithreading primitives that have been implemented over the years --- from atomic operations in hardware (https://en.wikipedia.org/wiki/Compare-and-swap), over futexes (https://en.wikipedia.org/wiki/Futex) and restartable sequences (https://www.efficios.com/blog/2019/02/08/linux-restartable-sequences/) in the Linux kernel, to lock elision [1] (https://lwn.net/Articles/534758/) [2] (https://www.gnu.org/software/libc/manual/html_node/Elision-Tunables.html)) --- single-threaded programs can still profit performance-wise from the assertion that they are single-threaded.

Gnulib defines four facilities that help optimizing for the single-threaded case.

  * The Gnulib multithreading API, when used on glibc ≤ 2.32 and *BSD systems, uses weak symbols to detect whether the program is linked with libpthread.  If not, the program has no way to create additional threads and must therefore be single-threaded.  This optimization applies to all the Gnulib multithreading API (locks, thread-local storage, and more).

  * The thread-optim module, on glibc ≥ 2.32 systems, allows your code to skip locking between threads (regardless which of the three multithreading APIs you use).  You need extra code for this: include the "thread-optim.h" header file, and use the macro gl_multithreaded like this:

          bool mt = gl_multithreaded ();
          if (mt) gl_lock_lock (some_lock);
          ...
          if (mt) gl_lock_unlock (some_lock);

  * You may use the unlocked-io module 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.

     You need extra code for this optimization to be effective: include the "unlocked-io.h" header file.  Some Gnulib modules that do operations on FILE streams have these preparations already included.

  * You may define the C macro GNULIB_REGEX_SINGLE_THREAD, if all the programs in your package invoke the functions of the regex module only from a single thread.

  * You may define the C macro GNULIB_MBRTOWC_SINGLE_THREAD, if all the programs in your package invoke the functions mbrtowc, mbrtoc32, and the functions of the regex module only from a single thread.  (The regex module uses mbrtowc under the hood.)

  * You may define the C macro GNULIB_WCHAR_SINGLE_LOCALE, if all the programs in your package set the locale early and

       * don't change the locale after it has been initialized, and

       * don't call locale sensitive functions (mbrtowc, wcwidth, etc.) before the locale has been initialized.

     This macro optimizes the functions mbrtowc, mbrtoc32, and wcwidth.

  * You may define the C macro GNULIB_GETUSERSHELL_SINGLE_THREAD, if all the programs in your package invoke the functions setusershell, getusershell, endusershell only from a single thread.

  * You may define the C macro GNULIB_EXCLUDE_SINGLE_THREAD, if all the programs in your package invoke the functions of the exclude module only from a single thread.