jeanlemotan
365 lines
14 KiB
HTML
365 lines
14 KiB
HTML
<!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>
|
|
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>
|
|
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 mutex(NULL, true);<br>
|
|
condition.Signal();<br>
|
|
condition.Wait(&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->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>
|