diff options
Diffstat (limited to 'docs/doxygen/other')
| -rw-r--r-- | docs/doxygen/other/Makefile.am | 32 | ||||
| -rwxr-xr-x | docs/doxygen/other/doxypy.py | 414 | ||||
| -rw-r--r-- | docs/doxygen/other/group_defs.dox | 95 | ||||
| -rw-r--r-- | docs/doxygen/other/main_page.dox | 5 | ||||
| -rw-r--r-- | docs/doxygen/other/omnithread.html | 411 | ||||
| -rw-r--r-- | docs/doxygen/other/omnithread.pdf | bin | 0 -> 126474 bytes | |||
| -rw-r--r-- | docs/doxygen/other/omnithread.ps | 730 | ||||
| -rwxr-xr-x | docs/doxygen/other/shared_ptr_docstub.h | 24 | ||||
| -rw-r--r-- | docs/doxygen/other/tv-channel-frequencies | 79 | ||||
| -rw-r--r-- | docs/doxygen/other/vector_docstub.h | 16 |
10 files changed, 1806 insertions, 0 deletions
diff --git a/docs/doxygen/other/Makefile.am b/docs/doxygen/other/Makefile.am new file mode 100644 index 000000000..5e05d5d36 --- /dev/null +++ b/docs/doxygen/other/Makefile.am @@ -0,0 +1,32 @@ +# +# Copyright 2001,2004 Free Software Foundation, Inc. +# +# This file is part of GNU Radio +# +# GNU Radio is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3, or (at your option) +# any later version. +# +# GNU Radio is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with GNU Radio; see the file COPYING. If not, write to +# the Free Software Foundation, Inc., 51 Franklin Street, +# Boston, MA 02110-1301, USA. +# + +include $(top_srcdir)/Makefile.common + +EXTRA_DIST = \ + doxypy.py \ + group_defs.dox \ + omnithread.html \ + omnithread.pdf \ + omnithread.ps \ + shared_ptr_docstub.h \ + tv-channel-frequencies \ + vector_docstub.h diff --git a/docs/doxygen/other/doxypy.py b/docs/doxygen/other/doxypy.py new file mode 100755 index 000000000..82fdb6bea --- /dev/null +++ b/docs/doxygen/other/doxypy.py @@ -0,0 +1,414 @@ +#!/usr/bin/env python + +__applicationName__ = "doxypy" +__blurb__ = """ +doxypy is an input filter for Doxygen. It preprocesses python +files so that docstrings of classes and functions are reformatted +into Doxygen-conform documentation blocks. +""" + +__doc__ = __blurb__ + \ +""" +In order to make Doxygen preprocess files through doxypy, simply +add the following lines to your Doxyfile: + FILTER_SOURCE_FILES = YES + INPUT_FILTER = "python /path/to/doxypy.py" +""" + +__version__ = "0.4.1" +__date__ = "5th December 2008" +__website__ = "http://code.foosel.org/doxypy" + +__author__ = ( + "Philippe 'demod' Neumann (doxypy at demod dot org)", + "Gina 'foosel' Haeussge (gina at foosel dot net)" +) + +__licenseName__ = "GPL v2" +__license__ = """This program is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation, either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see <http://www.gnu.org/licenses/>. +""" + +import sys +import re + +from optparse import OptionParser, OptionGroup + +class FSM(object): + """Implements a finite state machine. + + Transitions are given as 4-tuples, consisting of an origin state, a target + state, a condition for the transition (given as a reference to a function + which gets called with a given piece of input) and a pointer to a function + to be called upon the execution of the given transition. + """ + + """ + @var transitions holds the transitions + @var current_state holds the current state + @var current_input holds the current input + @var current_transition hold the currently active transition + """ + + def __init__(self, start_state=None, transitions=[]): + self.transitions = transitions + self.current_state = start_state + self.current_input = None + self.current_transition = None + + def setStartState(self, state): + self.current_state = state + + def addTransition(self, from_state, to_state, condition, callback): + self.transitions.append([from_state, to_state, condition, callback]) + + def makeTransition(self, input): + """ Makes a transition based on the given input. + + @param input input to parse by the FSM + """ + for transition in self.transitions: + [from_state, to_state, condition, callback] = transition + if from_state == self.current_state: + match = condition(input) + if match: + self.current_state = to_state + self.current_input = input + self.current_transition = transition + if options.debug: + print >>sys.stderr, "# FSM: executing (%s -> %s) for line '%s'" % (from_state, to_state, input) + callback(match) + return + +class Doxypy(object): + def __init__(self): + string_prefixes = "[uU]?[rR]?" + + self.start_single_comment_re = re.compile("^\s*%s(''')" % string_prefixes) + self.end_single_comment_re = re.compile("(''')\s*$") + + self.start_double_comment_re = re.compile("^\s*%s(\"\"\")" % string_prefixes) + self.end_double_comment_re = re.compile("(\"\"\")\s*$") + + self.single_comment_re = re.compile("^\s*%s(''').*(''')\s*$" % string_prefixes) + self.double_comment_re = re.compile("^\s*%s(\"\"\").*(\"\"\")\s*$" % string_prefixes) + + self.defclass_re = re.compile("^(\s*)(def .+:|class .+:)") + self.empty_re = re.compile("^\s*$") + self.hashline_re = re.compile("^\s*#.*$") + self.importline_re = re.compile("^\s*(import |from .+ import)") + + self.multiline_defclass_start_re = re.compile("^(\s*)(def|class)(\s.*)?$") + self.multiline_defclass_end_re = re.compile(":\s*$") + + ## Transition list format + # ["FROM", "TO", condition, action] + transitions = [ + ### FILEHEAD + + # single line comments + ["FILEHEAD", "FILEHEAD", self.single_comment_re.search, self.appendCommentLine], + ["FILEHEAD", "FILEHEAD", self.double_comment_re.search, self.appendCommentLine], + + # multiline comments + ["FILEHEAD", "FILEHEAD_COMMENT_SINGLE", self.start_single_comment_re.search, self.appendCommentLine], + ["FILEHEAD_COMMENT_SINGLE", "FILEHEAD", self.end_single_comment_re.search, self.appendCommentLine], + ["FILEHEAD_COMMENT_SINGLE", "FILEHEAD_COMMENT_SINGLE", self.catchall, self.appendCommentLine], + ["FILEHEAD", "FILEHEAD_COMMENT_DOUBLE", self.start_double_comment_re.search, self.appendCommentLine], + ["FILEHEAD_COMMENT_DOUBLE", "FILEHEAD", self.end_double_comment_re.search, self.appendCommentLine], + ["FILEHEAD_COMMENT_DOUBLE", "FILEHEAD_COMMENT_DOUBLE", self.catchall, self.appendCommentLine], + + # other lines + ["FILEHEAD", "FILEHEAD", self.empty_re.search, self.appendFileheadLine], + ["FILEHEAD", "FILEHEAD", self.hashline_re.search, self.appendFileheadLine], + ["FILEHEAD", "FILEHEAD", self.importline_re.search, self.appendFileheadLine], + ["FILEHEAD", "DEFCLASS", self.defclass_re.search, self.resetCommentSearch], + ["FILEHEAD", "DEFCLASS_MULTI", self.multiline_defclass_start_re.search, self.resetCommentSearch], + ["FILEHEAD", "DEFCLASS_BODY", self.catchall, self.appendFileheadLine], + + ### DEFCLASS + + # single line comments + ["DEFCLASS", "DEFCLASS_BODY", self.single_comment_re.search, self.appendCommentLine], + ["DEFCLASS", "DEFCLASS_BODY", self.double_comment_re.search, self.appendCommentLine], + + # multiline comments + ["DEFCLASS", "COMMENT_SINGLE", self.start_single_comment_re.search, self.appendCommentLine], + ["COMMENT_SINGLE", "DEFCLASS_BODY", self.end_single_comment_re.search, self.appendCommentLine], + ["COMMENT_SINGLE", "COMMENT_SINGLE", self.catchall, self.appendCommentLine], + ["DEFCLASS", "COMMENT_DOUBLE", self.start_double_comment_re.search, self.appendCommentLine], + ["COMMENT_DOUBLE", "DEFCLASS_BODY", self.end_double_comment_re.search, self.appendCommentLine], + ["COMMENT_DOUBLE", "COMMENT_DOUBLE", self.catchall, self.appendCommentLine], + + # other lines + ["DEFCLASS", "DEFCLASS", self.empty_re.search, self.appendDefclassLine], + ["DEFCLASS", "DEFCLASS", self.defclass_re.search, self.resetCommentSearch], + ["DEFCLASS", "DEFCLASS_MULTI", self.multiline_defclass_start_re.search, self.resetCommentSearch], + ["DEFCLASS", "DEFCLASS_BODY", self.catchall, self.stopCommentSearch], + + ### DEFCLASS_BODY + + ["DEFCLASS_BODY", "DEFCLASS", self.defclass_re.search, self.startCommentSearch], + ["DEFCLASS_BODY", "DEFCLASS_MULTI", self.multiline_defclass_start_re.search, self.startCommentSearch], + ["DEFCLASS_BODY", "DEFCLASS_BODY", self.catchall, self.appendNormalLine], + + ### DEFCLASS_MULTI + ["DEFCLASS_MULTI", "DEFCLASS", self.multiline_defclass_end_re.search, self.appendDefclassLine], + ["DEFCLASS_MULTI", "DEFCLASS_MULTI", self.catchall, self.appendDefclassLine], + ] + + self.fsm = FSM("FILEHEAD", transitions) + self.outstream = sys.stdout + + self.output = [] + self.comment = [] + self.filehead = [] + self.defclass = [] + self.indent = "" + + def __closeComment(self): + """Appends any open comment block and triggering block to the output.""" + + if options.autobrief: + if len(self.comment) == 1 \ + or (len(self.comment) > 2 and self.comment[1].strip() == ''): + self.comment[0] = self.__docstringSummaryToBrief(self.comment[0]) + + if self.comment: + block = self.makeCommentBlock() + self.output.extend(block) + + if self.defclass: + self.output.extend(self.defclass) + + def __docstringSummaryToBrief(self, line): + """Adds \\brief to the docstrings summary line. + + A \\brief is prepended, provided no other doxygen command is at the + start of the line. + """ + stripped = line.strip() + if stripped and not stripped[0] in ('@', '\\'): + return "\\brief " + line + else: + return line + + def __flushBuffer(self): + """Flushes the current outputbuffer to the outstream.""" + if self.output: + try: + if options.debug: + print >>sys.stderr, "# OUTPUT: ", self.output + print >>self.outstream, "\n".join(self.output) + self.outstream.flush() + except IOError: + # Fix for FS#33. Catches "broken pipe" when doxygen closes + # stdout prematurely upon usage of INPUT_FILTER, INLINE_SOURCES + # and FILTER_SOURCE_FILES. + pass + self.output = [] + + def catchall(self, input): + """The catchall-condition, always returns true.""" + return True + + def resetCommentSearch(self, match): + """Restarts a new comment search for a different triggering line. + + Closes the current commentblock and starts a new comment search. + """ + if options.debug: + print >>sys.stderr, "# CALLBACK: resetCommentSearch" + self.__closeComment() + self.startCommentSearch(match) + + def startCommentSearch(self, match): + """Starts a new comment search. + + Saves the triggering line, resets the current comment and saves + the current indentation. + """ + if options.debug: + print >>sys.stderr, "# CALLBACK: startCommentSearch" + self.defclass = [self.fsm.current_input] + self.comment = [] + self.indent = match.group(1) + + def stopCommentSearch(self, match): + """Stops a comment search. + + Closes the current commentblock, resets the triggering line and + appends the current line to the output. + """ + if options.debug: + print >>sys.stderr, "# CALLBACK: stopCommentSearch" + self.__closeComment() + + self.defclass = [] + self.output.append(self.fsm.current_input) + + def appendFileheadLine(self, match): + """Appends a line in the FILEHEAD state. + + Closes the open comment block, resets it and appends the current line. + """ + if options.debug: + print >>sys.stderr, "# CALLBACK: appendFileheadLine" + self.__closeComment() + self.comment = [] + self.output.append(self.fsm.current_input) + + def appendCommentLine(self, match): + """Appends a comment line. + + The comment delimiter is removed from multiline start and ends as + well as singleline comments. + """ + if options.debug: + print >>sys.stderr, "# CALLBACK: appendCommentLine" + (from_state, to_state, condition, callback) = self.fsm.current_transition + + # single line comment + if (from_state == "DEFCLASS" and to_state == "DEFCLASS_BODY") \ + or (from_state == "FILEHEAD" and to_state == "FILEHEAD"): + # remove comment delimiter from begin and end of the line + activeCommentDelim = match.group(1) + line = self.fsm.current_input + self.comment.append(line[line.find(activeCommentDelim)+len(activeCommentDelim):line.rfind(activeCommentDelim)]) + + if (to_state == "DEFCLASS_BODY"): + self.__closeComment() + self.defclass = [] + # multiline start + elif from_state == "DEFCLASS" or from_state == "FILEHEAD": + # remove comment delimiter from begin of the line + activeCommentDelim = match.group(1) + line = self.fsm.current_input + self.comment.append(line[line.find(activeCommentDelim)+len(activeCommentDelim):]) + # multiline end + elif to_state == "DEFCLASS_BODY" or to_state == "FILEHEAD": + # remove comment delimiter from end of the line + activeCommentDelim = match.group(1) + line = self.fsm.current_input + self.comment.append(line[0:line.rfind(activeCommentDelim)]) + if (to_state == "DEFCLASS_BODY"): + self.__closeComment() + self.defclass = [] + # in multiline comment + else: + # just append the comment line + self.comment.append(self.fsm.current_input) + + def appendNormalLine(self, match): + """Appends a line to the output.""" + if options.debug: + print >>sys.stderr, "# CALLBACK: appendNormalLine" + self.output.append(self.fsm.current_input) + + def appendDefclassLine(self, match): + """Appends a line to the triggering block.""" + if options.debug: + print >>sys.stderr, "# CALLBACK: appendDefclassLine" + self.defclass.append(self.fsm.current_input) + + def makeCommentBlock(self): + """Indents the current comment block with respect to the current + indentation level. + + @returns a list of indented comment lines + """ + doxyStart = "##" + commentLines = self.comment + + commentLines = map(lambda x: "%s# %s" % (self.indent, x), commentLines) + l = [self.indent + doxyStart] + l.extend(commentLines) + + return l + + def parse(self, input): + """Parses a python file given as input string and returns the doxygen- + compatible representation. + + @param input the python code to parse + @returns the modified python code + """ + lines = input.split("\n") + + for line in lines: + self.fsm.makeTransition(line) + + if self.fsm.current_state == "DEFCLASS": + self.__closeComment() + + return "\n".join(self.output) + + def parseFile(self, filename): + """Parses a python file given as input string and returns the doxygen- + compatible representation. + + @param input the python code to parse + @returns the modified python code + """ + f = open(filename, 'r') + + for line in f: + self.parseLine(line.rstrip('\r\n')) + if self.fsm.current_state == "DEFCLASS": + self.__closeComment() + self.__flushBuffer() + f.close() + + def parseLine(self, line): + """Parse one line of python and flush the resulting output to the + outstream. + + @param line the python code line to parse + """ + self.fsm.makeTransition(line) + self.__flushBuffer() + +def optParse(): + """Parses commandline options.""" + parser = OptionParser(prog=__applicationName__, version="%prog " + __version__) + + parser.set_usage("%prog [options] filename") + parser.add_option("--autobrief", + action="store_true", dest="autobrief", + help="use the docstring summary line as \\brief description" + ) + parser.add_option("--debug", + action="store_true", dest="debug", + help="enable debug output on stderr" + ) + + ## parse options + global options + (options, filename) = parser.parse_args() + + if not filename: + print >>sys.stderr, "No filename given." + sys.exit(-1) + + return filename[0] + +def main(): + """Starts the parser on the file given by the filename as the first + argument on the commandline. + """ + filename = optParse() + fsm = Doxypy() + fsm.parseFile(filename) + +if __name__ == "__main__": + main() diff --git a/docs/doxygen/other/group_defs.dox b/docs/doxygen/other/group_defs.dox new file mode 100644 index 000000000..7373236ce --- /dev/null +++ b/docs/doxygen/other/group_defs.dox @@ -0,0 +1,95 @@ +/*! + * \defgroup block Signal Processing Blocks + * These are the signal processing blocks... + * @{ + */ + +/*! + * \defgroup source Signal Sources + * signal sources docs... + */ + +/*! + * \defgroup sink Signal Sinks + * docs for sinks... + */ + +/*! + * \defgroup filter Filters + */ + +/*! + * \defgroup converter Type Conversions + */ + +/*! + * \defgroup level Signal Level Control + */ + +/*! + * \defgroup clock Signal Clock Synchronization + */ + +/*! + * \defgroup dft Fourier Transformation + */ + +/*! + * \defgroup synch Synchronization + */ + +/*! + * \defgroup packet Packetization + */ + +/*! + * \defgroup logic Logical + */ + +/*! @} */ + +/*! \defgroup filter_design Digital Filter Design */ +/*! \defgroup graphical Graphical Utilities */ +/*! \defgroup encdec Voice Encoders and Decoders */ +/*! \defgroup coding Information Coding and Decoding */ +/*! \defgroup modulation Signal Modulation */ +/*! \defgroup demodulation Signal Demodulation */ +/*! \defgroup flow Samples Flow Control */ + +/*! \defgroup math Mathmatics */ +/*! \defgroup tools Tools */ +/*! \defgroup misc Miscellaneous */ +/*! \defgroup internal Implementation Details */ + +/*! \defgroup base Misc Common Base Classes */ +/*! + * \defgroup applications Applications + * These are some applications build using gnuradio... + * @{ + */ + +/*! + * \defgroup atsc ATSC + * ATSC Applications... + */ + +/*! + * \defgroup radar Radar + * Radar Applications... + */ + +/*! + * \defgroup pager Pager + * Pager Applications + */ + +/*! + * \defgroup sounder Sounder + * Channel Sounder + */ + +/*! @} */ + +/*! \defgroup usrp USRP */ +/*! \defgroup usrp2 USRP2 */ +/*! \defgroup hardware Hardware */ diff --git a/docs/doxygen/other/main_page.dox b/docs/doxygen/other/main_page.dox new file mode 100644 index 000000000..5c37905fa --- /dev/null +++ b/docs/doxygen/other/main_page.dox @@ -0,0 +1,5 @@ +/*! \mainpage + +Welcome to GNU Radio! + +*/ diff --git a/docs/doxygen/other/omnithread.html b/docs/doxygen/other/omnithread.html new file mode 100644 index 000000000..5682d1d0b --- /dev/null +++ b/docs/doxygen/other/omnithread.html @@ -0,0 +1,411 @@ +<!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> diff --git a/docs/doxygen/other/omnithread.pdf b/docs/doxygen/other/omnithread.pdf Binary files differnew file mode 100644 index 000000000..b54218744 --- /dev/null +++ b/docs/doxygen/other/omnithread.pdf diff --git a/docs/doxygen/other/omnithread.ps b/docs/doxygen/other/omnithread.ps new file mode 100644 index 000000000..9e858f0b7 --- /dev/null +++ b/docs/doxygen/other/omnithread.ps @@ -0,0 +1,730 @@ +%!PS-Adobe-2.0 +%%Creator: dvipsk 5.86 p1.5d Copyright 1996-2001 ASCII Corp.(www-ptex@ascii.co.jp) +%%based on dvipsk 5.86 Copyright 1999 Radical Eye Software (www.radicaleye.com) +%%Title: omnithread.dvi +%%Pages: 7 +%%PageOrder: Ascend +%%BoundingBox: 0 0 596 842 +%%DocumentFonts: Palatino-Roman Palatino-Italic Palatino-Bold Courier +%%EndComments +%DVIPSWebPage: (www.radicaleye.com) +%DVIPSCommandLine: dvips omnithread +%DVIPSParameters: dpi=600, compressed +%DVIPSSource: TeX output 2002.08.15:1756 +%%BeginProcSet: texc.pro +%! +/TeXDict 300 dict def TeXDict begin/N{def}def/B{bind def}N/S{exch}N/X{S +N}B/A{dup}B/TR{translate}N/isls false N/vsize 11 72 mul N/hsize 8.5 72 +mul N/landplus90{false}def/@rigin{isls{[0 landplus90{1 -1}{-1 1}ifelse 0 +0 0]concat}if 72 Resolution div 72 VResolution div neg scale isls{ +landplus90{VResolution 72 div vsize mul 0 exch}{Resolution -72 div hsize +mul 0}ifelse TR}if Resolution VResolution vsize -72 div 1 add mul TR[ +matrix currentmatrix{A A round sub abs 0.00001 lt{round}if}forall round +exch round exch]setmatrix}N/@landscape{/isls true N}B/@manualfeed{ +statusdict/manualfeed true put}B/@copies{/#copies X}B/FMat[1 0 0 -1 0 0] +N/FBB[0 0 0 0]N/nn 0 N/IEn 0 N/ctr 0 N/df-tail{/nn 8 dict N nn begin +/FontType 3 N/FontMatrix fntrx N/FontBBox FBB N string/base X array +/BitMaps X/BuildChar{CharBuilder}N/Encoding IEn N end A{/foo setfont}2 +array copy cvx N load 0 nn put/ctr 0 N[}B/sf 0 N/df{/sf 1 N/fntrx FMat N +df-tail}B/dfs{div/sf X/fntrx[sf 0 0 sf neg 0 0]N df-tail}B/E{pop nn A +definefont setfont}B/Cw{Cd A length 5 sub get}B/Ch{Cd A length 4 sub get +}B/Cx{128 Cd A length 3 sub get sub}B/Cy{Cd A length 2 sub get 127 sub} +B/Cdx{Cd A length 1 sub get}B/Ci{Cd A type/stringtype ne{ctr get/ctr ctr +1 add N}if}B/id 0 N/rw 0 N/rc 0 N/gp 0 N/cp 0 N/G 0 N/CharBuilder{save 3 +1 roll S A/base get 2 index get S/BitMaps get S get/Cd X pop/ctr 0 N Cdx +0 Cx Cy Ch sub Cx Cw add Cy setcachedevice Cw Ch true[1 0 0 -1 -.1 Cx +sub Cy .1 sub]/id Ci N/rw Cw 7 add 8 idiv string N/rc 0 N/gp 0 N/cp 0 N{ +rc 0 ne{rc 1 sub/rc X rw}{G}ifelse}imagemask restore}B/G{{id gp get/gp +gp 1 add N A 18 mod S 18 idiv pl S get exec}loop}B/adv{cp add/cp X}B +/chg{rw cp id gp 4 index getinterval putinterval A gp add/gp X adv}B/nd{ +/cp 0 N rw exit}B/lsh{rw cp 2 copy get A 0 eq{pop 1}{A 255 eq{pop 254}{ +A A add 255 and S 1 and or}ifelse}ifelse put 1 adv}B/rsh{rw cp 2 copy +get A 0 eq{pop 128}{A 255 eq{pop 127}{A 2 idiv S 128 and or}ifelse} +ifelse put 1 adv}B/clr{rw cp 2 index string putinterval adv}B/set{rw cp +fillstr 0 4 index getinterval putinterval adv}B/fillstr 18 string 0 1 17 +{2 copy 255 put pop}for N/pl[{adv 1 chg}{adv 1 chg nd}{1 add chg}{1 add +chg nd}{adv lsh}{adv lsh nd}{adv rsh}{adv rsh nd}{1 add adv}{/rc X nd}{ +1 add set}{1 add clr}{adv 2 chg}{adv 2 chg nd}{pop nd}]A{bind pop} +forall N/D{/cc X A type/stringtype ne{]}if nn/base get cc ctr put nn +/BitMaps get S ctr S sf 1 ne{A A length 1 sub A 2 index S get sf div put +}if put/ctr ctr 1 add N}B/I{cc 1 add D}B/bop{userdict/bop-hook known{ +bop-hook}if/SI save N @rigin 0 0 moveto/V matrix currentmatrix A 1 get A +mul exch 0 get A mul add .99 lt{/QV}{/RV}ifelse load def pop pop}N/eop{ +SI restore userdict/eop-hook known{eop-hook}if showpage}N/@start{ +userdict/start-hook known{start-hook}if pop/VResolution X/Resolution X +1000 div/DVImag X/IEn 256 array N 2 string 0 1 255{IEn S A 360 add 36 4 +index cvrs cvn put}for pop 65781.76 div/vsize X 65781.76 div/hsize X}N +/dir 0 def/dyy{/dir 0 def}B/dyt{/dir 1 def}B/dty{/dir 2 def}B/dtt{/dir 3 +def}B/p{dir 2 eq{-90 rotate show 90 rotate}{dir 3 eq{-90 rotate show 90 +rotate}{show}ifelse}ifelse}N/RMat[1 0 0 -1 0 0]N/BDot 260 string N/Rx 0 +N/Ry 0 N/V{}B/RV/v{/Ry X/Rx X V}B statusdict begin/product where{pop +false[(Display)(NeXT)(LaserWriter 16/600)]{A length product length le{A +length product exch 0 exch getinterval eq{pop true exit}if}{pop}ifelse} +forall}{false}ifelse end{{gsave TR -.1 .1 TR 1 1 scale Rx Ry false RMat{ +BDot}imagemask grestore}}{{gsave TR -.1 .1 TR Rx Ry scale 1 1 false RMat +{BDot}imagemask grestore}}ifelse B/QV{gsave newpath transform round exch +round exch itransform moveto Rx 0 rlineto 0 Ry neg rlineto Rx neg 0 +rlineto fill grestore}B/a{moveto}B/delta 0 N/tail{A/delta X 0 rmoveto}B +/M{S p delta add tail}B/b{S p tail}B/c{-4 M}B/d{-3 M}B/e{-2 M}B/f{-1 M} +B/g{0 M}B/h{1 M}B/i{2 M}B/j{3 M}B/k{4 M}B/w{0 rmoveto}B/l{p -4 w}B/m{p +-3 w}B/n{p -2 w}B/o{p -1 w}B/q{p 1 w}B/r{p 2 w}B/s{p 3 w}B/t{p 4 w}B/x{ +0 S rmoveto}B/y{3 2 roll p a}B/bos{/SS save N}B/eos{SS restore}B end + +%%EndProcSet +%%BeginProcSet: 8r.enc +% @@psencodingfile@{ +% author = "S. Rahtz, P. MacKay, Alan Jeffrey, B. Horn, K. Berry", +% version = "0.6", +% date = "1 July 1998", +% filename = "8r.enc", +% email = "tex-fonts@@tug.org", +% docstring = "Encoding for TrueType or Type 1 fonts +% to be used with TeX." +% @} +% +% Idea is to have all the characters normally included in Type 1 fonts +% available for typesetting. This is effectively the characters in Adobe +% Standard Encoding + ISO Latin 1 + extra characters from Lucida. +% +% Character code assignments were made as follows: +% +% (1) the Windows ANSI characters are almost all in their Windows ANSI +% positions, because some Windows users cannot easily reencode the +% fonts, and it makes no difference on other systems. The only Windows +% ANSI characters not available are those that make no sense for +% typesetting -- rubout (127 decimal), nobreakspace (160), softhyphen +% (173). quotesingle and grave are moved just because it's such an +% irritation not having them in TeX positions. +% +% (2) Remaining characters are assigned arbitrarily to the lower part +% of the range, avoiding 0, 10 and 13 in case we meet dumb software. +% +% (3) Y&Y Lucida Bright includes some extra text characters; in the +% hopes that other PostScript fonts, perhaps created for public +% consumption, will include them, they are included starting at 0x12. +% +% (4) Remaining positions left undefined are for use in (hopefully) +% upward-compatible revisions, if someday more characters are generally +% available. +% +% (5) hyphen appears twice for compatibility with both +% ASCII and Windows. +% +/TeXBase1Encoding [ +% 0x00 (encoded characters from Adobe Standard not in Windows 3.1) + /.notdef /dotaccent /fi /fl + /fraction /hungarumlaut /Lslash /lslash + /ogonek /ring /.notdef + /breve /minus /.notdef +% These are the only two remaining unencoded characters, so may as +% well include them. + /Zcaron /zcaron +% 0x10 + /caron /dotlessi +% (unusual TeX characters available in, e.g., Lucida Bright) + /dotlessj /ff /ffi /ffl + /.notdef /.notdef /.notdef /.notdef + /.notdef /.notdef /.notdef /.notdef + % very contentious; it's so painful not having quoteleft and quoteright + % at 96 and 145 that we move the things normally found there to here. + /grave /quotesingle +% 0x20 (ASCII begins) + /space /exclam /quotedbl /numbersign + /dollar /percent /ampersand /quoteright + /parenleft /parenright /asterisk /plus /comma /hyphen /period /slash +% 0x30 + /zero /one /two /three /four /five /six /seven + /eight /nine /colon /semicolon /less /equal /greater /question +% 0x40 + /at /A /B /C /D /E /F /G /H /I /J /K /L /M /N /O +% 0x50 + /P /Q /R /S /T /U /V /W + /X /Y /Z /bracketleft /backslash /bracketright /asciicircum /underscore +% 0x60 + /quoteleft /a /b /c /d /e /f /g /h /i /j /k /l /m /n /o +% 0x70 + /p /q /r /s /t /u /v /w + /x /y /z /braceleft /bar /braceright /asciitilde + /.notdef % rubout; ASCII ends +% 0x80 + /.notdef /.notdef /quotesinglbase /florin + /quotedblbase /ellipsis /dagger /daggerdbl + /circumflex /perthousand /Scaron /guilsinglleft + /OE /.notdef /.notdef /.notdef +% 0x90 + /.notdef /.notdef /.notdef /quotedblleft + /quotedblright /bullet /endash /emdash + /tilde /trademark /scaron /guilsinglright + /oe /.notdef /.notdef /Ydieresis +% 0xA0 + /.notdef % nobreakspace + /exclamdown /cent /sterling + /currency /yen /brokenbar /section + /dieresis /copyright /ordfeminine /guillemotleft + /logicalnot + /hyphen % Y&Y (also at 45); Windows' softhyphen + /registered + /macron +% 0xD0 + /degree /plusminus /twosuperior /threesuperior + /acute /mu /paragraph /periodcentered + /cedilla /onesuperior /ordmasculine /guillemotright + /onequarter /onehalf /threequarters /questiondown +% 0xC0 + /Agrave /Aacute /Acircumflex /Atilde /Adieresis /Aring /AE /Ccedilla + /Egrave /Eacute /Ecircumflex /Edieresis + /Igrave /Iacute /Icircumflex /Idieresis +% 0xD0 + /Eth /Ntilde /Ograve /Oacute + /Ocircumflex /Otilde /Odieresis /multiply + /Oslash /Ugrave /Uacute /Ucircumflex + /Udieresis /Yacute /Thorn /germandbls +% 0xE0 + /agrave /aacute /acircumflex /atilde + /adieresis /aring /ae /ccedilla + /egrave /eacute /ecircumflex /edieresis + /igrave /iacute /icircumflex /idieresis +% 0xF0 + /eth /ntilde /ograve /oacute + /ocircumflex /otilde /odieresis /divide + /oslash /ugrave /uacute /ucircumflex + /udieresis /yacute /thorn /ydieresis +] def + +%%EndProcSet +%%BeginProcSet: texps.pro +%! +TeXDict begin/rf{findfont dup length 1 add dict begin{1 index/FID ne 2 +index/UniqueID ne and{def}{pop pop}ifelse}forall[1 index 0 6 -1 roll +exec 0 exch 5 -1 roll VResolution Resolution div mul neg 0 0]/Metrics +exch def dict begin 0 1 255{exch dup type/integertype ne{pop pop 1 sub +dup 0 le{pop}{[}ifelse}{FontMatrix 0 get div Metrics 0 get div def} +ifelse}for Metrics/Metrics currentdict end def[2 index currentdict end +definefont 3 -1 roll makefont/setfont cvx]cvx def}def/ObliqueSlant{dup +sin S cos div neg}B/SlantFont{4 index mul add}def/ExtendFont{3 -1 roll +mul exch}def/ReEncodeFont{CharStrings rcheck{/Encoding false def dup[ +exch{dup CharStrings exch known not{pop/.notdef/Encoding true def}if} +forall Encoding{]exch pop}{cleartomark}ifelse}if/Encoding exch def}def +end + +%%EndProcSet +TeXDict begin 39158280 55380996 1000 600 600 (omnithread.dvi) +@start /Fa 134[ 45 45 66 1[ 51 30 35 35 1[ 45 40 51 71 +25 2[ 25 45 45 25 35 45 37 42 40 8[ 66 3[ 56 51 2[ 56 +71 5[ 30 3[ 56 3[ 66 23[ 30 30 40[{ TeXBase1Encoding ReEncodeFont} 31 +90.9091 /Palatino-Italic rf /Fb 134[ 51 1[ 76 1[ 56 30 +40 35 2[ 51 56 81 30 2[ 30 56 51 35 45 56 40 56 45 14[ 66 +2[ 76 5[ 35 6[ 61 19[ 23 30 23 4[ 25 39[{ TeXBase1Encoding ReEncodeFont} +27 90.9091 /Palatino-Bold rf /Fc 135[ 50 83 1[ 61 33 +44 39 1[ 61 55 61 89 33 2[ 33 61 55 1[ 50 61 44 61 50 +10[ 78 8[ 100 9[ 72 12[ 50 1[ 50 50 50 50 2[ 25 4[ 33 +33 40[{ TeXBase1Encoding ReEncodeFont} 30 99.6264 /Palatino-Bold +rf /Fd 134[ 55 55 55 55 55 55 55 55 55 55 55 55 55 55 +55 55 55 55 55 55 55 55 55 55 55 1[ 55 5[ 55 55 55 55 +55 55 55 55 1[ 55 55 55 55 55 55 1[ 55 55 55 55 55 55 +55 55 55 3[ 55 2[ 55 1[ 55 1[ 55 55 55 55 55 55 55 1[ 55 +55 55 1[ 55 55 55 40[{ TeXBase1Encoding ReEncodeFont} 65 +90.9091 /Courier rf /Fe 141[ 36 12[ 44 56 2[ 45 7[ 61 +61 91 1[ 71 56 48 61 2[ 71 76 3[ 30 31 76 1[ 51 56 70 +64 56 71 10[ 45 3[ 45 45 1[ 55 23 4[ 30 30 40[{ +.167 SlantFont TeXBase1Encoding ReEncodeFont} 29 90.9091 +/Palatino-Roman rf +%DVIPSBitmapFont: Ff cmsy10 10.95 1 +/Ff 1 16 df<EB0FFCEB3FFF90B512C0000314F04880488048804880A2481580A3B712C0 +AA6C1580A36C1500A26C5C6C5C6C5C6C5CC614C0013F90C7FCEB0FFC22227BA72D> 15 +D E +%EndDVIPSBitmapFont +/Fg 104[ 91 2[ 45 45 24[ 45 51 47 76 51 55 30 39 36 51 +55 50 53 80 26 51 21 26 53 51 30 44 56 40 50 45 3[ 30 +1[ 30 2[ 61 91 66 71 56 48 61 1[ 55 71 76 86 56 66 30 +31 76 1[ 51 56 70 64 56 71 6[ 23 45 45 45 45 45 45 45 +45 45 45 55 23 30 23 55 1[ 30 30 25 4[ 34 30[ 55 55 2[{ +TeXBase1Encoding ReEncodeFont} 75 90.9091 /Palatino-Roman +rf /Fh 134[ 66 60 100 1[ 73 40 53 47 1[ 73 66 73 106 +2[ 40 40 73 66 47 60 73 53 73 60 11[ 93 80 73 86 1[ 73 +100 100 120 3[ 47 18[ 60 60 60 60 60 60 1[ 35 1[ 40 45[{ +TeXBase1Encoding ReEncodeFont} 38 119.552 /Palatino-Bold +rf /Fi 137[ 50 2[ 39 9[ 28 3[ 39 50 17[ 66 82[{ +TeXBase1Encoding ReEncodeFont} 6 99.6264 /Palatino-Italic +rf /Fj 137[ 56 1[ 32 42 39 2[ 54 58 88 3[ 29 58 55 1[ 48 +61 44 55 50 12[ 61 1[ 67 3[ 83 1[ 61 8[ 71 1[ 78 14[ 50 +50 50 9[ 78 38[{ TeXBase1Encoding ReEncodeFont} 25 99.6264 +/Palatino-Roman rf /Fk 139[ 47 61 57 2[ 78 83 4[ 42 83 +2[ 69 88 64 79 72 12[ 88 4[ 113 119 136 3[ 48 7[ 112 +65[{ TeXBase1Encoding ReEncodeFont} 18 143.462 /Palatino-Roman +rf end +%%EndProlog +%%BeginSetup +%%Feature: *Resolution 600dpi +TeXDict begin +%%PaperSize: A4 + +%%EndSetup +%%Page: 1 1 +1 0 bop Fk 728 918 a(The) 36 b(OMNI) g(Thr) m(ead) f(Abstracti) n(on) p +Fj 1293 1176 a(T) -9 b(ristan) 26 b(Richar) n(dson) 1022 +1293 y(A) -7 b(T&T) 24 b(Laboratories) i(Cambridge) p +Fi 1192 1504 a(Revised) p Fj 24 w(November) f(2001) p +Fh 63 1961 a(1) 119 b(Introduction) p Fg 63 2183 a(The) 20 +b(OMNI) h(thr) n(ead) g(abstraction) g(is) h(des) n(igned) f(to) f(pr) n +(ovide) h(a) h(common) f(set) f(of) h(thr) n(ead) g(oper) n(-) 63 +2296 y(ations) h(for) g(use) g(in) h(pr) n(ograms) f(written) f(in) i +(C++.) 29 b(Pr) n(ograms) 22 b(written) g(using) f(the) h(abstraction) +63 2409 y(should) 30 b(be) g(much) i(easier) e(to) g(port) g(betwee) n +(n) h(dif) n(fer) n(ent) g(ar) n(chi) r(tectur) l(es) g(with) g(dif) n +(fer) n(ent) f(un-) 63 2522 y(derlying) 21 b(thr) n(eads) h +(primitives.) 204 2640 y(The) 17 b(pr) n(ogramming) h(interface) g(is) f +(designed) f(to) h(be) h(similar) h(to) e(the) g(C) i(language) e +(interface) 63 2753 y(to) k(POSIX) h(thr) n(eads) f(\(IEEE) g(draft) h +(standar) n(d) f(100) r(3.1c) i(\227) f(pr) n(eviously) g(1003) r(.4a,) +g(often) g(known) 63 2866 y(as) g(\223pthr) n(eads\224) h([POSIX94]\).) +204 2985 y(Much) 18 b(of) f(the) g(abstraction) i(consists) d(of) i +(simple) g(C++) g(object) g(wrappers) e(ar) n(ound) h(pthr) n(ead) 63 +3098 y(calls.) 28 b(Howe) n(ver) 20 b(for) f(some) f(featur) n(es) g +(such) h(as) h(thr) n(ead-spe) n(ci\002c) h(data,) f(a) f(better) f +(interface) i(can) 63 3211 y(be) i(of) n(fer) n(ed) g(because) h(of) f +(the) g(use) g(of) g(C++.) 204 3329 y(Some) 28 b(of) h(the) f(mor) n(e) +h(complex) f(featur) n(es) g(of) h(pthr) n(eads) f(ar) n(e) h(not) f +(suppo) n(rted) g(because) h(of) 63 3442 y(the) e(dif) n(\002culty) i +(of) f(ensuring) g(the) f(same) h(featur) n(es) g(can) h(be) f(of) n +(fer) n(ed) g(on) g(top) g(of) g(other) f(thr) n(ead) 63 +3555 y(sys) n(tems.) f(Such) 17 b(featur) n(es) g(include) h(thr) n +(ead) f(cancell) r(ation) g(and) h(complex) g(schedu) n(ling) h(contr) n +(ol) 63 3668 y(\(thoug) n(h) k(simple) g(thr) n(ead) f(priorities) g +(ar) n(e) h(supp) n(orted\).) 204 3787 y(The) i(abstraction) h(layer) h +(is) f(curr) n(ently) f(implemented) g(for) h(the) f(following) i(ar) n +(chitectur) n(es) 63 3900 y(/) 22 b(thr) n(ead) h(sys) n(tems:) p +Ff 199 4141 a(\017) p Fg 46 w(Solaris) g(2.x) g(using) f(pthr) n(eads) f +(draft) h(10) p Ff 199 4351 a(\017) p Fg 46 w(Solaris) h(2.x) g(using) f +(solaris) g(thr) n(eads) g(\(but) h(pthr) n(eads) e(version) h(is) h +(now) f(standar) n(d\)) p Ff 199 4561 a(\017) p Fg 46 +w(Alpha) h(OSF1) g(using) f(pthr) n(eads) f(draft) i(4) p +Ff 199 4772 a(\017) p Fg 46 w(W) -5 b(indows) 21 b(NT) h(using) g(NT) g +(thr) n(eads) p Ff 199 4982 a(\017) p Fg 46 w(Linux) g(2.x) h(using) f +(Linuxthr) n(ead) g(0.5) h(\(which) h(is) e(based) g(on) h(pthr) n +(eads) e(draft) i(10\)) p Ff 199 5193 a(\017) p Fg 46 +w(Linux) f(2.x) h(using) f(MIT) g(pthr) n(eads) f(\(which) j(is) f +(based) f(on) g(draft) h(8\)) p Ff 199 5403 a(\017) p +Fg 46 w(A) -7 b(TMos) 22 b(using) g(pthr) n(eads) f(draft) h(6) i +(\(but) e(not) g(V) -5 b(irata) 23 b(A) -7 b(TMos\)) 1684 +5652 y(1) p 90 rotate dyy eop +%%Page: 2 2 +2 1 bop Fg 221 249 a(2) p Fe 1797 w(2) 91 b(SYNCHRONI) n(SA) -7 +b(TION) 22 b(OBJECTS) p Fg 362 548 a(See) h(the) p Fd +22 w(omni) n(thre) n(ad.h) p Fg 22 w(header) f(\002le) i(for) f(full) i +(det) n(ail) r(s) e(of) g(the) g(API.) f(The) h(des) n(criptions) 221 +661 y(below) 35 b(assume) g(you) g(have) h(some) e(pr) n(evious) h +(knowled) n(ge) g(of) h(thr) n(eads) n(,) j(mutexes) n(,) g(condi-) 221 +774 y(tion) f(varia) r(bles) g(and) g(semaphor) n(es) n(.) 75 +b(Also) 38 b(r) n(efer) f(to) h(other) f(document) n(ation) i(\([Birr) n +(ell89) r(],) 221 887 y([POSIX94) q(]\)) 22 b(for) g(further) f +(explanation) i(of) f(thes) n(e) g(ideas) g(\(particularly) h +(condition) f(variab) r(les,) 221 1000 y(the) g(use) g(of) g(which) h +(may) g(not) f(be) h(particularly) h(intuitive) f(when) f(\002rst) f +(encounter) n(ed) n(\).) p Fh 221 1299 a(2) 119 b(Synchronisation) 31 +b(objects) p Fg 221 1510 a(Synchr) n(onisation) 26 b(objects) h(ar) n +(e) g(used) e(to) h(synchr) n(onise) g(thr) n(eads) g(within) h(the) f +(same) h(pr) n(ocess) n(.) 221 1623 y(Ther) n(e) j(is) i(no) f(inter) n +(-pr) n(ocess) f(synchr) n(onisation) g(pr) n(ovided.) 53 +b(The) 30 b(synchr) n(onisation) h(objects) 221 1735 +y(pr) n(ovided) 22 b(ar) n(e) h(mutexes) n(,) g(condition) f(variab) r +(les) g(and) h(counting) f(semaphor) n(e) n(s.) p Fc +221 1991 a(2.1) 99 b(Mutex) p Fg 221 2168 a(An) 26 b(object) g(of) h +(typ) n(e) p Fd 26 w(omni) n(_mute) n(x) p Fg 26 w(is) g(use) n(d) f +(for) h(mutual) f(exclusion.) 39 b(It) 26 b(pr) n(ovides) f(two) g(op-) +221 2281 y(erations,) p Fd 37 w(lock\() n(\)) p Fg 35 +w(and) p Fd 35 w(unloc) n(k\(\)) p Fg(.) 64 b(The) 35 +b(alternative) h(names) p Fd 35 w(acq) n(uire\() n(\)) p +Fg 35 w(and) p Fd 35 w(re-) 221 2393 y(leas) n(e\(\)) p +Fg 19 w(can) 21 b(be) f(used) f(if) i(pr) n(eferr) n(ed) n(.) 27 +b(Behaviour) 20 b(is) g(unde\002ne) n(d) g(when) f(a) i(thr) n(ead) f +(attempt) n(s) 221 2506 y(to) 30 b(lock) h(the) e(same) i(mutex) f +(again) h(or) f(when) g(a) h(mutex) f(is) h(locked) e(by) i(one) e(thr) +n(ead) h(and) h(un-) 221 2619 y(locked) 22 b(by) h(a) g(dif) n(fer) n +(ent) f(thr) n(ead.) p Fc 221 2874 a(2.2) 99 b(Condition) 26 +b(V) -11 b(ariable) p Fg 221 3051 a(A) 28 b(condition) f(varia) r(ble) h +(is) g(r) n(epr) n(ese) n(nted) f(by) h(an) p Fd 28 w(omn) n(i_con) n +(diti) n(on) p Fg 27 w(and) g(is) g(used) e(for) i(sig-) 221 +3164 y(nalli) r(ng) 20 b(betwee) n(n) g(thr) n(eads.) 26 +b(A) 21 b(call) h(to) p Fd 19 w(wait\() n(\)) p Fg 20 +w(causes) e(a) h(thr) n(ead) e(to) h(wait) h(on) f(the) f(condition) 221 +3277 y(varia) r(ble.) 45 b(A) 28 b(call) i(to) p Fd 27 +w(sign) n(al\(\)) p Fg 27 w(wakes) d(up) h(at) g(least) g(one) f(thr) n +(ead) h(if) h(any) f(ar) n(e) g(waiting.) 45 b(A) 221 +3390 y(call) 25 b(to) p Fd 22 w(bro) n(adca) n(st\(\)) p +Fg 21 w(wakes) d(up) g(all) i(thr) n(eads) e(waiting) h(on) f(the) g +(condition) g(varia) r(ble.) 362 3503 y(When) 30 b(constr) o(ucte) n +(d,) i(a) e(pointer) f(to) h(an) p Fd 30 w(omni) n(_mute) n(x) p +Fg 30 w(must) f(be) h(given.) 50 b(A) 30 b(condition) 221 +3616 y(varia) r(ble) p Fd 33 w(wait\() n(\)) p Fg 33 +w(has) j(an) h(implic) r(it) f(mutex) p Fd 33 w(unlo) n(ck\(\)) p +Fg 32 w(and) p Fd 33 w(lock) n(\(\)) p Fg 33 w(ar) n(ound) g(it.) 60 +b(The) 221 3729 y(link) 30 b(between) f(condition) g(varia) r(ble) h +(and) g(mutex) f(lasts) g(for) h(the) f(lifetime) i(of) e(the) g +(condition) 221 3842 y(varia) r(ble) c(\(unlike) h(pthr) n(eads) e +(wher) n(e) g(the) h(link) h(is) f(only) g(for) g(the) g(duration) f +(of) i(the) e(wait\).) 37 b(The) 221 3955 y(same) 23 +b(mutex) f(may) h(be) f(used) f(with) i(several) f(condition) h(variab) +r(les.) 362 4068 y(A) c(wait) g(with) g(a) g(timeout) f(can) i(be) e +(achieved) h(by) g(call) r(ing) p Fd 19 w(tim) n(ed_w) n(ait\(\)) p +Fg -2 w(.) 27 b(This) 18 b(is) h(given) 221 4181 y(an) 27 +b(absolute) e(time) h(to) f(wait) h(until.) 38 b(The) 26 +b(r) n(outine) p Fd 25 w(omn) n(i_thr) n(ead:) n(:get_) n(time) n(\(\)) +p Fg 25 w(can) h(be) 221 4293 y(used) 21 b(to) h(turn) g(a) h(r) n +(elativ) r(e) f(time) g(into) h(an) g(absolute) f(time.) p +Fd 28 w(tim) n(ed_wa) n(it\(\)) p Fg 21 w(r) n(eturns) p +Fd 21 w(true) p Fg 21 w(if) 221 4406 y(the) 27 b(condition) h(was) g +(signalled,) p Fd 29 w(false) p Fg 26 w(if) h(the) f(time) g(expir) n +(ed) f(befor) n(e) g(the) h(condition) f(vari) r(-) 221 +4519 y(able) d(was) e(signalled.) p Fc 221 4774 a(2.3) 99 +b(Counting) 26 b(semaphores) p Fg 221 4951 a(An) p Fd +21 w(omn) n(i_sem) n(apho) n(re) p Fg 20 w(is) 21 b(a) h(counting) e +(semaphor) n(e) n(.) 28 b(When) 20 b(cr) n(eated) g(it) h(is) g(given) g +(an) g(initial) 221 5064 y(unsigned) j(intege) n(r) i(value.) 36 +b(When) p Fd 25 w(wai) n(t\(\)) p Fg 24 w(is) 26 b(called,) g(the) f +(value) h(is) f(decr) n(emente) n(d) g(if) h(non-) 221 +5177 y(zer) n(o.) 43 b(If) 27 b(the) g(value) h(is) f(zer) n(o) h(then) +f(the) f(thr) n(ead) h(blocks) h(instead.) 41 b(When) p +Fd 27 w(post) n(\(\)) p Fg 27 w(is) 27 b(cal) r(led,) 221 +5290 y(if) h(any) g(thr) n(eads) e(ar) n(e) i(blocked) f(in) p +Fd 27 w(wait\() n(\)) p Fg(,) h(exactly) f(one) g(thr) n(ead) g(is) g +(woken.) 41 b(If) 27 b(no) g(thr) n(eads) 221 5403 y(wer) n(e) 22 +b(blocked) g(then) g(the) g(value) h(of) g(the) e(semaphor) n(e) h(is) h +(incr) n(emented.) p 90 rotate dyy eop +%%Page: 3 3 +3 2 bop Fg 3306 249 a(3) 204 548 y(If) 27 b(a) h(thr) n(ead) e(cal) r +(ls) p Fd 27 w(try) n(_wait) n(\(\)) p Fg(,) h(then) g(the) f(thr) n +(ead) g(won't) h(block) h(if) f(the) g(semaphor) n(e's) 63 +661 y(value) c(is) g(0,) g(r) n(eturning) p Fd 21 w(false) p +Fg 21 w(instead.) 204 777 y(Ther) n(e) f(is) g(no) h(way) f(of) h +(query) n(ing) g(the) f(value) h(of) g(the) f(semaphor) n(e) n(.) p +Fh 63 1095 a(3) 119 b(Thread) 29 b(object) p Fg 63 1313 +a(A) 23 b(thr) n(ead) g(is) h(r) n(epr) n(ese) n(nted) e(by) i(an) p +Fd 24 w(omni) n(_thr) n(ead) p Fg 23 w(object.) 30 b(Ther) n(e) 23 +b(ar) n(e) h(br) n(oadly) g(two) e(dif) n(fer) n(-) 63 +1426 y(ent) f(ways) i(in) g(which) g(it) g(can) g(be) g(used) n(.) 204 +1542 y(The) 28 b(\002rst) g(way) h(is) h(simply) f(to) f(cr) n(eate) h +(an) p Fd 30 w(omn) n(i_thr) n(ead) p Fg 28 w(object,) h(giving) g(a) f +(particula) r(r) 63 1655 y(function) c(which) h(the) e(thr) n(ead) h +(should) f(execute) n(.) 36 b(This) 25 b(is) g(like) g(the) g(POSIX) f +(\(or) i(any) f(other) n(\)) h(C) 63 1768 y(language) c(interface.) 204 +1884 y(The) k(second) f(method) h(of) h(use) e(is) i(to) f(cr) n(eate) h +(a) g(new) g(class) g(which) g(inherits) f(fr) n(om) p +Fd 28 w(omn) n(i_) 63 1997 y(thr) n(ead) p Fg(.) 50 b(In) 31 +b(this) f(case) g(the) g(thr) n(ead) g(will) i(execute) d(the) p +Fd 29 w(run\(\)) p Fg 29 w(member) h(function) h(of) f(the) 63 +2109 y(new) 22 b(class.) 29 b(One) 23 b(advantage) g(of) g(this) g +(scheme) f(is) h(that) g(thr) n(ead-speci\002c) g(data) g(can) h(be) f +(imple-) 63 2222 y(mented) e(simply) h(by) h(having) g(data) g(members) +f(of) h(the) f(new) g(class.) 204 2339 y(When) f(constr) o(ucted) g(a) i +(thr) n(ead) f(is) g(in) h(the) e("new") h(state) f(and) h(has) g(not) g +(actuall) r(y) g(starte) n(d.) 28 b(A) 63 2451 y(call) j(to) p +Fd 29 w(sta) n(rt\(\)) p Fg 28 w(causes) e(the) g(thr) n(ead) g(to) g +(begin) g(executing.) 47 b(A) 29 b(static) h(member) f(function) p +Fd 63 2564 a(cre) n(ate\() n(\)) p Fg 32 w(is) j(pr) n(ovided) f(to) g +(constr) o(uct) g(and) g(start) g(a) i(thr) n(ead) e(in) h(a) g(single) +g(call.) 57 b(A) 31 b(thr) n(ead) 63 2677 y(exits) 21 +b(by) i(call) r(ing) p Fd 22 w(exit\() n(\)) p Fg 22 +w(or) g(by) f(r) n(eturning) g(fr) n(om) h(the) f(thr) n(ead) g +(function.) 204 2793 y(Thr) n(eads) 27 b(can) j(be) e(either) g +(detached) f(or) h(undetached) n(.) 46 b(Detached) 28 +b(thr) n(eads) g(ar) n(e) h(thr) n(eads) 63 2906 y(for) h(which) i(all) +g(state) e(will) i(be) f(lost) f(upon) g(exit.) 52 b(Other) 30 +b(thr) n(eads) g(cannot) h(dete) n(rmine) g(when) 63 +3019 y(a) e(detached) f(thr) n(ead) h(will) h(disappear) -7 +b(,) 31 b(and) e(ther) n(efor) n(e) f(should) g(not) h(attempt) f(to) g +(access) h(the) 63 3132 y(thr) n(ead) 23 b(object) g(unless) f(some) h +(explicit) h(synchr) n(onisation) f(with) g(the) g(detached) f(thr) n +(ead) h(guar) n(-) 63 3245 y(antees) e(that) h(it) h(still) g(exists.) +204 3361 y(Undet) n(ached) 33 b(thr) n(eads) f(ar) n(e) i(thr) n(eads) e +(for) h(which) g(storage) f(is) h(not) f(r) n(eclai) r(med) g(until) i +(an-) 63 3474 y(othe) n(r) g(thr) n(ead) g(waits) g(for) g(its) g +(termination) g(by) g(call) r(ing) p Fd 34 w(joi) n(n\(\)) p +Fg(.) 61 b(An) 34 b(exit) g(value) h(can) g(be) 63 3587 +y(passe) n(d) 23 b(fr) n(om) g(an) g(undet) n(ached) g(thr) n(ead) f +(to) g(the) g(thr) n(ead) g(which) h(joins) g(it.) 204 +3703 y(Detached) 31 b(/) h(undetached) e(thr) n(eads) h(ar) n(e) i +(distinguish) n(ed) f(on) f(cr) n(eation) h(by) g(the) f(type) g(of) 63 +3816 y(function) 24 b(they) e(execute.) 30 b(Undetached) 22 +b(thr) n(eads) h(execute) g(a) h(function) g(which) g(has) g(a) p +Fd 25 w(voi) n(d*) p Fg 63 3929 a(r) n(eturn) c(typ) n(e,) h(wher) n +(eas) f(detached) f(thr) n(eads) h(execute) f(a) j(function) f(which) g +(has) g(a) p Fd 21 w(void) p Fg 19 w(r) n(eturn) 63 4042 +y(typ) n(e.) 52 b(Unfortunate) n(ly) 31 b(C++) g(member) g(functions) f +(ar) n(e) h(not) f(allowed) g(to) g(be) h(distingu) n(ished) 63 +4155 y(simply) 26 b(by) h(their) f(r) n(eturn) g(type) n(.) 40 +b(Thus) 26 b(in) h(the) f(case) h(of) g(a) g(derived) f(class) h(of) p +Fd 26 w(omni_) n(thre) n(ad) p Fg 63 4268 a(which) 20 +b(needs) e(an) j(undet) n(ached) f(thr) n(ead,) g(the) f(member) h +(function) g(execute) n(d) g(by) g(the) f(thr) n(ead) g(is) 63 +4380 y(called) p Fd 19 w(run_u) n(ndet) n(ache) n(d\(\)) p +Fg 18 w(rather) f(than) p Fd 19 w(run\() n(\)) p Fg(,) h(and) g(it) g +(is) g(started) e(by) i(calli) r(ng) p Fd 18 w(star) n(t_) 63 +4493 y(und) n(etac) n(hed\(\)) p Fg 21 w(instead) j(of) p +Fd 22 w(start) n(\(\)) p Fg(.) 204 4610 y(The) i(abstraction) i(curr) n +(ently) e(suppo) n(rts) h(thr) n(ee) f(priorities) g(of) h(thr) n(ead,) +g(but) g(no) g(guarantee) 63 4722 y(is) 33 b(made) g(of) h(how) f(this) +g(will) h(af) n(f) r(ect) f(underlying) f(thr) n(ead) h(scheduling.) 59 +b(The) 33 b(thr) n(ee) f(priori-) 63 4835 y(ties) 18 +b(ar) n(e) p Fd 20 w(PRIO) n(RITY) n(_LOW) p Fg(,) p +Fd 18 w(PRIO) n(RITY) n(_NOR) n(MAL) p Fg 19 w(and) p +Fd 19 w(PRIO) n(RITY) n(_HIG) n(H) p Fg(.) h(By) g(default) g(all) 63 +4948 y(thr) n(eads) i(r) o(un) i(at) p Fd 23 w(PRIO) n(RITY) n(_NORM) n +(AL) p Fg(.) f(A) g(dif) n(fer) n(ent) h(priority) f(can) i(be) e +(speci\002ed) g(on) g(thr) n(ead) 63 5061 y(cr) n(eation,) h(or) f +(while) h(the) f(thr) n(ead) g(is) h(r) o(unning) g(using) p +Fd 22 w(set_) n(prio) n(rity\() n(\).) p Fg 28 w(A) g(thr) n(ead's) f +(cur) n(-) 63 5174 y(r) n(ent) g(priority) g(is) g(r) n(eturned) f(by) p +Fd 23 w(pri) n(ority) n(\(\)) p Fg(.) 204 5290 y(Other) d(functions) g +(pr) n(ovided) g(ar) n(e) p Fd 19 w(sel) n(f\(\)) p Fg +18 w(which) h(r) n(eturns) e(the) h(calli) r(ng) g(thr) n(ead's) p +Fd 18 w(omn) n(i_) 63 5403 y(thr) n(ead) p Fg 36 w(object,) p +Fd 40 w(yie) n(ld\(\)) p Fg 35 w(which) 38 b(r) n(eques) n(ts) e(that) h +(other) e(thr) n(eads) h(be) h(allowed) g(to) f(r) o(un,) p +90 rotate dyy eop +%%Page: 4 4 +4 3 bop Fg 221 249 a(4) p Fe 1367 w(6) 91 b(THRE) n(ADED) 23 +b(I/O) g(SHUTDOWN) f(FOR) g(UNIX) p Fd 221 548 a(id\(\)) p +Fg 27 w(which) 29 b(r) n(eturns) e(an) i(intege) n(r) g(id) f(for) h +(the) e(thr) n(ead) h(for) g(use) g(in) h(debug) n(ging,) p +Fd 29 w(state) n(\(\)) p Fg(,) p Fd 221 661 a(slee) n(p\(\)) p +Fg 22 w(and) p Fd 22 w(get_t) n(ime\() n(\)) p Fg(.) p +Fh 221 953 a(4) 119 b(Per) n(-threa) n(d) 30 b(data) p +Fg 221 1164 a(omnithr) n(ead) 22 b(suppo) n(rts) g(per) n(-thr) n(ead) f +(data,) h(via) i(member) e(functions) f(of) i(the) p +Fd 21 w(omni) n(_thr) n(ead) p Fg 221 1277 a(object.) 362 +1390 y(First,) d(you) g(must) h(allocate) h(a) f(key) f(for) g(with) h +(the) p Fd 20 w(omni) n(_thre) n(ad::) n(allo) n(cate_) n(key\() n(\)) p +Fg 221 1502 a(function.) 28 b(Then,) 21 b(any) h(object) g(whose) f +(class) h(is) g(derived) f(fr) n(om) p Fd 23 w(omni) n(_thr) n(ead::) n +(valu) n(e_t) p Fg 221 1615 a(can) 27 b(be) f(stor) n(e) n(d) g(using) f +(the) p Fd 26 w(set) n(_val) n(ue\(\)) p Fg 25 w(function.) 38 +b(V) -8 b(alues) 25 b(ar) n(e) h(r) n(etrieved) f(or) h(r) n(emoved) 221 +1728 y(with) p Fd 23 w(get) n(_valu) n(e\(\)) p Fg 21 +w(and) p Fd 23 w(remo) n(ve_v) n(alue\() n(\)) p Fg 22 +w(r) n(espectively) -10 b(.) 362 1841 y(When) 23 b(the) g(thr) n(ead) g +(exits,) g(all) i(per) n(-thr) n(ead) e(data) h(is) g(delet) n(ed) f +(\(hence) h(the) e(base) i(class) g(with) 221 1954 y(virtual) g(dest) n +(r) o(uctor\).) 362 2067 y(Note) 17 b(that) i(the) f(per) n(-thr) n +(ead) f(data) i(functions) f(ar) n(e) p Fb 19 w(not) p +Fg 18 w(thr) n(ead) g(safe,) i(so) d(although) i(you) e(can) 221 +2180 y(access) 29 b(one) e(thr) n(ead's) h(storage) f(fr) n(om) i +(another) f(thr) n(ead,) h(ther) n(e) e(is) i(no) f(concurr) n(ency) g +(contr) n(ol.) 221 2293 y(Unless) j(you) g(r) n(eall) r(y) h(know) f +(what) h(you) f(ar) n(e) i(doing,) g(it) g(is) f(best) f(to) h(only) g +(access) g(per) n(-thr) n(ead) 221 2406 y(data) 23 b(fr) n(om) g(the) f +(thr) n(ead) g(it) h(is) g(attached) f(to.) p Fh 221 +2698 a(5) 119 b(Using) 31 b(OMNI) d(threads) h(in) h(your) g(program) p +Fg 221 2909 a(Obvi) r(ously) 16 b(you) h(need) g(to) g(include) h(the) p +Fd 16 w(omnit) n(hrea) n(d.h) p Fg 17 w(header) e(\002le) i(in) g(your) +f(sour) n(ce) g(code,) 221 3021 y(and) 25 b(link) g(in) h(the) e +(omnithr) n(ead) g(libra) r(ry) g(with) h(your) f(execut) n(abl) r(e.) +34 b(Because) 23 b(ther) n(e) h(is) h(a) g(single) p +Fd 221 3134 a(omni) n(threa) n(d.h) p Fg 30 w(for) 32 +b(all) h(platforms,) h(certain) e(pr) n(epr) n(oces) n(sor) f +(de\002nes) f(must) h(be) g(given) h(as) 221 3247 y(compiler) 25 +b(options) n(.) 33 b(The) 23 b(easiest) g(way) h(to) g(do) f(this) h +(is) g(to) g(stud) n(y) g(the) g(make\002les) f(given) h(in) h(the) 221 +3360 y(examples) i(pr) n(ovided) g(with) g(this) g(distribution.) 42 +b(If) 27 b(you) g(ar) n(e) g(to) g(include) h(OMNI) f(thr) n(eads) g +(in) 221 3473 y(your) 18 b(own) g(development) g(envir) n(onment,) h +(thes) n(e) g(ar) n(e) g(the) f(necessary) g(pr) n(epr) n(oce) n(ssor) g +(de\002nes) n(:) p 362 3567 3287 4 v 360 3680 4 113 v +412 3646 a(Platform) p 1312 3680 V 599 w(Pr) n(epr) n(ocess) n(or) 23 +b(De\002nes) p 3648 3680 V 362 3683 3287 4 v 362 3700 +V 360 3813 4 113 v 412 3779 a(Sun) f(Solaris) h(2.x) p +1312 3813 V Fd 365 w(-D__) n(suno) n(s__) 54 b(-D_) n(_spa) n(rc__) f +(-D__) n(OSVER) n(SION) n(__=5) p 3648 3813 V 360 3926 +V 1312 3926 V 1363 3892 a(-DSV) n(R4) h(-DUs) n(ePth) n(read) f(-D_R) n +(EENT) n(RANT) p 3648 3926 V 362 3929 3287 4 v 360 4042 +4 113 v Fg 412 4008 a(x86) 24 b(Linux) e(2.0) p 1312 +4042 V Fd 418 w(-D__) n(linu) n(x__) 54 b(-D_) n(_i86) n(__) g(-D__) n +(OSVE) n(RSION) n(__=2) p 3648 4042 V 360 4155 V Fg 412 +4121 a(with) 23 b(linuxthr) n(eads) f(0.5) p 1312 4155 +V Fd 100 w(-D_R) n(EENT) n(RANT) p 3648 4155 V 362 4158 +3287 4 v 360 4271 4 113 v Fg 412 4237 a(Digital) i(Unix) f(3.2) p +1312 4271 V Fd 320 w(-D__) n(osf1) n(__) 54 b(-D__) n(alph) n(a__) g +(-D_) n(_OSV) n(ERSIO) n(N__=) n(3) p 3648 4271 V 360 +4384 V 1312 4384 V 1363 4350 a(-D_R) n(EENT) n(RANT) p +3648 4384 V 362 4387 3287 4 v 360 4500 4 113 v Fg 412 +4466 a(W) -5 b(indows) 22 b(NT) p 1312 4500 V Fd 411 +w(-D__) n(NT__) 53 b(-MD) p 3648 4500 V 362 4503 3287 +4 v Fh 221 4740 a(6) 119 b(Threaded) 29 b(I/O) g(shutdown) h(for) g +(Unix) p Fg 221 4951 a(or) -7 b(,) 20 b(how) e(one) g(thr) n(ead) h +(shou) n(ld) h(tell) f(another) f(thr) n(ead) g(to) h(shut) f(down) g +(when) g(it) h(might) g(be) g(doing) 221 5064 y(a) k(blocking) g(cal) r +(l) g(on) f(a) h(socket) n(.) p Fb 362 5177 a(If) h(you) e(are) i +(using) e(omniOR) n(B,) h(you) e(don') n(t) i(need) g(to) g(worry) f +(about) g(all) i(this,) f(since) h(om-) 221 5290 y(niORB) i(does) h(it) +h(for) f(you) n(.) p Fg 41 w(This) g(section) f(is) h(only) g(r) n +(elevant) g(if) h(you) e(ar) n(e) h(using) f(omnithr) n(ead) 221 +5403 y(in) d(your) f(own) g(socket) n(-based) h(pr) n(ogramming.) k(It) +22 b(is) h(also) g(serious) n(ly) g(out) f(of) h(date.) p +90 rotate dyy eop +%%Page: 5 5 +5 4 bop Fe 63 249 a(6.1) 91 b(r) n(ead\(\)) p Fg 2800 +w(5) 204 548 y(Unfortunate) n(ly) 35 b(ther) n(e) e(doe) n(sn't) h +(seem) f(to) h(be) g(a) h(standar) n(d) e(way) i(of) f(doing) f(this) h +(which) 63 661 y(works) 19 b(acr) n(oss) i(all) i(Unix) e(syst) n(ems.) +27 b(I) 21 b(have) g(investigated) f(the) h(behaviour) g(of) g(Solaris) +h(2.5) g(and) 63 774 y(Digital) k(Unix) g(3.2.) 36 b(On) 26 +b(Digital) h(Unix) e(everyth) n(ing) h(is) f(\002ne,) g(as) h(the) e +(obvious) h(method) f(using) 63 887 y(shutd) n(own\(\)) 32 +b(seems) f(to) h(work) f(OK.) h(Unfortunately) f(on) h(Solaris) h(shut) +n(down) f(can) h(only) f(be) 63 1000 y(used) 25 b(on) h(a) h(connected) +e(socke) n(t,) i(so) f(we) g(need) f(devious) h(means) g(to) g(get) f +(ar) n(ound) h(this) g(lim) r(ita-) 63 1112 y(tion.) h(The) 22 +b(details) g(ar) n(e) h(summarised) g(below:) p Fc 63 +1429 a(6.1) 99 b(read\(\)) p Fg 63 1627 a(Thr) n(ead) 28 +b(A) h(is) g(in) h(a) g(loop,) g(doing) p Fd 28 w(rea) n(d\(soc) n(k\)) +p Fg(,) g(pr) n(ocess) n(ing) f(the) g(data,) h(then) f(going) f(back) +63 1739 y(into) 22 b(the) g(r) n(ead.) 204 1862 y(Thr) n(ead) 30 +b(B) h(comes) f(along) h(and) g(wants) f(to) g(shut) g(it) h(down) f +(\227) h(it) g(can't) g(cancel) h(thr) n(ead) f(A) 63 +1975 y(since) 21 b(\(i\)) h(working) e(out) g(how) g(to) h(clean) h(up) +e(accor) n(ding) i(to) e(wher) n(e) g(A) h(is) g(in) h(its) f(loop) f +(is) h(a) h(night-) 63 2088 y(mar) n(e,) h(and) f(\(ii\)) i(this) f +(isn't) f(ava) r(ilabl) r(e) g(in) h(omnithr) n(ead) f(anyway) -10 +b(.) 204 2211 y(On) 23 b(Solaris) g(2.5) g(and) g(Digital) h(Unix) f +(3.2) g(the) f(following) h(strate) n(gy) f(works:) 204 +2334 y(Thr) n(ead) g(B) g(does) p Fd 21 w(shut) n(down\() n(sock) n +(,2\)) p Fg(.) 204 2457 y(At) g(this) g(point) h(thr) n(ead) f(A) g(is) +h(either) f(blocked) g(inside) p Fd 23 w(rea) n(d\(so) n(ck\)) p +Fg(,) g(or) g(is) h(elsewhe) n(r) n(e) g(in) 63 2570 +y(the) 18 b(loop.) 26 b(If) 18 b(the) g(former) h(then) f(r) n(ead) h +(will) h(r) n(eturn) e(0,) i(indicating) f(that) g(the) f(socke) n(t) h +(is) g(closed.) 26 b(If) 63 2683 y(the) 21 b(latter) h(then) f +(eventually) h(thr) n(ead) g(A) g(will) i(call) p Fd +24 w(rea) n(d\(so) n(ck\)) p Fg 21 w(and) f(then) e(this) h(will) h(r) n +(eturn) 63 2796 y(0.) 28 b(Thr) n(ead) 22 b(A) h(should) p +Fd 21 w(clos) n(e\(soc) n(k\)) p Fg(,) f(do) g(any) g(other) g(tidying) +f(up,) h(and) h(exit.) 204 2919 y(If) 34 b(ther) n(e) g(is) h(another) f +(point) g(in) h(the) e(loop) i(that) f(thr) n(ead) g(A) h(can) g(block) +g(then) f(obviously) 63 3032 y(thr) n(ead) 19 b(B) h(needs) f(to) h(be) +g(awar) n(e) h(of) f(this) g(and) g(be) h(able) g(to) e(wake) h(it) h +(up) f(in) g(the) g(appr) n(opriate) g(way) 63 3145 y(fr) n(om) j(that) +f(point.) p Fc 63 3462 a(6.2) 99 b(accept\(\)) p Fg 63 +3659 a(Again) 25 b(thr) n(ead) g(A) h(is) f(in) h(a) g(loop,) g(this) f +(time) h(doing) e(an) i(acc) r(ept) e(on) h(listenSock,) g(dealing) h +(with) 63 3772 y(a) d(new) f(connection) g(and) h(going) e(back) j +(into) e(accept.) 28 b(Thr) n(ead) 22 b(B) g(wants) h(to) f(cancel) h +(it.) 204 3895 y(On) g(Digital) h(Unix) f(3.2) g(the) f(strateg) n(y) g +(is) h(identical) h(to) e(that) g(for) h(r) n(ead:) 204 +4018 y(Thr) n(ead) 39 b(B) g(does) p Fd 38 w(shut) n(down) n(\(list) n +(enSo) n(ck,2) n(\)) p Fg(.) 79 b(Wher) n(ever) 38 b(thr) n(ead) h(A) h +(is) f(in) h(the) 63 4131 y(loop,) i(eventually) c(it) h(will) h(r) n +(eturn) p Fd 38 w(ECONN) n(ABOR) n(TED) p Fg 38 w(fr) n(om) f(the) f +(accept) h(call) r(.) 76 b(It) 39 b(shou) n(ld) p Fd +63 4244 a(clo) n(se\(l) n(isten) n(Sock) n(\)) p Fg(,) 22 +b(tidy) g(up) g(as) h(necessary) e(and) i(exit.) 204 +4367 y(On) 30 b(Solaris) f(2.5) i(thr) n(ead) e(B) g(can't) h(do) p +Fd 29 w(shu) n(tdow) n(n\(lis) n(tenS) n(ock,2) n(\)) p +Fg 29 w(\227) g(this) f(r) n(eturns) p Fd 63 4480 a(ENO) n(TCON) n(N) p +Fg(.) 22 b(Instead) f(the) h(following) h(strateg) n(y) g(can) g(be) g +(used) n(:) 204 4603 y(First) 35 b(thr) n(ead) h(B) g(set) n(s) g(some) +f(sort) g(of) h("shutdo) n(wn) g(\003ag") g(associated) g(with) g +(listenSock.) 63 4716 y(Then) 31 b(it) h(does) p Fd 30 +w(gets) n(ocka) n(ddr\(l) n(iste) n(nSock) n(\)) p Fg +32 w(to) f(\002nd) g(out) g(which) i(port) e(listenSock) f(is) 63 +4828 y(on) 18 b(\(or) h(knows) e(alr) n(eady\),) j(sets) d(up) h(a) h +(socket) e(dummySock,) i(doe) n(s) p Fd 19 w(con) n(nect) n(\(dumm) n +(ySoc) n(k,) 63 4941 y(thi) n(s) 54 b(host,) f(por) n(t\)) p +Fg 22 w(and) 23 b(\002nally) g(does) p Fd 21 w(clos) n(e\(dum) n(mySo) n +(ck\)) p Fg(.) 204 5064 y(Wher) n(ever) 16 b(thr) n(ead) h(A) g(is) g +(in) h(the) e(loop,) h(eventually) g(it) h(will) g(call) p +Fd 19 w(acce) n(pt\(li) n(sten) n(Sock) n(\)) p Fg(.) 63 +5177 y(This) 35 b(will) j(r) n(eturn) d(successfully) g(with) h(a) h +(new) e(socket,) j(say) e(connSock.) 67 b(Thr) n(ead) 36 +b(A) f(then) 63 5290 y(checks) 20 b(to) h(see) f(if) i(the) f("shutd) n +(own) g(\003ag") h(is) f(set.) 26 b(If) c(not,) e(then) h(it's) g(a) h +(normal) g(connection.) 27 b(If) 21 b(it) 63 5403 y(is) h(set,) g(then) +f(thr) n(ead) h(A) h(closes) f(listenSock) f(and) i(connSock,) e +(tidies) h(up) g(and) h(exits.) p 90 rotate dyy eop +%%Page: 6 6 +6 5 bop Fg 221 249 a(6) p Fe 1367 w(6) 91 b(THRE) n(ADED) 23 +b(I/O) g(SHUTDOWN) f(FOR) g(UNIX) p Fc 221 548 a(6.3) 99 +b(write\(\)) p Fg 221 768 a(Thr) n(ead) 19 b(A) f(may) h(be) g(blocked) +f(in) i(write,) f(or) f(about) h(to) f(go) g(in) h(to) g(a) g(poten) n +(tiall) r(y-blocking) g(write.) 221 881 y(Thr) n(ead) j(B) h(wants) f +(to) g(shut) f(it) i(down.) 362 1016 y(On) g(Solaris) g(2.5:) 362 +1150 y(Thr) n(ead) f(B) h(doe) n(s) p Fd 23 w(shu) n(tdown) n(\(soc) n +(k,2\)) p Fg -2 w(.) 362 1285 y(If) c(thr) n(ead) f(A) h(is) g(alr) n +(eady) g(in) p Fd 20 w(wri) n(te\(s) n(ock\)) p Fg 17 +w(then) f(it) h(will) i(r) n(eturn) d(with) p Fd 18 w(ENXIO) p +Fg -2 w(.) h(If) g(thr) n(ead) 221 1398 y(A) k(calls) h(write) e(after) +g(thr) n(ead) g(B) h(calls) h(shut) n(down) e(this) g(will) i(r) n +(eturn) p Fd 22 w(EIO) p Fg(.) 362 1532 y(On) f(Digital) h(Unix) f +(3.2:) 362 1666 y(Thr) n(ead) f(B) h(doe) n(s) p Fd 23 +w(shu) n(tdown) n(\(soc) n(k,2\)) p Fg -2 w(.) 362 1801 +y(If) h(thr) n(ead) f(A) g(is) h(alr) n(eady) g(in) p +Fd 24 w(writ) n(e\(so) n(ck\)) p Fg 23 w(then) e(it) i(will) h(r) n +(eturn) e(the) f(number) i(of) f(bytes) 221 1914 y(written) 31 +b(befor) n(e) h(it) g(became) g(blocked.) 55 b(A) 32 +b(subseq) n(uent) f(cal) r(l) h(to) f(write) h(will) h(then) e(gene) n +(rate) p Fd 221 2027 a(SIGP) n(IPE) p Fg 22 w(\(or) p +Fd 22 w(EPIP) n(E) p Fg 23 w(will) 24 b(be) e(r) n(eturned) f(if) p +Fd 24 w(SIG) n(PIPE) p Fg 21 w(is) i(ignor) n(ed) e(by) i(the) f(thr) n +(ead\).) p Fc 221 2413 a(6.4) 99 b(connect\(\)) p Fg +221 2634 a(Thr) n(ead) 30 b(A) f(may) h(be) g(blocked) f(in) i +(connect,) g(or) e(about) h(to) f(go) g(in) i(to) e(a) h(poten) n +(tiall) r(y-blocking) 221 2747 y(connect.) d(Thr) n(ead) c(B) f(wants) g +(to) g(shut) g(it) g(down.) 362 2881 y(On) h(Digital) h(Unix) f(3.2:) +362 3016 y(Thr) n(ead) f(B) h(doe) n(s) p Fd 23 w(shu) n(tdown) n +(\(soc) n(k,2\)) p Fg -2 w(.) 362 3150 y(If) j(thr) n(ead) f(A) g(is) h +(alr) n(eady) g(in) p Fd 26 w(conn) n(ect\() n(sock) n(\)) p +Fg 26 w(then) e(it) i(will) h(r) n(eturn) e(a) h(successful) f(con-) 221 +3263 y(nection.) 54 b(Subsequ) n(ent) 31 b(r) n(eading) g(or) g +(writing) g(will) i(show) d(that) i(the) e(socket) g(has) h(been) g +(shut) 221 3376 y(down) 22 b(\(i.e.) 28 b(r) n(ead) 23 +b(r) n(eturns) e(0,) i(write) f(generate) n(s) p Fd 23 +w(SIG) n(PIPE) p Fg 21 w(or) g(r) n(eturns) p Fd 22 w(EPI) n(PE) p +Fg(\).) g(If) h(thr) n(ead) f(A) 221 3489 y(call) r(s) g(connect) g +(after) h(thr) n(ead) f(B) g(call) r(s) g(shutdo) n(wn) h(this) f(will) +i(r) n(eturn) p Fd 22 w(EIN) n(VAL) p Fg(.) 362 3623 +y(On) f(Solaris) g(2.5:) 362 3758 y(Ther) n(e) 35 b(is) h(no) f(way) g +(to) g(wake) g(up) g(a) h(thr) n(ead) f(which) h(is) g(blocked) f(in) h +(connect.) 66 b(Inst) n(ead) 221 3871 y(Solaris) 33 b(for) n(ces) g(us) +f(thr) n(ough) g(a) i(ridiculous) f(pr) n(oced) n(ur) n(e) g(whichever) +g(way) g(we) f(try) g(it.) 59 b(One) 221 3984 y(way) 23 +b(is) f(this:) 362 4118 y(First) d(thr) n(ead) h(A) g(cr) n(eates) f(a) +h(pipe) g(in) g(addition) g(to) f(the) g(socket) n(.) 27 +b(Instead) 19 b(of) h(shut) n(ting) g(down) 221 4231 +y(the) i(socket) n(,) h(thr) n(ead) f(B) g(simply) h(writes) e(a) i +(byte) f(to) g(the) g(pipe.) 362 4365 y(Thr) n(ead) 17 +b(A) g(meanwhile) h(set) n(s) f(the) g(socke) n(t) g(to) g +(non-blocking) g(mode) f(using) p Fd 17 w(fcn) n(tl\(s) n(ock,) 221 +4478 y(F_SE) n(TFL,) 53 b(O_NO) n(NBLO) n(CK\)) p Fg(.) 26 +b(Then) h(it) g(cal) r(ls) g(connect) g(on) g(the) f(socket) g(\227) h +(this) g(will) i(r) n(eturn) p Fd 221 4591 a(EINP) n(ROGRE) n(SS) p +Fg(.) k(Then) h(it) h(must) e(cal) r(l) p Fd 35 w(sel) n(ect\() n(\)) p +Fg(,) k(waiting) e(for) f(either) g(sock) g(to) f(become) 221 +4704 y(writable) 39 b(or) f(for) h(the) e(pipe) h(to) g(become) g(r) n +(eadable.) 75 b(If) 39 b(select) e(r) n(eturns) g(that) i(just) e(sock) +h(is) 221 4817 y(writable) 30 b(then) f(the) g(connection) g(has) h +(succeede) n(d.) 49 b(It) 29 b(then) g(need) n(s) h(to) f(set) f(the) h +(socket) f(back) 221 4930 y(to) i(blocking) h(mode) f(using) p +Fd 30 w(fcnt) n(l\(so) n(ck,) 54 b(F_S) n(ETFL) n(,) h(0\)) p +Fg(.) c(If) 31 b(instead) e(select) h(r) n(eturns) 221 +5043 y(that) 23 b(the) e(pipe) h(is) h(r) n(eadable,) g(thr) n(ead) f +(A) h(closes) e(the) h(socket) n(,) h(tidies) f(up) g(and) h(exits.) 362 +5177 y(An) g(alternative) h(method) e(is) i(similar) h(but) e(to) g +(use) f(polling) i(instead) e(of) i(the) e(pipe.) 29 +b(Thr) n(ead) 221 5290 y(B) 24 b(justs) e(sets) g(a) j(\003ag) f(and) g +(thr) n(ead) f(A) h(calls) h(select) e(with) g(a) i(timeout,) e(period) +n(ica) r(lly) h(waking) f(up) 221 5403 y(to) f(see) g(if) h(the) f +(\003ag) h(has) f(been) g(set.) p 90 rotate dyy eop +%%Page: 7 7 +7 6 bop Fe 63 249 a(REF) n(ERENCES) p Fg 2660 w(7) p +Fh 63 548 a(Refere) n(nces) p Fg 63 759 a([POSIX94]) p +Fa 46 w(Portable) 29 b(Operat) r(ing) f(System) g(Interface) h +(\(POSIX\)) e(Thr) n(ea) r(ds) h(Extension) p Fg(,) h(P1003) r(.1c) 245 +872 y(Draft) 23 b(10,) g(IEEE,) e(Septe) n(mber) i(1994) r(.) 63 +1059 y([Birr) n(ell89]) p Fa 47 w(An) 28 b(Intr) n(od) r(uction) g(to) h +(Pr) n(ogr) r(amming) g(with) g(Thr) n(ead) r(s) p Fg(,) h(Rese) n(ar) n +(ch) g(Repo) n(rt) e(35,) j(DEC) 245 1172 y(Syst) n(ems) 22 +b(Resear) n(ch) g(Center) -7 b(,) 22 b(Palo) h(Alto,) f(CA,) h(January) +g(1989) r(.) p 90 rotate dyy eop +%%Trailer +end +userdict /end-hook known{end-hook}if +%%EOF diff --git a/docs/doxygen/other/shared_ptr_docstub.h b/docs/doxygen/other/shared_ptr_docstub.h new file mode 100755 index 000000000..428dd03f1 --- /dev/null +++ b/docs/doxygen/other/shared_ptr_docstub.h @@ -0,0 +1,24 @@ +namespace boost +{ + /*! + * \brief shared_ptr documentation stub + * + * \warning + * This isn't the real shared_ptr template. It's just enough to get doxygen + * to draw pretty collaboration diagrams. + * + * An enhanced relative of scoped_ptr with reference counted copy semantics. + * The object pointed to is deleted when the last shared_ptr pointing to it + * is destroyed or reset. + */ + +template<class T> class shared_ptr +{ +public: + + T * px; // contained pointer + +}; // shared_ptr + + +} // namespace boost diff --git a/docs/doxygen/other/tv-channel-frequencies b/docs/doxygen/other/tv-channel-frequencies new file mode 100644 index 000000000..e2780eca9 --- /dev/null +++ b/docs/doxygen/other/tv-channel-frequencies @@ -0,0 +1,79 @@ +# These are the center frequencies in MHz for North American broadcast +# TV channels. Each channel is 6 MHz wide, hence the bottom edge of the +# channel is 3 MHz below the value in this table. +# +# For NTSC (Analog) TV, the picture carrier is 1.25 MHz up from the +# bottom edge. NTSC has the FM audio at bottom + 5.75 and the spike is easily +# visible. +# +# For ATSC, the pilot tone is 0.31 MHz up from the bottom. +# +# + 2 57.00 + 3 63.00 + 4 69.00 + 5 79.00 + 6 85.00 + 7 177.00 + 8 183.00 + 9 189.00 + 10 195.00 + 11 201.00 + 12 207.00 + 13 213.00 + 14 473.00 + 15 479.00 + 16 485.00 + 17 491.00 + 18 497.00 + 19 503.00 + 20 509.00 + 21 515.00 + 22 521.00 + 23 527.00 + 24 533.00 + 25 539.00 + 26 545.00 + 27 551.00 + 28 557.00 + 29 563.00 + 30 569.00 + 31 575.00 + 32 581.00 + 33 587.00 + 34 593.00 + 35 599.00 + 36 605.00 + 37 611.00 + 38 617.00 + 39 623.00 + 40 629.00 + 41 635.00 + 42 641.00 + 43 647.00 + 44 653.00 + 45 659.00 + 46 665.00 + 47 671.00 + 48 677.00 + 49 683.00 + 50 689.00 + 51 695.00 + 52 701.00 + 53 707.00 + 54 713.00 + 55 719.00 + 56 725.00 + 57 731.00 + 58 737.00 + 59 743.00 + 60 749.00 + 61 755.00 + 62 761.00 + 63 767.00 + 64 773.00 + 65 779.00 + 66 785.00 + 67 791.00 + 68 797.00 + 69 803.00 diff --git a/docs/doxygen/other/vector_docstub.h b/docs/doxygen/other/vector_docstub.h new file mode 100644 index 000000000..139ce651d --- /dev/null +++ b/docs/doxygen/other/vector_docstub.h @@ -0,0 +1,16 @@ +namespace std +{ + /*! + * \brief vector documentation stub + * + * \warning + * This isn't the real vector template. It's just enough to get doxygen + * to draw pretty collaboration diagrams. + */ + template<class T> class vector + { + public: + T *p; + }; + +} // namespace std |