cpp
/
EAThread
mirror of https://github.com/electronicarts/EAThread.git


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364
							<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head>
<style type="text/css">
<!--
.style1 {font-family: "Courier New", Courier, mono}
-->
</style>
</head>
<body>
<h1>User Guide</h1>
<h3>Introduction</h3>
<p>This document provides a brief description of the EAThread modules and
    then provides some basic information on using these modules. You will
    want to consult documentation for individual modules for more detailed
information about them. </p>
<p>All code is in C++ and largely follows the EA coding guidelines as of
    January of 2004. All classes are in the EA::Thread C++ namespace.
    Thus, the fully qualified name of the Mutex class is
    EA::Thread::Mutex. Most of the code is plain C++ and
    doesn't attempt to be very academic with the language. Thus RTTI is not
    used, template usage is used only in one module (FixedAllocator),
    exception handling is not used, etc. Unit tests have been set up for
    most of the functionality and are available with the full package. The
    headers are heavily commented in Doxygen-savvy format and the source
code for the primary modules has been heavily commented as well. </p>
<h3>EAThread Modules<span style="font-weight: bold;"></span>
</h3>
<div style="margin-left: 40px;">
  <table style="text-align: left; width: 100%;" border="1" cellpadding="2" cellspacing="2">
    <tbody> 
    <tr>
      <td style="vertical-align: top;" valign="top"><span style="font-weight: bold;">Module</span><br>
      </td>
      <td style="vertical-align: top;" valign="top"><span style="font-weight: bold;">Description</span></td>
      <td style="vertical-align: top;" valign="top"><span style="font-weight: bold;">Source</span><br>
      </td>
      <td style="vertical-align: top;" valign="top"><span style="font-weight: bold;">Dependencies</span><br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;" valign="top">Thread<br>
      </td>
      <td style="vertical-align: top;" valign="top"> Implements the creation and 
        control of individual threads. <br>
</td>
      <td style="vertical-align: top;" valign="top">eathread.h/cpp<br>
eathread_thread.h/cpp<br>
</td>
      <td style="vertical-align: top;" valign="top">EABase</td>
    </tr>
    <tr>
      <td style="vertical-align: top;" valign="top">Storage<br>
      </td>
      <td style="vertical-align: top;" valign="top">Implements thread-specific 
        storage (a.k.a. thread-local storage). This is a mechanism whereby a given 
        named global variable exists not once globally but exists once per thread. 
        Each thread gets its own view of the variable. <br>
      </td>
      <td style="vertical-align: top;" valign="top">eathread_storage.h/cpp<br>
      </td>
      <td style="vertical-align: top;" valign="top">EABase<br>
        eathead.h/cpp<br>
        eathread_mutex.h/cpp*<br>
      <br>
      </td>
    </tr>
<tr>
      <td style="vertical-align: top;" valign="top">Atomic</td>
      <td style="vertical-align: top;" valign="top">Implements atomic operations 
        on integers and pointers. These are useful for doing thread-safe basic 
        operations and tests on integers or pointers without the cost of more 
        expensive synchronization primitives such as mutexes.<br>
</td>
      <td style="vertical-align: top;" valign="top">eathread_atomic.h<br>
</td>
      <td style="vertical-align: top;" valign="top">EABase</td>
    </tr>
    <tr>
      <td style="vertical-align: top;" valign="top">Mutex<br>
</td>
      <td style="vertical-align: top;" valign="top">Implements traditional mutual 
        exclusion. Mutexes here encompass critical section functionality (a.k.a. 
        futex) and traditional cross-process exclusion.<br>
</td>
      <td style="vertical-align: top;" valign="top">eathread_mutex.h/cpp<br>
</td>
      <td style="vertical-align: top;" valign="top">EABase<br>
eathread.h/cpp<br>
</td>
    </tr>
    <tr>
      <td style="vertical-align: top;" valign="top">Futex</td>
      <td style="vertical-align: top;" valign="top">Implements a fast mutex. A fast mutex is a mutex which can be faster because it acts entirely within user space within the current process and can possibly have some of its code inlined. </td>
      <td style="vertical-align: top;" valign="top">eathread_futex.h/cpp</td>
      <td style="vertical-align: top;" valign="top">EABase<br>
eathread.h/cpp</td>
    </tr>
    <tr>
      <td style="vertical-align: top;" valign="top">ReadWriteMutex<br>
</td>
      <td style="vertical-align: top;" valign="top">Implements a mutex that allows 
        multiple concurrent reading threads but only one writing thread. This 
        is useful for situations where one thread is updating a state but multiple 
        threads may be reading that state.<br>
</td>
      <td style="vertical-align: top;" valign="top">eathread_rwmutex.h/cpp<br>
