<?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;
]>
<glossary id="threads.glossary" last-revision="$Date: 2004/07/17 04:33:59 $">
  <title>Glossary</title>
  <para>Definitions are given in terms of the C++ Standard
  &cite.ISO98;. References to the standard are in the form [1.2.3/4], which
  represents the section number, with the paragraph number following the
  "/".</para>
  <para>Because the definitions are written in something akin to "standardese",
  they can be difficult to understand. The intent isn't to confuse, but rather
  to clarify the additional requirements &Boost.Threads; places on a C++
  implementation as defined by the C++ Standard.</para>
  <glossentry id="threads.glossary.thread">
    <glossterm>Thread</glossterm>
    <glossdef>
	  <para>Thread is short for "thread of execution". A thread of execution is
	  an execution environment [1.9/7] within the execution environment of a C++
	  program [1.9]. The main() function [3.6.1] of the program is the initial
	  function of the initial thread. A program in a multithreading environment
	  always has an initial thread even if the program explicitly creates no
	  additional threads.</para>
      <para>Unless otherwise specified, each thread shares all aspects of its
	  execution environment with other threads in the program. Shared aspects of
	  the execution environment include, but are not limited to, the
	  following:</para>
	  <itemizedlist>
        <listitem><para>Static storage duration (static, extern) objects
		[3.7.1].</para></listitem>
	    <listitem><para>Dynamic storage duration (heap) objects [3.7.3]. Thus
		each memory allocation will return a unique addresses, regardless of the
		thread making the allocation request.</para></listitem>
        <listitem><para>Automatic storage duration (stack) objects [3.7.2]
		accessed via pointer or reference from another thread.</para></listitem>
        <listitem><para>Resources provided by the operating system. For example,
		files.</para></listitem>
        <listitem><para>The program itself. In other words, each thread is
		executing some function of the same program, not a totally different
		program.</para></listitem>
      </itemizedlist>
      <para>Each thread has its own:</para>
      <itemizedlist>
        <listitem><para>Registers and current execution sequence (program
		counter) [1.9/5].</para></listitem>
        <listitem><para>Automatic storage duration (stack) objects
		[3.7.2].</para></listitem>
      </itemizedlist>
    </glossdef>
  </glossentry>
  <glossentry id="threads.glossary.thread-safe">
    <glossterm>Thread-safe</glossterm>
	<glossdef>
      <para>A program is thread-safe if it has no <link
	  linkend="threads.glossary.race-condition">race conditions</link>, does
	  not <link linkend="threads.glossary.deadlock">deadlock</link>, and has
	  no <link linkend="threads.glossary.priority-failure">priority
	  failures</link>.</para>
	  <para>Note that thread-safety does not necessarily imply efficiency, and
	  than while some thread-safety violations can be determined statically at
	  compile time, many thread-safety errors can only only be detected at
	  runtime.</para>
	</glossdef>
  </glossentry>
  <glossentry id="threads.glossary.thread-state">
    <glossterm>Thread State</glossterm>
	<glossdef>
      <para>During the lifetime of a thread, it shall be in one of the following
	  states:</para>
	  <table>
		<title>Thread States</title>
		<tgroup cols="2" align="left">
			<thead>
				<row>
					<entry>State</entry>
					<entry>Description</entry>
				</row>
			</thead>
			<tbody>
				<row>
					<entry>Ready</entry>
					<entry>Ready to run, but waiting for a processor.</entry>
				</row>
				<row>
					<entry>Running</entry>
					<entry>Currently executing on a processor. Zero or more threads
					may be running at any time, with a maximum equal to the number of
					processors.</entry>
				</row>
				<row>
					<entry>Blocked</entry>
					<entry>Waiting for some resource other than a processor which is
					not currently available, or for the completion of calls to library
					functions [1.9/6]. The term "waiting" is synonymous with
					"blocked"</entry>
				</row>
				<row>
					<entry>Terminated</entry>
					<entry>Finished execution but not yet detached or joined.</entry>
				</row>
			</tbody>
		</tgroup>
	  </table>
      <para>Thread state transitions shall occur only as specified:</para>
	  <table>
		<title>Thread States Transitions</title>
		<tgroup cols="3" align="left">
			<thead>
				<row>
					<entry>From</entry>
					<entry>To</entry>
					<entry>Cause</entry>
				</row>
			</thead>
			<tbody>
				<row>
					<entry>[none]</entry>
					<entry>Ready</entry>
					<entry><para>Thread is created by a call to a library function. 
					In the case of the initial thread, creation is implicit and 
					occurs during the startup of the main() function [3.6.1].</para></entry>
				</row>
				<row>
					<entry>Ready</entry>
					<entry>Running</entry>
					<entry><para>Processor becomes available.</para></entry>
				</row>
				<row>
					<entry>Running</entry>
					<entry>Ready</entry>
					<entry>Thread preempted.</entry>
				</row>
				<row>
					<entry>Running</entry>
					<entry>Blocked</entry>
					<entry>Thread calls a library function which waits for a resource or
					for the completion of I/O.</entry>
				</row>
				<row>
					<entry>Running</entry>
					<entry>Terminated</entry>
					<entry>Thread returns from its initial function, calls a thread
					termination library function, or is canceled by some other thread
					calling a thread termination library function.</entry>
				</row>
				<row>
					<entry>Blocked</entry>
					<entry>Ready</entry>
					<entry>The resource being waited for becomes available, or the
					blocking library function completes.</entry>
				</row>
				<row>
					<entry>Terminated</entry>
					<entry>[none]</entry>
					<entry>Thread is detached or joined by some other thread calling the
					appropriate library function, or by program termination
					[3.6.3].</entry>
				</row>
			</tbody>
		</tgroup>
      </table>
      <para>[Note: if a suspend() function is added to the threading library,
	  additional transitions to the blocked state will have to be added to the
	  above table.]</para>
    </glossdef>
  </glossentry>
  <glossentry id="threads.glossary.race-condition">
    <glossterm>Race Condition</glossterm>
	<glossdef>
      <para>A race condition is what occurs when multiple threads read from and write
	  to the same memory without proper synchronization, resulting in an incorrect
	  value being read or written. The result of a race condition may be a bit
	  pattern which isn't even a valid value for the data type. A race condition
	  results in undefined behavior [1.3.12].</para>
      <para>Race conditions can be prevented by serializing memory access using
	  the tools provided by &Boost.Threads;.</para>
    </glossdef>
  </glossentry>
  <glossentry id="threads.glossary.deadlock">
    <glossterm>Deadlock</glossterm>
	<glossdef>
      <para>Deadlock is an execution state where for some set of threads, each
	  thread in the set is blocked waiting for some action by one of the other
	  threads in the set. Since each is waiting on the others, none will ever
	  become ready again.</para>
	</glossdef>
  </glossentry>
  <glossentry id="threads.glossary.starvation">
    <glossterm>Starvation</glossterm>
	<glossdef>
	  <para>The condition in which a thread is not making sufficient progress in
	  its work during a given time interval.</para>
	</glossdef>
  </glossentry>
  <glossentry id="threads.glossary.priority-failure">
    <glossterm>Priority Failure</glossterm>
	<glossdef>
	  <para>A priority failure (such as priority inversion or infinite overtaking)
	  occurs when threads are executed in such a sequence that required work is not
	  performed in time to be useful.</para>
	</glossdef>
  </glossentry>
  <glossentry id="threads.glossary.undefined-behavior">
    <glossterm>Undefined Behavior</glossterm>
	<glossdef>
	  <para>The result of certain operations in &Boost.Threads; is undefined;
	  this means that those operations can invoke almost any behavior when
	  they are executed.</para>
	  
	  <para>An operation whose behavior is undefined can work "correctly"
	  in some implementations (i.e., do what the programmer thought it
	  would do), while in other implementations it may exhibit almost
	  any "incorrect" behavior--such as returning an invalid value,
	  throwing an exception, generating an access violation, or terminating 
	  the process.</para>
	  
	  <para>Executing a statement whose behavior is undefined is a
	  programming error.</para>
	</glossdef>
  </glossentry>
  <glossentry id="threads.glossary.memory-visibility">
    <glossterm>Memory Visibility</glossterm>
	<glossdef>
	  <para>An address [1.7] shall always point to the same memory byte,
	  regardless of the thread or processor dereferencing the address.</para>
      <para>An object [1.8, 1.9] is accessible from multiple threads if it is of
	  static storage duration (static, extern) [3.7.1], or if a pointer or
	  reference to it is explicitly or implicitly dereferenced in multiple
	  threads.</para>
	  <para>For an object accessible from multiple threads, the value of the
	  object accessed from one thread may be indeterminate or different from the
	  value accessed from another thread, except under the conditions specified in
	  the following table. For the same row of the table, the value of an object
	  accessible at the indicated sequence point in thread A will be determinate
	  and the same if accessed at or after the indicated sequence point in thread
	  B, provided the object is not otherwise modified. In the table, the
	  "sequence point at a call" is the sequence point after the evaluation of all
	  function arguments [1.9/17], while the "sequence point after a call" is the
	  sequence point after the copying of the returned value... [1.9/17].</para>
      <table>
		<title>Memory Visibility</title>
		<tgroup cols="2">
			<thead>
				<row>
					<entry>Thread A</entry>
					<entry>Thread B</entry>
				</row>
			</thead>
			<tbody>
				<row>
					<entry>The sequence point at a call to a library thread-creation
					function.</entry>
					<entry>The first sequence point of the initial function in the new
					thread created by the Thread A call.</entry>
				</row>
				<row>
					<entry>The sequence point at a call to a library function which
					locks a mutex, directly or by waiting for a condition
					variable.</entry>
					<entry>The sequence point after a call to a library function which
					unlocks the same mutex.</entry>
				</row>
				<row>
					<entry>The last sequence point before thread termination.</entry>
					<entry>The sequence point after a call to a library function which
					joins the terminated thread.</entry>
				</row>
				<row>
					<entry>The sequence point at a call to a library function which
					signals or broadcasts a condition variable.</entry>
					<entry>The sequence point after the call to the library function
					which was waiting on that same condition variable or signal.</entry>
				</row>
			</tbody>
		</tgroup>
      </table>
      <para>The architecture of the execution environment and the observable
	  behavior of the abstract machine [1.9] shall be the same on all
	  processors.</para>
	  <para>The latitude granted by the C++ standard for an implementation to
	  alter the definition of observable behavior of the abstract machine to
	  include additional library I/O functions [1.9/6] is extended to include
	  threading library functions.</para>
	  <para>When an exception is thrown and there is no matching exception handler
	  in the same thread, behavior is undefined. The preferred behavior is the
	  same as when there is no matching exception handler in a program
	  [15.3/9]. That is, terminate() is called, and it is implementation-defined
	  whether or not the stack is unwound.</para>
    </glossdef>
  </glossentry>
  <section>
    <title>Acknowledgements</title>
    <para>This document was originally written by Beman Dawes, and then much
	improved by the incorporation of comments from William Kempf, who now
	maintains the contents.</para>
	<para>The visibility rules are based on &cite.Butenhof97;.</para>
  </section>
</glossary>