+++ /dev/null
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
- "http://www.w3.org/TR/REC-html40/loose.dtd">
-<HTML>
-<HEAD><TITLE>The OMNI Thread Abstraction</TITLE>
-
-<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<META name="GENERATOR" content="hevea 1.06">
-</HEAD>
-<BODY >
-<!--HEVEA command line is: /usr/local/bin/hevea omnithread -->
-<!--HTMLHEAD-->
-<!--ENDHTML-->
-<!--PREFIX <ARG ></ARG>-->
-<!--CUT DEF section 1 -->
-
-
-<H1 ALIGN=center>The OMNI Thread Abstraction</H1>
-
-<H3 ALIGN=center>Tristan Richardson<BR>
-AT&T Laboratories Cambridge<BR>
-</H3>
-
-<H3 ALIGN=center><I>Revised</I> November 2001</H3>
-<!--TOC section Introduction-->
-
-<H2><A NAME="htoc1">1</A> Introduction</H2><!--SEC END -->
-
-The OMNI thread abstraction is designed to provide a common set of
-thread operations for use in programs written in C++. Programs
-written using the abstraction should be much easier to port between
-different architectures with different underlying threads primitives.<BR>
-<BR>
-The programming interface is designed to be similar to the C language
-interface to POSIX threads (IEEE draft standard 1003.1c --- previously
-1003.4a, often known as ``pthreads'' [<A HREF="#pthreads"><CITE>POSIX94</CITE></A>]).<BR>
-<BR>
-Much of the abstraction consists of simple C++ object wrappers around
-pthread calls. However for some features such as thread-specific
-data, a better interface can be offered because of the use of C++.<BR>
-<BR>
-Some of the more complex features of pthreads are not supported
-because of the difficulty of ensuring the same features can be offered
-on top of other thread systems. Such features include thread
-cancellation and complex scheduling control (though simple thread
-priorities are supported).<BR>
-<BR>
-The abstraction layer is currently implemented for the following
-architectures / thread systems:
-<UL><LI>Solaris 2.x using pthreads draft 10
-<LI>Solaris 2.x using solaris threads (but pthreads version is now standard)
-<LI>Alpha OSF1 using pthreads draft 4
-<LI>Windows NT using NT threads
-<LI>Linux 2.x using Linuxthread 0.5 (which is based on pthreads draft 10)
-<LI>Linux 2.x using MIT pthreads (which is based on draft 8)
-<LI>ATMos using pthreads draft 6 (but not Virata ATMos)</UL>
-See the <TT>omnithread.h</TT> header file for full details of the API.
-The descriptions below assume you have some previous knowledge of
-threads, mutexes, condition variables and semaphores. Also refer to
-other documentation ([<A HREF="#birrell"><CITE>Birrell89</CITE></A>], [<A HREF="#pthreads"><CITE>POSIX94</CITE></A>]) for further
-explanation of these ideas (particularly condition variables, the use
-of which may not be particularly intuitive when first encountered).<BR>
-<BR>
-<!--TOC section Synchronisation objects-->
-
-<H2><A NAME="htoc2">2</A> Synchronisation objects</H2><!--SEC END -->
-
-Synchronisation objects are used to synchronise threads within the
-same process. There is no inter-process synchronisation provided.
-The synchronisation objects provided are mutexes, condition variables
-and counting semaphores.<BR>
-<BR>
-<!--TOC subsection Mutex-->
-
-<H3><A NAME="htoc3">2.1</A> Mutex</H3><!--SEC END -->
-
-An object of type <TT>omni_mutex</TT> is used for mutual exclusion.
-It provides two operations, <TT>lock()</TT> and <TT>unlock()</TT>.
-The alternative names <TT>acquire()</TT> and <TT>release()</TT> can be
-used if preferred. Behaviour is undefined when a thread attempts to
-lock the same mutex again or when a mutex is locked by one thread and
-unlocked by a different thread.<BR>
-<BR>
-<!--TOC subsection Condition Variable-->
-
-<H3><A NAME="htoc4">2.2</A> Condition Variable</H3><!--SEC END -->
-
-A condition variable is represented by an <TT>omni_condition</TT> and
-is used for signalling between threads. A call to <TT>wait()</TT>
-causes a thread to wait on the condition variable. A call to
-<TT>signal()</TT> wakes up at least one thread if any are waiting. A
-call to <TT>broadcast()</TT> wakes up all threads waiting on the
-condition variable.<BR>
-<BR>
-When constructed, a pointer to an <TT>omni_mutex</TT> must be given.
-A condition variable <TT>wait()</TT> has an implicit mutex
-<TT>unlock()</TT> and <TT>lock()</TT> around it. The link between
-condition variable and mutex lasts for the lifetime of the condition
-variable (unlike pthreads where the link is only for the duration of
-the wait). The same mutex may be used with several condition
-variables.<BR>
-<BR>
-A wait with a timeout can be achieved by calling
-<TT>timed_wait()</TT>. This is given an absolute time to wait until.
-The routine <TT>omni_thread::get_time()</TT> can be used to turn a
-relative time into an absolute time. <TT>timed_wait()</TT> returns
-<TT>true</TT> if the condition was signalled, <TT>false</TT> if the
-time expired before the condition variable was signalled.<BR>
-<BR>
-<!--TOC subsection Counting semaphores-->
-
-<H3><A NAME="htoc5">2.3</A> Counting semaphores</H3><!--SEC END -->
-
-An <TT>omni_semaphore</TT> is a counting semaphore. When created it
-is given an initial unsigned integer value. When <TT>wait()</TT> is
-called, the value is decremented if non-zero. If the value is zero
-then the thread blocks instead. When <TT>post()</TT> is called, if
-any threads are blocked in <TT>wait()</TT>, exactly one thread is
-woken. If no threads were blocked then the value of the semaphore is
-incremented.<BR>
-<BR>
-If a thread calls <TT>try_wait()</TT>, then the thread won't block if
-the semaphore's value is 0, returning <TT>false</TT> instead.<BR>
-<BR>
-There is no way of querying the value of the semaphore.<BR>
-<BR>
-<!--TOC section Thread object-->
-
-<H2><A NAME="htoc6">3</A> Thread object</H2><!--SEC END -->
-
-A thread is represented by an <TT>omni_thread</TT> object. There are
-broadly two different ways in which it can be used.<BR>
-<BR>
-The first way is simply to create an <TT>omni_thread</TT> object,
-giving a particular function which the thread should execute. This is
-like the POSIX (or any other) C language interface.<BR>
-<BR>
-The second method of use is to create a new class which inherits from
-<TT>omni_thread</TT>. In this case the thread will execute the
-<TT>run()</TT> member function of the new class. One advantage of
-this scheme is that thread-specific data can be implemented simply by
-having data members of the new class.<BR>
-<BR>
-When constructed a thread is in the "new" state and has not actually
-started. A call to <TT>start()</TT> causes the thread to begin
-executing. A static member function <TT>create()</TT> is provided to
-construct and start a thread in a single call. A thread exits by
-calling <TT>exit()</TT> or by returning from the thread function.<BR>
-<BR>
-Threads can be either detached or undetached. Detached threads are
-threads for which all state will be lost upon exit. Other threads
-cannot determine when a detached thread will disappear, and therefore
-should not attempt to access the thread object unless some explicit
-synchronisation with the detached thread guarantees that it still
-exists.<BR>
-<BR>
-Undetached threads are threads for which storage is not reclaimed
-until another thread waits for its termination by calling
-<TT>join()</TT>. An exit value can be passed from an undetached
-thread to the thread which joins it.<BR>
-<BR>
-Detached / undetached threads are distinguished on creation by the
-type of function they execute. Undetached threads execute a function
-which has a <TT>void*</TT> return type, whereas detached threads
-execute a function which has a <TT>void</TT> return type.
-Unfortunately C++ member functions are not allowed to be distinguished
-simply by their return type. Thus in the case of a derived class of
-<TT>omni_thread</TT> which needs an undetached thread, the member
-function executed by the thread is called <TT>run_undetached()</TT>
-rather than <TT>run()</TT>, and it is started by calling
-<TT>start_undetached()</TT> instead of <TT>start()</TT>.<BR>
-<BR>
-The abstraction currently supports three priorities of thread, but no
-guarantee is made of how this will affect underlying thread
-scheduling. The three priorities are <TT>PRIORITY_LOW</TT>,
-<TT>PRIORITY_NORMAL</TT> and <TT>PRIORITY_HIGH</TT>. By default all
-threads run at <TT>PRIORITY_NORMAL</TT>. A different priority can be
-specified on thread creation, or while the thread is running using
-<TT>set_priority().</TT> A thread's current priority is returned by
-<TT>priority()</TT>.<BR>
-<BR>
-Other functions provided are <TT>self()</TT> which returns the calling
-thread's <TT>omni_thread</TT> object, <TT>yield()</TT> which
-requests that other threads be allowed to run, <TT>id()</TT> which
-returns an integer id for the thread for use in debugging,
-<TT>state()</TT>, <TT>sleep()</TT> and <TT>get_time()</TT>.<BR>
-<BR>
-<!--TOC section Per-thread data-->
-
-<H2><A NAME="htoc7">4</A> Per-thread data</H2><!--SEC END -->
-
-omnithread supports per-thread data, via member functions of the
-<TT>omni_thread</TT> object.<BR>
-<BR>
-First, you must allocate a key for with the
-<TT>omni_thread::allocate_key()</TT> function. Then, any object
-whose class is derived from <TT>omni_thread::value_t</TT> can be
-stored using the <TT>set_value()</TT> function. Values are retrieved
-or removed with <TT>get_value()</TT> and <TT>remove_value()</TT>
-respectively.<BR>
-<BR>
-When the thread exits, all per-thread data is deleted (hence the base
-class with virtual destructor).<BR>
-<BR>
-Note that the per-thread data functions are <B>not</B> thread safe,
-so although you can access one thread's storage from another thread,
-there is no concurrency control. Unless you really know what you are
-doing, it is best to only access per-thread data from the thread it is
-attached to.<BR>
-<BR>
-<!--TOC section Using OMNI threads in your program-->
-
-<H2><A NAME="htoc8">5</A> Using OMNI threads in your program</H2><!--SEC END -->
-
-Obviously you need to include the <TT>omnithread.h</TT> header file in
-your source code, and link in the omnithread library with your
-executable. Because there is a single <TT>omnithread.h</TT> for all
-platforms, certain preprocessor defines must be given as compiler
-options. The easiest way to do this is to study the makefiles given
-in the examples provided with this distribution. If you are to
-include OMNI threads in your own development environment, these are
-the necessary preprocessor defines:<BR>
-<TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1>
-<TR><TD ALIGN=left NOWRAP>Platform</TD>
-<TD ALIGN=left NOWRAP>Preprocessor Defines</TD>
-</TR>
-<TR><TD ALIGN=left NOWRAP>Sun Solaris 2.x</TD>
-<TD ALIGN=left NOWRAP><CODE>-D__sunos__ -D__sparc__ -D__OSVERSION__=5</CODE></TD>
-</TR>
-<TR><TD ALIGN=left NOWRAP> </TD>
-<TD ALIGN=left NOWRAP><CODE>-DSVR4 -DUsePthread -D_REENTRANT</CODE></TD>
-</TR>
-<TR><TD ALIGN=left NOWRAP>x86 Linux 2.0</TD>
-<TD ALIGN=left NOWRAP><CODE>-D__linux__ -D__i86__ -D__OSVERSION__=2</CODE></TD>
-</TR>
-<TR><TD ALIGN=left NOWRAP>with linuxthreads 0.5</TD>
-<TD ALIGN=left NOWRAP><CODE>-D_REENTRANT</CODE></TD>
-</TR>
-<TR><TD ALIGN=left NOWRAP>Digital Unix 3.2</TD>
-<TD ALIGN=left NOWRAP><CODE>-D__osf1__ -D__alpha__ -D__OSVERSION__=3</CODE></TD>
-</TR>
-<TR><TD ALIGN=left NOWRAP> </TD>
-<TD ALIGN=left NOWRAP><CODE>-D_REENTRANT</CODE></TD>
-</TR>
-<TR><TD ALIGN=left NOWRAP>Windows NT</TD>
-<TD ALIGN=left NOWRAP><CODE>-D__NT__ -MD</CODE></TD>
-</TR></TABLE><BR>
-<!--TOC section Threaded I/O shutdown for Unix-->
-
-<H2><A NAME="htoc9">6</A> Threaded I/O shutdown for Unix</H2><!--SEC END -->
-
-or, how one thread should tell another thread to shut down when it
-might be doing a blocking call on a socket.<BR>
-<BR>
-<B>If you are using omniORB, you don't need to worry about all
-this, since omniORB does it for you.</B> This section is only relevant
-if you are using omnithread in your own socket-based programming. It
-is also seriously out of date.<BR>
-<BR>
-Unfortunately there doesn't seem to be a standard way of doing this
-which works across all Unix systems. I have investigated the
-behaviour of Solaris 2.5 and Digital Unix 3.2. On Digital Unix
-everything is fine, as the obvious method using shutdown() seems to
-work OK. Unfortunately on Solaris shutdown can only be used on a
-connected socket, so we need devious means to get around this
-limitation. The details are summarised below:<BR>
-<BR>
-<!--TOC subsection read()-->
-
-<H3><A NAME="htoc10">6.1</A> read()</H3><!--SEC END -->
-
-Thread A is in a loop, doing <CODE>read(sock)</CODE>, processing the data,
-then going back into the read.<BR>
-<BR>
-Thread B comes along and wants to shut it down --- it can't cancel
-thread A since (i) working out how to clean up according to where A is
-in its loop is a nightmare, and (ii) this isn't available in
-omnithread anyway.<BR>
-<BR>
-On Solaris 2.5 and Digital Unix 3.2 the following strategy works:<BR>
-<BR>
-Thread B does <CODE>shutdown(sock,2)</CODE>.<BR>
-<BR>
-At this point thread A is either blocked inside <CODE>read(sock)</CODE>, or
-is elsewhere in the loop. If the former then read will return 0,
-indicating that the socket is closed. If the latter then eventually
-thread A will call <CODE>read(sock)</CODE> and then this will return 0.
-Thread A should <CODE>close(sock)</CODE>, do any other tidying up, and exit.<BR>
-<BR>
-If there is another point in the loop that thread A can block then
-obviously thread B needs to be aware of this and be able to wake it up
-in the appropriate way from that point.<BR>
-<BR>
-<!--TOC subsection accept()-->
-
-<H3><A NAME="htoc11">6.2</A> accept()</H3><!--SEC END -->
-
-Again thread A is in a loop, this time doing an accept on listenSock,
-dealing with a new connection and going back into accept. Thread B
-wants to cancel it.<BR>
-<BR>
-On Digital Unix 3.2 the strategy is identical to that for read:<BR>
-<BR>
-Thread B does <CODE>shutdown(listenSock,2)</CODE>. Wherever thread A is in
-the loop, eventually it will return <CODE>ECONNABORTED</CODE> from the
-accept call. It should <CODE>close(listenSock)</CODE>, tidy up as necessary
-and exit.<BR>
-<BR>
-On Solaris 2.5 thread B can't do <CODE>shutdown(listenSock,2)</CODE> ---
-this returns <CODE>ENOTCONN</CODE>. Instead the following strategy can be
-used:<BR>
-<BR>
-First thread B sets some sort of "shutdown flag" associated with
-listenSock. Then it does <CODE>getsockaddr(listenSock)</CODE> to find out
-which port listenSock is on (or knows already), sets up a socket
-dummySock, does <CODE>connect(dummySock,</CODE> <CODE>this host, port)</CODE> and
-finally does <CODE>close(dummySock)</CODE>.<BR>
-<BR>
-Wherever thread A is in the loop, eventually it will call
-<CODE>accept(listenSock)</CODE>. This will return successfully with a new
-socket, say connSock. Thread A then checks to see if the "shutdown
-flag" is set. If not, then it's a normal connection. If it is set,
-then thread A closes listenSock and connSock, tidies up and exits.<BR>
-<BR>
-<!--TOC subsection write()-->
-
-<H3><A NAME="htoc12">6.3</A> write()</H3><!--SEC END -->
-
-Thread A may be blocked in write, or about to go in to a
-potentially-blocking write. Thread B wants to shut it down.<BR>
-<BR>
-On Solaris 2.5:<BR>
-<BR>
-Thread B does <CODE>shutdown(sock,2)</CODE>.<BR>
-<BR>
-If thread A is already in <CODE>write(sock)</CODE> then it will return with
-<CODE>ENXIO</CODE>. If thread A calls write after thread B calls shutdown
-this will return <CODE>EIO</CODE>.<BR>
-<BR>
-On Digital Unix 3.2:<BR>
-<BR>
-Thread B does <CODE>shutdown(sock,2)</CODE>.<BR>
-<BR>
-If thread A is already in <CODE>write(sock)</CODE> then it will return the
-number of bytes written before it became blocked. A subsequent call
-to write will then generate <CODE>SIGPIPE</CODE> (or <CODE>EPIPE</CODE> will be
-returned if <CODE>SIGPIPE</CODE> is ignored by the thread).<BR>
-<BR>
-<!--TOC subsection connect()-->
-
-<H3><A NAME="htoc13">6.4</A> connect()</H3><!--SEC END -->
-
-Thread A may be blocked in connect, or about to go in to a
-potentially-blocking connect. Thread B wants to shut it down.<BR>
-<BR>
-On Digital Unix 3.2:<BR>
-<BR>
-Thread B does <CODE>shutdown(sock,2)</CODE>.<BR>
-<BR>
-If thread A is already in <CODE>connect(sock)</CODE> then it will return a
-successful connection. Subsequent reading or writing will show that
-the socket has been shut down (i.e. read returns 0, write generates
-<CODE>SIGPIPE</CODE> or returns <CODE>EPIPE</CODE>). If thread A calls connect
-after thread B calls shutdown this will return <CODE>EINVAL</CODE>.<BR>
-<BR>
-On Solaris 2.5:<BR>
-<BR>
-There is no way to wake up a thread which is blocked in connect.
-Instead Solaris forces us through a ridiculous procedure whichever way
-we try it. One way is this:<BR>
-<BR>
-First thread A creates a pipe in addition to the socket. Instead of
-shutting down the socket, thread B simply writes a byte to the pipe.<BR>
-<BR>
-Thread A meanwhile sets the socket to non-blocking mode using
-<CODE>fcntl(sock,</CODE> <CODE>F_SETFL, O_NONBLOCK)</CODE>. Then it calls connect
-on the socket --- this will return <CODE>EINPROGRESS</CODE>. Then it must
-call <CODE>select()</CODE>, waiting for either sock to become writable or
-for the pipe to become readable. If select returns that just sock is
-writable then the connection has succeeded. It then needs to set the
-socket back to blocking mode using <CODE>fcntl(sock, F_SETFL, 0)</CODE>. If
-instead select returns that the pipe is readable, thread A closes the
-socket, tidies up and exits.<BR>
-<BR>
-An alternative method is similar but to use polling instead of the
-pipe. Thread B justs sets a flag and thread A calls select with a
-timeout, periodically waking up to see if the flag has been set.<BR>
-<BR>
-<!--TOC section References-->
-
-<H2>References</H2><!--SEC END -->
-<DL COMPACT=compact><DT><A NAME="pthreads"><FONT COLOR=purple>[POSIX94]</FONT></A><DD>
-<EM>Portable Operating System Interface (POSIX) Threads Extension</EM>,
-P1003.1c Draft 10,
-IEEE,
-September 1994.<BR>
-<BR>
-<DT><A NAME="birrell"><FONT COLOR=purple>[Birrell89]</FONT></A><DD>
-<EM>An Introduction to Programming with Threads</EM>,
-Research Report 35,
-DEC Systems Research Center,
-Palo Alto, CA,
-January 1989.</DL>
-<!--HTMLFOOT-->
-<!--ENDHTML-->
-<!--FOOTER-->
-<HR SIZE=2>
-<BLOCKQUOTE><EM>This document was translated from L<sup>A</sup>T<sub>E</sub>X by
-</EM><A HREF="http://pauillac.inria.fr/~maranget/hevea/index.html"><EM>H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A</EM></A><EM>.
-</EM></BLOCKQUOTE>
-</BODY>
-</HTML>
projects / debian / gnuradio / blobdiff