</td>
      <td style="vertical-align: top;" valign="top"><font size="-2"></font>EABase<br>
        eathread.h/cpp<br>
        eathread_atomic.h<br>
        eathread_condition.h/cpp </td>
    </tr>
    <tr>
      <td style="vertical-align: top;" valign="top">Semaphore<br>
</td>
      <td style="vertical-align: top;" valign="top">Implements a traditional sempahore. 
        A semaphore has zero or positive count associated with it; a thread can 
        'grab' the semaphore if the count is greater than zero and grabbing it 
        reduces its count by one. When the count is zero, threads must wait until 
        it is incremented, which can be done arbitrarily. The semaphore is the 
        primitive upon which all other high level primitives can be constructed.<br>
</td>
      <td style="vertical-align: top;" valign="top">eathread_semaphore.h/cpp<br>
</td>
      <td style="vertical-align: top;" valign="top">EABase<br>
        eathread.h/cpp<br>
        eathread_atomic.h<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;" valign="top">Condition<br>
</td>
      <td style="vertical-align: top;" valign="top">Implements a condition variable, 
        which is a synchronization primitive that supports the producer/consumer 
        pattern. It is for all practical purposes also known as a "monitor" in 
        Java and C#. This primitive is particularly useful for implementing efficient 
        cross thread-messaging systems or worker thread job implementations.<br>
</td>
      <td style="vertical-align: top;" valign="top">eathread_condition.h/cpp<br>
</td>
      <td style="vertical-align: top;" valign="top">EABase<br>
        eathread.h/cpp<br>
        eathread_atomic.h<br>
        eathread_mutex.h/cpp eathread_semaphore.h/cpp<br>
</td>
    </tr>
    <tr>
      <td style="vertical-align: top;" valign="top">Barrier<br>
      </td>
      <td style="vertical-align: top;" valign="top">Implements a cyclic barrier 
        primitive. A barrier is a primitive which coordinates the completion of 
        work by a predetermined number of threads. A barrier has an integer max 
        "height" and a current height associated with it. When a thread hits the 
        barrier, it blocks until the prescribed number of threads hit the barrier, 
        then all are freed.<br>
      </td>
      <td style="vertical-align: top;" valign="top">eathread_barrier.h/cpp<br>
      </td>
      <td style="vertical-align: top;" valign="top"> 
        <p>EABase<br>
          eathread.h/cpp<br>
          eathread_atomic.h<br>
          eathread_semaphore.h/cpp<br>
        </p>
        </td>
    </tr>
<tr>
      <td style="vertical-align: top;" valign="top">SpinLock<br>
</td>
      <td style="vertical-align: top;" valign="top">Implements a traditional spin 
        lock. A spin lock is a special kind of mutex that "spins" in a loop waiting 
        to be able to continue instead of blocking like a mutex. A spinlock is 
        more efficient than a mutex but it generally doesn't work unless operating 
        on a true multi-processing system. When it does work on a true multi-processing 
        system it is inefficient.<br>
</td>
      <td style="vertical-align: top;" valign="top">eathread_spinlock.h<br>
</td>
      <td style="vertical-align: top;" valign="top">EABase<br>
        eathread.h/cpp<br>
        eathread_sync.h <br>
        eathread_atomic.h<br>
</td>
    </tr>
    <tr>
      <td style="vertical-align: top;" valign="top">ReadWriteSpinLock<br>
</td>
      <td style="vertical-align: top;" valign="top">Implements a spinlock that 
        allows multiple readers but only a single writer. Otherwise it is similar 
        to a basic spin lock with respect to purpose and applicability. <br>
</td>
      <td style="vertical-align: top;" valign="top">eathread_rwspinlock.h<br>
</td>
      <td style="vertical-align: top;" valign="top">EABase<br>
        eathread.h/cpp<br>
        eathread_sync.h <br>
        eathread_atomic.h<br>
      </td>
    </tr><tr>
      <td style="vertical-align: top;" valign="top">ThreadPool<br>
</td>
      <td style="vertical-align: top;" valign="top">Implements a "pool" of worker 
        threads available for work. These are commonly used by server systems 
        to spawn off client-server tasks.<br>
</td>
      <td style="vertical-align: top;" valign="top">eathread_pool.h/cpp<br>
</td>
      <td style="vertical-align: top;" valign="top">EABase<br>
        eathread.h/cpp<br>
        eathread_thread.h/cpp<br>
        eathread_condition.h/cpp<br>
        eathread_atomic.h<br>
        eathread_list.h</td>
    </tr><tr>
      <td style="vertical-align: top;" valign="top">Sync<br>
