Index: starting.xml =================================================================== RCS file: /home/pooma/Repository/r2/docs/manual/starting.xml,v retrieving revision 1.2 diff -c -p -r1.2 starting.xml *** starting.xml 2002/03/04 23:48:09 1.2 --- starting.xml 2002/03/15 23:07:20 *************** *** 80,95 **** &pooma; is open-source software, freely available via the Internet or perhaps packaged with this &book;. CodeSourcery, LLC, ! currently hosts the &poomatoolkit; source code. Download the the &pooma; source code &poomasourcefile; from the &pooma; download page (&poomadownloadpage;) available off the &pooma; home page (&poomahomepage;). The tgz indicates this is a compressed tar archive file. For a UNIX operating system, one can extract the source files using the ! command tar xzvf &poomasourcefile;. ! --- 80,95 ---- &pooma; is open-source software, freely available via the Internet or perhaps packaged with this &book;. CodeSourcery, LLC, ! currently hosts the &poomatoolkit; source code. Download the &pooma; source code &poomasourcefile; from the &pooma; download page (&poomadownloadpage;) available off the &pooma; home page (&poomahomepage;). The tgz indicates this is a compressed tar archive file. For a UNIX operating system, one can extract the source files using the ! command tar xzvf &poomasourcefile;. Index: template.xml =================================================================== RCS file: /home/pooma/Repository/r2/docs/manual/template.xml,v retrieving revision 1.8 diff -c -p -r1.8 template.xml *** template.xml 2002/03/04 23:48:09 1.8 --- template.xml 2002/03/15 23:07:21 *************** *** 22,39 **** compiler, not when a program runs. ! Templates permit declaring families of classes using a ! single declaration. For example, the &array; ! ! &array; ! ! ! type polymorphism ! ! template ! declaration permits using &array;s with many different value ! types, e.g., arrays of integers, arrays of floating point ! numbers, and arrays of arrays. For those interested in the implementation of &pooma;, we close the --- 22,37 ---- compiler, not when a program runs. ! Templates ! permit declaring families of classes using a single declaration. ! For example, the ! &array;&array;type ! polymorphismtemplate declaration permits ! using &array;s with many different value types, e.g., arrays of ! integers, arrays of floating point numbers, and arrays of ! arrays. For those interested in the implementation of &pooma;, we close the *************** *** 61,99 **** program's interesting computation occurred when it was executed. When writing the program, the programmer, at programming ! time, ! ! programming time ! ! would specify which statements and expressions will occur and ! which types to use. At compile time, the compiler would convert the program's source code into an executable program. Even though the compiler uses the types to produce the executable, no interesting computation would occur. At run ! time, ! ! run time ! ! the resulting executable program ! would actually perform the operations. The introduction of templates permits interesting computation to occur while the compiler produces the executable. ! Most interesting is template instantiation, ! ! template ! instantiation ! ! which produces a type ! at compile time. For example, the &array; type ! definition requires template parameters Dim, ! T, and EngineTag, specifying ! its dimension, the type of its values, and its &engine; type. To ! use this, a programmer specifies values for the template ! parameters: Array<2,double,Brick> specifies a dimension of 2, a value type of &double;, and the &brick; &engine; type. At compile time, the compiler creates a --- 59,87 ---- program's interesting computation occurred when it was executed. When writing the program, the programmer, at programming ! time,programming ! time would specify which statements and ! expressions will occur and which types to use. At compile time, the compiler would convert the program's source code into an executable program. Even though the compiler uses the types to produce the executable, no interesting computation would occur. At run ! time,run ! time the resulting executable program would ! actually perform the operations. The introduction of templates permits interesting computation to occur while the compiler produces the executable. ! Most interesting is template ! instantiation,templateinstantiation ! which produces a type at compile time. For example, the &array; ! type definition requires template parameters ! Dim, T, and ! EngineTag, specifying its dimension, the type ! of its values, and its &engine; type. To use this, a programmer ! specifies values for the template parameters: Array<2,double,Brick> specifies a dimension of 2, a value type of &double;, and the &brick; &engine; type. At compile time, the compiler creates a *************** *** 110,135 **** computable. Unfortunately, syntax for compile-time computation is more difficult than for run-time computation. Also current compilers are not as efficient as code executed by hardware. ! Run-time &cc; constructs are Turing-complete ! ! Turing complete ! ! so using templates is ! unnecessary. Thus, we can shift computation to the time which ! best trades off the ease of expressing syntax with the speed of ! computation by programmer, compiler, or computer chip. For ! example, &pooma; uses expression template technology ! ! expression templates ! ! to speed ! run-time execution of data-parallel statements. The &pooma; ! developers decided to shift some of the computation from run-time ! to compile-time using template computations. The resulting ! run-time code runs more quickly, but compiling the code takes ! longer. Also, programming time for the &pooma; developers ! increased significantly, but, most users, who are usually most ! concerned about decreasing run times, benefited. --- 98,118 ---- computable. Unfortunately, syntax for compile-time computation is more difficult than for run-time computation. Also current compilers are not as efficient as code executed by hardware. ! Run-time &cc; constructs are ! Turing-completeTuring ! complete so using templates is unnecessary. ! Thus, we can shift computation to the time which best trades off ! the ease of expressing syntax with the speed of computation by ! programmer, compiler, or computer chip. For example, &pooma; uses ! expression template technologyexpression ! templates to speed run-time execution of ! data-parallel statements. The &pooma; developers decided to shift ! some of the computation from run-time to compile-time using ! template computations. The resulting run-time code runs more ! quickly, but compiling the code takes longer. Also, programming ! time for the &pooma; developers increased significantly, but, most ! users, who are usually most concerned about decreasing run times, ! benefited. *************** *** 145,169 **** parameters, both of which are used in this book. ! template instantiation, ! ! template ! instantiation ! i.e., specifying a particular type by specifying values for template parameters. ! nested type names, ! ! nested type ! type, nested. ! ! ! type ! nested ! ! which are types specified within a class definition. We discuss each of these below. --- 128,143 ---- parameters, both of which are used in this book. ! template ! instantiation,templateinstantiation i.e., specifying a particular type by specifying values for template parameters. ! nested type names, nested ! typetype, ! nested.typenested ! which are types specified within a class definition. We discuss each of these below. *************** *** 231,241 **** follow the class name surrounded by angle brackets (<>). For example, pair<int> instantiates ! ! template ! instantiation ! the pair template class definition with T equal to ∫. That is, the compiler creates a definition for pair<int> by copying --- 205,211 ---- follow the class name surrounded by angle brackets (<>). For example, pair<int> instantiatestemplateinstantiation the pair template class definition with T equal to ∫. That is, the compiler creates a definition for pair<int> by copying *************** *** 246,261 **** The result is a definition exactly the same as pairOfInts. ! As we mentioned above, template instantiation ! ! template ! instantiation ! ! is analogous to function application. ! ! function ! application ! A template class is analogous to a function; it is a function from types and constants to classes. The analogy between compile-time and run-time programming constructs can be extended. pairOfInts. ! As we mentioned above, template ! instantiationtemplateinstantiation ! is analogous to function ! application.functionapplication A template class is analogous to a function; it is a function from types and constants to classes. The analogy between compile-time and run-time programming constructs can be extended. ! compile time ! value ! ! include types, and ! compile-time operations use these types. For both run-time and ! compile-time programming, &cc; defines default sets of values that ! all conforming compilers must support. For example, ! 3 and 6.022e+23 are run-time values that any &cc; compiler must accept. It must also accept the ∫, &bool;, and int* types. --- 227,239 ---- lists these correspondences. For example, at run time, values consist of things such as integers, floating point numbers, pointers, functions, and objects. Programs compute by operating ! on these values. The compile-time ! valuescompile ! timevalue include ! types, and compile-time operations use these types. For both ! run-time and compile-time programming, &cc; defines default sets ! of values that all conforming compilers must support. For ! example, 3 and 6.022e+23 are run-time values that any &cc; compiler must accept. It must also accept the ∫, &bool;, and int* types. *************** *** 313,341 **** template argument, e.g., any type ! packaging repeated operations ! A function ! ! function ! ! generalizes a particular operation applied to different ! values. The function parameters are placeholders for ! particular values. ! A template class generalizes a particular class ! definition using different types. The template parameters ! are placeholders for particular values. ! application ! ! function ! application ! ! ! application ! function, application. ! ! Use a function by appending function arguments surrounded by parentheses. Use a template class by appending template arguments --- 274,290 ---- template argument, e.g., any type ! packaging repeated operations A ! functionfunction ! generalizes a particular operation applied to different ! values. The function parameters are placeholders for ! particular values. A template class ! generalizes a particular class definition using different ! types. The template parameters are placeholders for ! particular values. ! application functionapplicationapplicationfunction, application. Use a function by appending function arguments surrounded by parentheses. Use a template class by appending template arguments *************** maxOut(0, 3); *** 467,492 **** and the latter stores named values, nested type names are values, i.e., types, stored within class definitions. For example, the template class &array; has an nested type name for the type of its ! domain: ! typedef typename Engine_t::Domain_t Domain_t; ! This typedef, ! ! typedef ! type, definition. ! ! ! type ! definition ! ! i.e., type ! definition, defines the type Domain_t as equivalent ! to Engine_t::Domain_t. The ! :: operator ! ! :: operator ! ! selects the Domain_t nested type from inside the Engine_t type. This illustrates how to access &array;'s Domain_t when not within &array;'s scope: Array<Dim, T, EngineTag>::Domain_t. The --- 416,429 ---- and the latter stores named values, nested type names are values, i.e., types, stored within class definitions. For example, the template class &array; has an nested type name for the type of its ! domain: typedef typename Engine_t::Domain_t Domain_t; ! This ! typedef,typedeftype, ! definition.typedefinition ! i.e., type definition, defines the type Domain_t as ! equivalent to Engine_t::Domain_t. The ! :: operator:: operator selects the Domain_t nested type from inside the Engine_t type. This illustrates how to access &array;'s Domain_t when not within &array;'s scope: Array<Dim, T, EngineTag>::Domain_t. The *************** typedef typename Engine_t::Domain_t Doma *** 554,596 **** operations on code. ! values stored in a collection ! An object stores values. ! A traits ! class ! ! traits class ! ! ! class ! traits ! traits class ! ! contains values describing a type. ! extracting values from collections ! An object's named values are extracted using the ! . operator. ! ! . operator ! ! A class's nested types and classes are extracted using ! the :: operator. ! ! :: operator ! ! ! control flow ! ! control flow ! ! to choose among operations ! if, while, goto, … ! template class specializations with pattern matching --- 491,518 ---- operations on code. ! values stored in a collection An object ! stores values. A traits ! classtraits ! classclasstraitstraits ! class contains values describing a ! type. ! extracting values from collections An ! object's named values are extracted using the ! . operator.. operator A class's nested types and classes are extracted using ! the ! :: operator.:: operator ! control flowcontrol ! flow to choose among operations ! if, while, ! goto, … template ! class specializations with pattern matching *************** enum { dimensionPlusRank = dimensions + *** 654,701 **** The use of non-integral constant values such as floating-point ! numbers at compile time is restricted. ! ! ! ! ! Other compile-time values include pointers ! ! pointer ! ! to objects and ! functions, references ! ! reference ! ! to objects and functions, and executable ! code. For example, a pointer to a function ! ! pointer ! function ! ! ! function pointer ! pointer, function. ! ! sometimes is passed to ! a template function to perform a specific task. Even though ! executable code ! ! executable code ! ! cannot be directly represented in a program, it is ! a compile-time value which the compiler uses. A simple example is ! a class that is created by template instantiation, ! ! template ! instantiation ! ! e.g., pair<int>. Conceptually, the ∫ template ! argument is substituted throughout the pair template ! class to produce a class definition. Although neither the ! programmer nor the user sees this class definition, it is represented inside the compiler, which can use and manipulate the code. The use of non-integral constant values such as floating-point ! numbers at compile time is restricted. ! ! Other compile-time values include ! pointerspointer to ! objects and functions, ! referencesreference to ! objects and functions, and executable code. For example, a ! pointer to a ! functionpointerfunctionfunction ! pointerpointer, function. ! sometimes is passed to a template function to perform a specific ! task. Even though executable codeexecutable ! code cannot be directly represented in a ! program, it is a compile-time value which the compiler uses. A ! simple example is a class that is created by template ! instantiation,templateinstantiation ! e.g., pair<int>. Conceptually, the ∫ ! template argument is substituted throughout the pair ! template class to produce a class definition. Although neither ! the programmer nor the user sees this class definition, it is represented inside the compiler, which can use and manipulate the code. ! Through template programming, the compiler's optimizer ! ! optimizer ! compiler, optimizer. ! ! ! optimization ! compiler, optimizer. ! ! ! compiler ! optimizer ! ! can ! transform complicated code into much simpler code. In , we describe the complicated template code used to implement efficiently data-parallel operations. Although the template code is --- 605,616 ---- ! Through template programming, the compiler's ! optimizeroptimizercompiler, ! optimizer.optimizationcompiler, ! optimizer.compileroptimizer ! can transform complicated code into much simpler code. In , we describe the complicated template code used to implement efficiently data-parallel operations. Although the template code is *************** struct usuallySimpleClass<false> { *** 757,827 **** compilers that translate &cc; code into &c; code may permit inspecting the resulting code. For example, using the command-line option with the ! KAI &cc; compiler ! ! ! compiler ! KAI ! ! ! KAI &cc; compiler ! compiler, KAI. ! ! creates a file ! containing the intermediate code. Unfortunately, ! reading and understanding the code is frequently difficult. Each category of values supports a distinct set of operations. For example, the run-time category of ! integer values supports combination using + ! and - and comparison using ! > and ==. At run ! time, the category of strings can be compared using ! == and characters can be extracted using ! subscripts with the [] operator. Compile-time ! operations are more limited. Types may be declared and used. The ! sizeof operator yields the number of ! bytes to represent an object of the specified type. Enumerations, ! constant integers, sizeof expressions, ! and simple arithmetic and comparison operators such as ! + and == can form constant expressions that can be used at compile time. These values can initialize enumerations and integer constants and be used as template arguments. At compile time, pointers and references to objects and functions can be used as template arguments, while the category of executable code supports no ! operations. (The compiler's optimizer ! ! compiler ! optimizer ! may simplify it, though.) traits class - - At run time, an object - - object ! can store multiple values, each ! having its own name. For example, a pair<int> ! object p stores two ∫s named ! left_ and right_. The . ! operator ! ! . operator ! extracts a named member from an object: ! p.left_. At compile time, a class can ! store multiple values, each having its own name. These are ! sometimes called traits classes. For example, implementing ! data-parallel operations requiring storing a tree of types. ! The ExpressionTraits<BinaryNode<Op, Left, Right&closeclose; traits class stores the types of a binary node representing the operation of Op on left and right children. Its definition --- 650,704 ---- compilers that translate &cc; code into &c; code may permit inspecting the resulting code. For example, using the command-line option with the ! KAI &cc; ! compilercompilerKAIKAI &cc; ! compilercompiler, ! KAI. creates a file containing the intermediate ! code. Unfortunately, reading and understanding the code is ! frequently difficult. Each category of values supports a distinct set of operations. For example, the run-time category of ! integer values supports combination using + and ! - and comparison using > ! and ==. At run time, the category of strings ! can be compared using == and characters can be ! extracted using subscripts with the [] ! operator. Compile-time operations are more limited. Types may be ! declared and used. The sizeof operator yields ! the number of bytes to represent an object of the specified type. ! Enumerations, constant integers, sizeof ! expressions, and simple arithmetic and comparison operators such ! as + and == can form constant expressions that can be used at compile time. These values can initialize enumerations and integer constants and be used as template arguments. At compile time, pointers and references to objects and functions can be used as template arguments, while the category of executable code supports no ! operations. (The compiler's ! optimizercompileroptimizer may simplify it, though.) traits class ! At run time, an ! objectobject can store ! multiple values, each having its own name. For example, a ! pair<int> object p ! stores two ∫s named left_ and right_. The . ! operator. operator extracts a named member from an object: ! p.left_. At compile time, a class can store ! multiple values, each having its own name. These are sometimes ! called traits classes. For example, implementing ! data-parallel operations requiring storing a tree of types. The ! ExpressionTraits<BinaryNode<Op, Left, Right&closeclose; traits class stores the types of a binary node representing the operation of Op on left and right children. Its definition *************** struct ExpressionTraits<BinaryNode< *** 869,889 **** Control flow determines which code is used. At run time, control-flow statements such as if, ! while, and ! goto determine which statements to ! execute. Template programming uses two mechanisms: template class ! specializations and pattern matching. These are similar to ! control flow in functional programming languages. A template class specialization is a class definition specific to one or more template arguments. For example, the ! implementation for data-parallel operations ! ! data-parallel operation ! ! uses the templated CreateLeaf. The default ! definition works for any template ! argument T: template<class T> struct CreateLeaf --- 746,764 ---- Control flow determines which code is used. At run time, control-flow statements such as if, ! while, and goto determine ! which statements to execute. Template programming uses two ! mechanisms: template class specializations and pattern matching. ! These are similar to control flow in functional programming ! languages. A template class specialization is a class definition specific to one or more template arguments. For example, the ! implementation for data-parallel ! operationsdata-parallel ! operation uses the templated ! CreateLeaf. The default definition works for any ! template argument T: template<class T> struct CreateLeaf *************** struct CreateLeaf<Expression<T&clo *** 932,944 **** Control flow using template specializations and pattern matching is similar to switch ! statements. ! ! switch ! A switch statement has a condition and one or more pairs of case labels and associated ! code. The code associated with the the case label whose value matches the condition is executed. If no case label matches the condition, the default code, if present, is used. In template programming, instantiating a template, e.g., --- 807,816 ---- Control flow using template specializations and pattern matching is similar to switch ! statements.switch A switch statement has a condition and one or more pairs of case labels and associated ! code. The code associated with the case label whose value matches the condition is executed. If no case label matches the condition, the default code, if present, is used. In template programming, instantiating a template, e.g., *************** CreateLeaf<Expression<int&closeclo *** 956,964 **** default label since it matches any arguments. If no set of template parameters match (which is impossible for our example) or if more than one set are best matches, the code is ! incorrect. ! ! --- 828,834 ---- default label since it matches any arguments. If no set of template parameters match (which is impossible for our example) or if more than one set are best matches, the code is ! incorrect. *************** void f(const T& t) { … } *** 983,1008 **** functions equivalent to f(const int&), f(const bool&), f(const int*&), …. Using a templated class ! definition with a static member function, ! ! function ! static member ! ! ! static member function ! function, static member ! ! we can define an equivalent function: ! ! function ! static member ! equivalence with function template ! ! ! template ! function ! equivalence with static member function ! template <typename T> class F { --- 853,859 ---- functions equivalent to f(const int&), f(const bool&), f(const int*&), …. Using a templated class ! definition with a static member function,functionstatic memberstatic member functionfunction, static member we can define an equivalent function:functionstatic memberequivalence with function templatetemplatefunctionequivalence with static member function template <typename T> class F { *************** operator+(const Array<D1,T1,E1> & *** 1036,1079 **** possible to write expressions such as a1 + a2. Member functions can also be templated. This permits, for example, overloading of assignment operators defined ! within templated classes. ! ! ! ! Function objects ! ! function ! object ! ! are frequently useful in run-time code. They consist of a function plus some additional storage and are usually implemented as structures with data members and a function ! call operator. ! ! function ! call operator ! ! Analogous classes can be used at compile time. ! Using the transformation ! ! function ! static member ! equivalence with function template ! ! ! template ! function ! equivalence with static member function ! ! introduced in the previous paragraph, we see that any function can be transformed into a class containing a ! static member function. ! ! function ! static member ! ! Internal type definitions, enumerations, and static constant values can be added to the class. The static member function can use these values during its computation. The CreateLeaf structure, introduced above, illustrates this. --- 887,901 ---- possible to write expressions such as a1 + a2. Member functions can also be templated. This permits, for example, overloading of assignment operators defined ! within templated classes. ! Function objectsfunctionobject are frequently useful in run-time code. They consist of a function plus some additional storage and are usually implemented as structures with data members and a function ! call operator.functioncall operator Analogous classes can be used at compile time. ! Using the transformationfunctionstatic memberequivalence with function templatetemplatefunctionequivalence with static member function introduced in the previous paragraph, we see that any function can be transformed into a class containing a ! static member function.functionstatic member Internal type definitions, enumerations, and static constant values can be added to the class. The static member function can use these values during its computation. The CreateLeaf structure, introduced above, illustrates this. Index: tutorial.xml =================================================================== RCS file: /home/pooma/Repository/r2/docs/manual/tutorial.xml,v retrieving revision 1.12 diff -c -p -r1.12 tutorial.xml *** tutorial.xml 2002/02/27 03:51:53 1.12 --- tutorial.xml 2002/03/15 23:07:22 *************** *** 690,696 **** each context. Regardless, the containers' domains are now distributed among the contexts so the program can run. When a patch needs data from another patch, the &poomatoolkit; sends messages to ! the desired patch uses the message-passing library. All such communication is automatically performed by the &toolkit; with no need for programmer or user input. --- 690,696 ---- each context. Regardless, the containers' domains are now distributed among the contexts so the program can run. When a patch needs data from another patch, the &poomatoolkit; sends messages to ! the designated patch uses the message-passing library. All such communication is automatically performed by the &toolkit; with no need for programmer or user input. *************** MultiPatch<UniformTag, Remote<Bric *** 737,743 **** or MultiPatch<UniformTag, Remote<CompressibleBrick&closeclose; ! or &engine;s. The computations for a distributed implementation are exactly the same as for a sequential implementation. The &poomatoolkit; and --- 737,743 ---- or MultiPatch<UniformTag, Remote<CompressibleBrick&closeclose; ! &engine;s. The computations for a distributed implementation are exactly the same as for a sequential implementation. The &poomatoolkit; and Index: figures/distributed-101.png =================================================================== RCS file: /home/pooma/Repository/r2/docs/manual/figures/distributed-101.png,v retrieving revision 1.2 diff -c -p -r1.2 distributed-101.png Binary files /tmp/cvsQn19cB and distributed-101.png differ Index: figures/distributed.mp =================================================================== RCS file: /home/pooma/Repository/r2/docs/manual/figures/distributed.mp,v retrieving revision 1.4 diff -c -p -r1.4 distributed.mp *** figures/distributed.mp 2002/01/31 21:29:58 1.4 --- figures/distributed.mp 2002/03/15 23:07:23 *************** beginfig(101) *** 184,190 **** foo = thelabel.bot(btex \begin{tabular}{c} Each context has memory and\\ processors to execute a program. \end{tabular} etex, c[1].s); unfill bbox foo; draw foo; ! label.top(btex Computer Configuration etex, configurationBoundary.n); %% Draw the Computer Computation structures. for t = 0 upto 5: --- 184,190 ---- foo = thelabel.bot(btex \begin{tabular}{c} Each context has memory and\\ processors to execute a program. \end{tabular} etex, c[1].s); unfill bbox foo; draw foo; ! label.top(btex Computer Con\avoidfi guration etex, configurationBoundary.n); %% Draw the Computer Computation structures. for t = 0 upto 5: