source: downloads/boost_1_33_1/libs/thread/doc/thread-ref.xml @ 13

<?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;
]>
<header name="boost/thread/thread.hpp"
  last-revision="$Date: 2005/12/04 18:11:08 $">
  <namespace name="boost">
    <class name="thread">
                <purpose>
                        <para>The <classname>thread</classname> class represents threads of
                        execution, and provides the functionality to create and manage 
                        threads within the &Boost.Threads; library. See 
                        <xref linkend="threads.glossary"/> for a precise description of 
                        <link linkend="threads.glossary.thread">thread of execution</link>,
                        and for definitions of threading-related terms and of thread states such as 
                        <link linkend="threads.glossary.thread-state">blocked</link>.</para>
                </purpose>

                <description>
                        <para>A <link linkend="threads.glossary.thread">thread of execution</link>
                        has an initial function. For the program's initial thread, the initial 
                        function is <code>main()</code>. For other threads, the initial 
                        function is <code>operator()</code> of the function object passed to
                        the <classname>thread</classname> object's constructor.</para>

                        <para>A thread of execution  is said to be &quot;finished&quot; 
                        or to have &quot;finished execution&quot; when its initial function returns or 
                        is terminated. This includes completion of all thread cleanup 
                        handlers, and completion of the normal C++ function return behaviors,
                        such as destruction of automatic storage (stack) objects and releasing 
                        any associated implementation resources.</para>

                        <para>A thread object has an associated state which is either
                        &quot;joinable&quot; or &quot;non-joinable&quot;.</para>

                        <para>Except as described below, the policy used by an implementation
                        of &Boost.Threads; to schedule transitions between thread states is 
                        unspecified.</para>

                        <para><note>Just as the lifetime of a file may be different from the
                        lifetime of an <code>iostream</code> object which represents the file, the lifetime
                        of a thread of execution may be different from the 
                        <classname>thread</classname> object which represents the thread of 
                        execution. In particular, after a call to <code>join()</code>,
                        the thread of execution will no longer exist even though the 
                        <classname>thread</classname> object continues to exist until the 
                        end of its normal lifetime. The converse is also possible; if 
                        a <classname>thread</classname> object is destroyed without 
                        <code>join()</code> first having been called, the thread of execution 
                        continues until its initial function completes.</note></para>
                </description>

                <inherit access="private">
                        <type><classname>boost::noncopyable</classname></type>
                        <purpose>Exposition only</purpose>
                </inherit>

                <constructor>
                        <effects>Constructs a <classname>thread</classname> object 
                        representing the current thread of execution.</effects>
                        
                        <postconditions><code>*this</code> is non-joinable.</postconditions>
                        
                        <notes><emphasis role="bold">Danger:</emphasis>
                        <code>*this</code> is valid only within the current thread.</notes>
                </constructor>

                <constructor specifiers="explicit">
                        <parameter name="threadfunc">
                                <paramtype>const boost::function0&lt;void&gt;&amp;</paramtype>
                        </parameter>
                        
                        <effects>
                                Starts a new thread of execution and constructs a 
                                <classname>thread</classname> object representing it. 
                                Copies <code>threadfunc</code> (which in turn copies
                                the function object wrapped by <code>threadfunc</code>) 
                                to an internal location which persists for the lifetime 
                                of the new thread of execution. Calls <code>operator()</code>
                                on the copy of the <code>threadfunc</code> function object 
                                in the new thread of execution.
                        </effects>
                        
                        <postconditions><code>*this</code> is joinable.</postconditions>

                        <throws><code>boost::thread_resource_error</code> if a new thread
                        of execution cannot be started.</throws>
                </constructor>
                
                <destructor>
                        <effects>Destroys <code>*this</code>. The actual thread of 
                        execution may continue to execute after the 
                        <classname>thread</classname> object has been destroyed.
                        </effects>
                        
                        <notes>If <code>*this</code> is joinable the actual thread 
                        of execution becomes &quot;detached&quot;. Any resources used 
                        by the thread will be reclaimed when the thread of execution 
                        completes. To ensure such a thread of execution runs to completion
                        before the <classname>thread</classname> object is destroyed, call
                        <code>join()</code>.</notes>
                </destructor>
                
                <method-group name="comparison">
                        <method name="operator==" cv="const">
                                <type>bool</type>
                                
                                <parameter name="rhs">
                                        <type>const thread&amp;</type>
                                </parameter>
                                
                                <requires>The thread is non-terminated or <code>*this</code>
                                is joinable.</requires>
                                  
                                <returns><code>true</code> if <code>*this</code> and 
                                <code>rhs</code> represent the same thread of 
                                execution.</returns>
                        </method>
                        
                        <method name="operator!=" cv="const">
                                <type>bool</type>
                                
                                <parameter name="rhs">
                                        <type>const thread&amp;</type>
                                </parameter>
                                
                                <requires>The thread is non-terminated or <code>*this</code>
                                is joinable.</requires>
                                  
                                <returns><code>!(*this==rhs)</code>.</returns>
                        </method>
                </method-group>

                <method-group name="modifier">
                        <method name="join">
                                <type>void</type>
                                
                                <requires><code>*this</code> is joinable.</requires>
                                  
                                <effects>The current thread of execution blocks until the 
                                initial function of the thread of execution represented by 
                                <code>*this</code> finishes and all resources are 
                                reclaimed.</effects>
                                
                                <postcondition><code>*this</code> is non-joinable.</postcondition>
                                
                                <notes>If <code>*this == thread()</code> the result is 
                                implementation-defined. If the implementation doesn't
                                detect this the result will be 
                                <link linkend="threads.glossary.deadlock">deadlock</link>.
                                </notes>
                        </method>
                </method-group>

                <method-group name="static">
                        <method name="sleep" specifiers="static">
                                <type>void</type>
                                
                                <parameter name="xt">
                                        <paramtype>const <classname>xtime</classname>&amp;</paramtype>
                                </parameter>
                                
                                <effects>The current thread of execution blocks until 
                                <code>xt</code> is reached.</effects>
                        </method>
                        
                        <method name="yield" specifiers="static">
                                <type>void</type>

                                <effects>The current thread of execution is placed in the
                                <link linkend="threads.glossary.thread-state">ready</link> 
                                state.</effects>
                                
                                <notes>
                                        <simpara>Allow the current thread to give up the rest of its 
                                        time slice (or other scheduling quota) to another thread. 
                                        Particularly useful in non-preemptive implementations.</simpara>
                                </notes>
                        </method>
                </method-group>
        </class>

        <class name="thread_group">
                <purpose>
                        The <classname>thread_group</classname> class provides a container
                        for easy grouping of threads to simplify several common thread 
                        creation and management idioms.
                </purpose>

                <inherit access="private">
                        <type><classname>boost::noncopyable</classname></type>
                        <purpose>Exposition only</purpose>
                </inherit>


                <constructor>
                        <effects>Constructs an empty <classname>thread_group</classname>
                        container.</effects>
                </constructor>
                
                <destructor>
                        <effects>Destroys each contained thread object. Destroys <code>*this</code>.</effects>
                        
                        <notes>Behavior is undefined if another thread references 
                        <code>*this </code> during the execution of the destructor.
                        </notes>
                </destructor>

                <method-group name="modifier">
                        <method name="create_thread">
                                <type><classname>thread</classname>*</type>
                                
                                <parameter name="threadfunc">
                                        <paramtype>const boost::function0&lt;void&gt;&amp;</paramtype>
                                </parameter>
                                
                                <effects>Creates a new <classname>thread</classname> object 
                                that executes <code>threadfunc</code> and adds it to the 
                                <code>thread_group</code> container object's list of managed
                                <classname>thread</classname> objects.</effects>
                                
                                <returns>Pointer to the newly created 
                                <classname>thread</classname> object.</returns>
                        </method>

                        <method name="add_thread">
                                <type>void</type>
                                
                                <parameter name="thrd">
                                        <paramtype><classname>thread</classname>*</paramtype>
                                </parameter>
                                
                                <effects>Adds <code>thrd</code> to the 
                                <classname>thread_group</classname> object's list of managed 
                                <classname>thread</classname> objects. The <code>thrd</code> 
                                object must have been allocated via <code>operator new</code> and will 
                                be deleted when the group is destroyed.</effects>
                        </method>

                        <method name="remove_thread">
                                <type>void</type>
                                
                                <parameter name="thrd">
                                        <paramtype><classname>thread</classname>*</paramtype>
                                </parameter>
                                
                                <effects>Removes <code>thread</code> from <code>*this</code>'s
                                list of managed <classname>thread</classname> objects.</effects>
                                
                                <throws><emphasis role="bold">???</emphasis> if 
                                <code>thrd</code> is not in <code>*this</code>'s list
                                of managed <classname>thread</classname> objects.</throws>
                        </method>

                        <method name="join_all">
                                <type>void</type>
                                
                                <effects>Calls <code>join()</code> on each of the managed 
                                <classname>thread</classname> objects.</effects>
                        </method>
                </method-group>
        </class>
  </namespace>
</header>