</td>
      <td style="vertical-align: top;" valign="top">Implements memory synchronization 
        primitives known as "fences" or "barriers" (not to be confused with thread 
        barrier primitives). These primitives are useful on multiprocessing platforms 
        for synchronizing the various processors' view of memory, which can become 
        "unsynchronized" in the presence of per-processor caches. <br>
</td>
      <td style="vertical-align: top;" valign="top">eathread_sync.h<br>
</td>
      <td style="vertical-align: top;" valign="top">EABase</td>
    </tr><tr>
      <td style="vertical-align: top;" valign="top">shared_ptr_mt<br>
shared_array_mt<br>
      </td>
      <td style="vertical-align: top;" valign="top">These are multithread-safe 
        equivalents to regular smart pointers such as shared_ptr and shared_array. 
        See the TL (Template Library) for implementations of the regular versions 
        of these smart pointers.<br>
      </td>
      <td style="vertical-align: top;" valign="top">shared_ptr_mt.h<br>

shared_array_mt.h</td>
      <td style="vertical-align: top;" valign="top"> 
        <p>eathread_atomic.h<br>
          eathread_mutex.h <br>
        </p>
        </td>
    </tr>


  </tbody>
</table>
  <p>* May not be required, depending on your platform/configuration.<br>
  </p>
</div>


<h3><span style="font-weight: bold;"></span>  Examples</h3>
<p>We present some
  very basic examples of how to use some of the EAThread modules. These
  exemplify the simplest uses of these modules and don't go into more
  advanced or complicated uses. There is more functionality in each of
  the classes than shown; see the documentation or header files for more
  information. For clarity, the examples assume that the code has
  specified the <span style="font-family: monospace;">using EA::Thread;</span> namespace statement.<br>
  <br>
How to create a thread.</p>
<blockquote>
  <p class="style1">#include "eathread/eathread_thread.h"<br>
    <br>
  int ThreadFunction(void* pContext){<br>
&nbsp;&nbsp; return 0;<br>
  }<br>
  <br>
  Thread thread;<br>
  thread.Begin(ThreadFunction);</p>
</blockquote>
<p>How to use thread-local storage.</p>
<blockquote>
  <p class="style1">#include "eathread/eathread_storage.h"<br>
    <br>
    ThreadLocalStorage tls;<br>
    tls.SetValue("hello");<br>
    const char* pString = (const char*)tls.GetValue();</p>
</blockquote>
<p>How to create and use an atomic integer.</p>
<blockquote>
  <p class="style1">#include "eathread/eathread_atomic.h"<br>
    <br>
    AtomicInteger i = 5;<br>
    i += 7;<br>
    --i;<br>
    if(i.SetValueConditional(3, 6))<br>
&nbsp;&nbsp; printf("i was 6 and now is 3.");</p>
</blockquote>
<p>How to create and use a mutex.</p>
<blockquote>
  <p class="style1">#include "eathread/eathread_mutex.h"<br>
    <br>
    Mutex mutex(NULL, true);<br>
    mutex.Lock();<br>
    mutex.Unlock();</p>
</blockquote>
<p>How to create and use a futex.</p>
<blockquote>
  <p class="style1">#include "eathread/eathread_futex.h"<br>
      <br>
    Futex futex;<br>
    futex.Lock();<br>
    futex.Unlock();</p>
</blockquote>
<p>How to create and use a semaphore.</p>
<blockquote>
  <p class="style1">#include "eathread/eathread_semaphore.h"<br>
    <br>
    Semaphore semaphore(NULL, true);<br>
    semaphore.Post();<br>
    semaphore.Wait();</p>
</blockquote>
<p>How to create and use a condition variable.</p>
<blockquote>
  <p class="style1">#include "eathread/eathread_condition.h"<br>
    <br>
    Condition condition(NULL, true);<br>
    Mutex&nbsp;&nbsp;&nbsp;&nbsp; mutex(NULL, true);<br>
    condition.Signal();<br>
    condition.Wait(&amp;mutex);</p>
</blockquote>
<p>How to create and use a spin lock.</p>
<blockquote>
  <p class="style1">#include "eathread/eathread_spinlock.h"<br>
    <br>
    SpinLock spinLock;<br>
    spinLock.Lock();<br>
  spinLock.Unlock();</p>
</blockquote>
<p>How to create and use a shared_ptr_mt.</p>
<blockquote>
  <p><span class="style1">#include "eathread/shared_ptr_mt.h"<br>
    <br>
    shared_ptr_mt pObject(new SomeClass);<br>
    pObject-&gt;DoSomething();</span></p>
</blockquote>
<hr style="width: 100%; height: 2px;">End of document<br>


<br>


<br>

<br>

<br>

<br>

<br>

<br>

<br>
<br>
<br>
<br>
</body>
</html>