<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
  "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd" [
  <!ENTITY % threads.entities SYSTEM "entities.xml">
  %threads.entities;
]>
<section id="threads.design" last-revision="$Date: 2004/07/17 04:33:59 $">
  <title>Design</title>
  <para>With client/server and three-tier architectures becoming common place
  in today's world, it's becoming increasingly important for programs to be
  able to handle parallel processing. Modern day operating systems usually
  provide some support for this through native thread APIs. Unfortunately,
  writing portable code that makes use of parallel processing in C++ is made
  very difficult by a lack of a standard interface for these native APIs.
  Further, these APIs are almost universally C APIs and fail to take
  advantage of C++'s strengths, or to address concepts unique to C++, such as
  exceptions.</para>
  <para>The &Boost.Threads; library is an attempt to define a portable interface
  for writing parallel processes in C++.</para>
  <section id="threads.design.goals">
    <title>Goals</title>
    <para>The &Boost.Threads; library has several goals that should help to set
	it apart from other solutions. These goals are listed in order of precedence
	with full descriptions below.
    <variablelist>
	  <varlistentry>
	    <term>Portability</term>
		<listitem>
          <para>&Boost.Threads; was designed to be highly portable. The goal is
		  for the interface to be easily implemented on any platform that
		  supports threads, and possibly even on platforms without native thread
		  support.</para>
		</listitem>
	  </varlistentry>
	  <varlistentry>
        <term>Safety</term>
        <listitem>
          <para>&Boost.Threads; was designed to be as safe as possible. Writing
		  <link linkend="threads.glossary.thread-safe">thread-safe</link>
		  code is very difficult and successful libraries must strive to
		  insulate the programmer from dangerous constructs as much as
		  possible. This is accomplished in several ways:
          <itemizedlist>
            <listitem>
              <para>C++ language features are used to make correct usage easy
			  (if possible) and error-prone usage impossible or at least more
			  difficult. For example, see the <link
			  linkend="threads.concepts.Mutex">Mutex</link> and <link
			  linkend="threads.concepts.Lock">Lock</link> designs, and note
			  how they interact.</para>
            </listitem>
            <listitem>
              <para>Certain traditional concurrent programming features are
			  considered so error-prone that they are not provided at all. For
			  example, see <xref linkend="threads.rationale.events" />.</para>
            </listitem>
            <listitem>
              <para>Dangerous features, or features which may be misused, are
              identified as such in the documentation to make users aware of
              potential pitfalls.</para>
            </listitem>
          </itemizedlist></para>
		</listitem>
	  </varlistentry>
      <varlistentry>
	    <term>Flexibility</term>
		<listitem>
		  <para>&Boost.Threads; was designed to be flexible. This goal is often
		  at odds with <emphasis>safety</emphasis>. When functionality might be
		  compromised by the desire to keep the interface safe, &Boost.Threads;
		  has been designed to provide the functionality, but to make it's use
		  prohibitive for general use. In other words, the interfaces have been
		  designed such that it's usually obvious when something is unsafe, and
		  the documentation is written to explain why.</para>
        </listitem>
	  </varlistentry>
      <varlistentry>
        <term>Efficiency</term>
		<listitem>
          <para>&Boost.Threads; was designed to be as efficient as
		  possible. When building a library on top of another library there is
		  always a danger that the result will be so much slower than the
		  "native" API that programmers are inclined to ignore the higher level
		  API. &Boost.Threads; was designed to minimize the chances of this
		  occurring. The interfaces have been crafted to allow an implementation
		  the greatest chance of being as efficient as possible. This goal is
		  often at odds with the goal for <emphasis>safety</emphasis>. Every
		  effort was made to ensure efficient implementations, but when in
		  conflict <emphasis>safety</emphasis> has always taken
		  precedence.</para>
        </listitem>
	  </varlistentry>
    </variablelist></para>
  </section>
  <section>
    <title>Iterative Phases</title>
    <para>Another goal of &Boost.Threads; was to take a dynamic, iterative
	approach in its development. The computing industry is still exploring the
	concepts of parallel programming. Most thread libraries supply only simple
	primitive concepts for thread synchronization. These concepts are very
	simple, but it is very difficult to use them safely or to provide formal
	proofs for constructs built on top of them. There has been a lot of research
	into other concepts, such as in "Communicating Sequential Processes."
	&Boost.Threads; was designed in iterative steps, with each step providing 
	the building blocks necessary for the next step and giving the researcher 
	the tools necessary to explore new concepts in a portable manner.</para>
    <para>Given the goal of following a dynamic, iterative approach
	&Boost.Threads; shall go through several growth cycles. Each phase in its
	development shall be roughly documented here.</para>
  </section>
  <section>
    <title>Phase 1, Synchronization Primitives</title>
    <para>Boost is all about providing high quality libraries with
	implementations for many platforms. Unfortunately, there's a big problem
	faced by developers wishing to supply such high quality libraries, namely
	thread-safety. The C++ standard doesn't address threads at all, but real
	world programs often make use of native threading support. A portable
	library that doesn't address the issue of thread-safety is therefore not
	much help to a programmer who wants to use the library in his multithreaded
	application. So there's a very great need for portable primitives that will
	allow the library developer to create <link
	linkend="threads.glossary.thread-safe">thread-safe</link>
	implementations. This need far out weighs the need for portable methods to
	create and manage threads.</para>
    <para>Because of this need, the first phase of &Boost.Threads; focuses
	solely on providing portable primitive concepts for thread
	synchronization. Types provided in this phase include the
	<classname>boost::mutex</classname>, 
	<classname>boost::try_mutex</classname>,
	<classname>boost::timed_mutex</classname>, 
	<classname>boost::recursive_mutex</classname>,
	<classname>boost::recursive_try_mutex</classname>,
	<classname>boost::recursive_timed_mutex</classname>, and
	<classname>boost::lock_error</classname>. These are considered the "core"
	synchronization primitives, though there are others that will be added in
	later phases.</para>
  </section>
  <section id="threads.design.phase2">
    <title>Phase 2, Thread Management and Thread Specific Storage</title>
    <para>This phase addresses the creation and management of threads and
    provides a mechanism for thread specific storage (data associated with a
    thread instance). Thread management is a tricky issue in C++, so this
    phase addresses only the basic needs of multithreaded program. Later
    phases are likely to add additional functionality in this area. This
    phase of &Boost.Threads; adds the <classname>boost::thread</classname> and
	<classname>boost::thread_specific_ptr</classname> types. With these
	additions the &Boost.Threads; library can be considered minimal but
	complete.</para>
  </section>
  <section>
    <title>The Next Phase</title>
    <para>The next phase will address more advanced synchronization concepts,
    such as read/write mutexes and barriers.</para>
  </section>
</section>
