Changeset 4708eaa for doc


Ignore:
Timestamp:
Feb 12, 2022, 1:56:39 PM (2 years ago)
Author:
Peter A. Buhr <pabuhr@…>
Branches:
ADT, ast-experimental, enum, master, pthread-emulation, qualifiedEnum
Children:
0db48ca
Parents:
470618c0
Message:

update PRNG documentation

File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/user/user.tex

    r470618c0 r4708eaa  
    1111%% Created On       : Wed Apr  6 14:53:29 2016
    1212%% Last Modified By : Peter A. Buhr
    13 %% Last Modified On : Sun Oct 10 12:45:00 2021
    14 %% Update Count     : 5095
     13%% Last Modified On : Sat Feb 12 10:10:11 2022
     14%% Update Count     : 5372
    1515%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    1616
     
    4040% blue highlighting ß...ß (sharp s symbol) emacs: C-q M-_
    4141% green highlighting ¢...¢ (cent symbol) emacs: C-q M-"
    42 % LaTex escape §...§ (section symbol) emacs: C-q M-'
     42% LaTex escape ...§ (section symbol) emacs: C-q M-'
    4343% keyword escape ¶...¶ (pilcrow symbol) emacs: C-q M-^
    4444% math escape $...$ (dollar symbol)
     
    8585\newcommand{\B}[1]{{\Textbf[blue]{#1}}}
    8686\newcommand{\G}[1]{{\Textbf[OliveGreen]{#1}}}
     87\newcommand{\Sp}{\R{\textvisiblespace}}
    8788\newcommand{\KWC}{K-W C\xspace}
    8889
     
    156157One of the main design philosophies of \CFA is to ``\Index{describe not prescribe}'', which means \CFA tries to provide a pathway from low-level C programming to high-level \CFA programming, but it does not force programmers to ``do the right thing''.
    157158Programmers can cautiously add \CFA extensions to their C programs in any order and at any time to incrementally move towards safer, higher-level programming.
    158 A programmer is always free to reach back to C from \CFA, for any reason, and in many cases, new \CFA features can be locally switched back to there C counterpart.
    159 There is no notion or requirement for \emph{rewriting} a legacy C program in \CFA;
     159A programmer is always free to reach back to C from \CFA, for any reason, and in many cases, new \CFA features can be locally switched back to their C counterpart.
     160There is no notion or requirement for \emph{rewriting} a legacy C program to \CFA;
    160161instead, a programmer evolves a legacy program into \CFA by incrementally incorporating \CFA features.
    161162As well, new programs can be written in \CFA using a combination of C and \CFA features.
     
    163164
    164165\Index*[C++]{\CC{}}~\cite{c++:v1} had a similar goal 30 years ago, allowing object-oriented programming to be incrementally added to C.
    165 However, \CC currently has the disadvantages of a strong object-oriented bias, multiple legacy design-choices that cannot be updated, and active divergence of the language model from C, requiring significant effort and training to incrementally add \CC to a C-based project.
     166However, \CC currently has the disadvantages of a strong object-oriented bias, multiple legacy design-choices that are difficult to update, and active divergence of the language model from C, requiring significant effort and training to incrementally add \CC to a C-based project.
    166167In contrast, \CFA has 30 years of hindsight and a clean starting point.
    167168
    168169Like \Index*[C++]{\CC{}}, there may be both old and new ways to achieve the same effect.
    169170For example, the following programs compare the C, \CFA, and \CC I/O mechanisms, where the programs output the same result.
    170 \begin{center}
     171\begin{flushleft}
    171172\begin{tabular}{@{}l@{\hspace{1em}}l@{\hspace{1em}}l@{}}
    172 \multicolumn{1}{c@{\hspace{1em}}}{\textbf{C}}   & \multicolumn{1}{c}{\textbf{\CFA}}     & \multicolumn{1}{c}{\textbf{\CC}}      \\
    173 \begin{cfa}
     173\multicolumn{1}{@{}c@{\hspace{1em}}}{\textbf{C}}        & \multicolumn{1}{c}{\textbf{\CFA}}     & \multicolumn{1}{c@{}}{\textbf{\CC}}   \\
     174\begin{cfa}[tabsize=3]
    174175#include <stdio.h>$\indexc{stdio.h}$
    175176
     
    180181\end{cfa}
    181182&
    182 \begin{cfa}
     183\begin{cfa}[tabsize=3]
    183184#include <fstream>$\indexc{fstream}$
    184185
     
    189190\end{cfa}
    190191&
    191 \begin{cfa}
     192\begin{cfa}[tabsize=3]
    192193#include <iostream>$\indexc{iostream}$
    193194using namespace std;
    194195int main() {
    195196        int x = 0, y = 1, z = 2;
    196         ®cout<<x<<" "<<y<<" "<<z<<endl;®
     197        ®cout << x << ' ' << y << ' ' << z << endl;®
    197198}
    198199\end{cfa}
    199200\end{tabular}
    200 \end{center}
     201\end{flushleft}
    201202While \CFA I/O \see{\VRef{s:StreamIOLibrary}} looks similar to \Index*[C++]{\CC{}}, there are important differences, such as automatic spacing between variables and an implicit newline at the end of the expression list, similar to \Index*{Python}~\cite{Python}.
    202203
     
    238239however, it largely extended the C language, and did not address many of C's existing problems.\footnote{%
    239240Two important existing problems addressed were changing the type of character literals from ©int© to ©char© and enumerator from ©int© to the type of its enumerators.}
    240 \Index*{Fortran}~\cite{Fortran08}, \Index*{Ada}~\cite{Ada12}, and \Index*{Cobol}~\cite{Cobol14} are examples of programming languages that took an evolutionary approach, where modern language-features (\eg objects, concurrency) are added and problems fixed within the framework of the existing language.
     241\Index*{Fortran}~\cite{Fortran08}, \Index*{Cobol}~\cite{Cobol14}, and \Index*{Ada}~\cite{Ada12} are examples of programming languages that took an evolutionary approach, where modern language-features (\eg objects, concurrency) are added and problems fixed within the framework of the existing language.
    241242\Index*{Java}~\cite{Java8}, \Index*{Go}~\cite{Go}, \Index*{Rust}~\cite{Rust} and \Index*{D}~\cite{D} are examples of the revolutionary approach for modernizing C/\CC, resulting in a new language rather than an extension of the descendent.
    242243These languages have different syntax and semantics from C, do not interoperate directly with C, and are not systems languages because of restrictive memory-management or garbage collection.
     
    333334long double _Complex ®abs®( long double _Complex );
    334335\end{cfa}
    335 The problem is \Index{name clash} between the C name ©abs© and the \CFA names ©abs©, resulting in two name linkages\index{C linkage}: ©extern "C"© and ©extern "Cforall"© (default).
     336The problem is a \Index{name clash} between the C name ©abs© and the \CFA names ©abs©, resulting in two name linkages\index{C linkage}: ©extern "C"© and ©extern "Cforall"© (default).
    336337Overloaded names must use \newterm{name mangling}\index{mangling!name} to create unique names that are different from unmangled C names.
    337338Hence, there is the same need as in \CC to know if a name is a C or \CFA name, so it can be correctly formed.
     
    377378The program is linked with the debugging version of the runtime system.
    378379The debug version performs runtime checks to aid the debugging phase of a \CFA program, but can substantially slow program execution.
    379 The runtime checks should only be removed after the program is completely debugged.
     380The runtime checks should only be removed after a program is completely debugged.
    380381\textbf{This option is the default.}
    381382
     
    452453cfa $test$.cfa -XCFA -P -XCFA parse -XCFA -n # show program parse without prelude
    453454\end{lstlisting}
     455Alternatively, multiple flages can be specified separated with commas and \emph{without} spaces.
     456\begin{lstlisting}[language=sh,{moredelim=**[is][\protect\color{red}]{®}{®}}]
     457cfa $test$.cfa -XCFA®,®-Pparse®,®-n # show program parse without prelude
     458\end{lstlisting}
    454459\begin{description}[topsep=5pt,itemsep=0pt,parsep=0pt]
    455460\item
     
    533538double ®``®forall = 3.5;
    534539\end{cfa}
    535 
    536 Existing C programs with keyword clashes can be converted by enclosing keyword identifiers in backquotes, and eventually the identifier name can be changed to a non-keyword name.
     540Existing C programs with keyword clashes can be converted by prefixing the keyword identifiers with double backquotes, and eventually the identifier name can be changed to a non-keyword name.
    537541\VRef[Figure]{f:HeaderFileInterposition} shows how clashes in existing C header-files \see{\VRef{s:StandardHeaders}} can be handled using preprocessor \newterm{interposition}: ©#include_next© and ©-I filename©.
    538542Several common C header-files with keyword clashes are fixed in the standard \CFA header-library, so there is a seamless programming-experience.
     
    627631\subsection{\texorpdfstring{\LstKeywordStyle{if} / \LstKeywordStyle{while} Statement}{if / while Statement}}
    628632
    629 The ©if©/©while© expression allows declarations, similar to ©for© declaration expression.\footnote{
    630 Declarations in the ©do©-©while© condition are not useful because they appear after the loop body.}
     633The \Indexc{if}/\Indexc{while} expression allows declarations, similar to \Indexc{for} declaration expression.\footnote{
     634Declarations in the \Indexc{do}-©while© condition are not useful because they appear after the loop body.}
    631635\begin{cfa}
    632636if ( ®int x = f()® ) ... $\C{// x != 0}$
     
    640644while ( ®struct S { int i; } x = { f() }; x.i < 4® ) ... $\C{// relational expression}$
    641645\end{cfa}
    642 Unless a relational expression is specified, each variable is compared not equal to 0, which is the standard semantics for the ©if©/©while© expression, and the results are combined using the logical ©&&© operator.
    643 The scope of the declaration(s) is local to the ©if© statement but exist within both the \emph{then} and \emph{else} clauses.
     646Unless a relational expression is specified, each variable is compared not equal to 0, which is the standard semantics for the ©if©/©while© expression, and the results are combined using the logical \Indexc{&&} operator.
     647The scope of the declaration(s) is local to the ©if©/©while© statement, \ie in both \emph{then} and \emph{else} clauses for ©if©, and loop body for ©while©.
    644648\CC only provides a single declaration always compared ©!=© to 0.
    645649
     
    649653\label{s:caseClause}
    650654
    651 C restricts the ©case© clause of a ©switch© statement to a single value.
     655C restricts the \Indexc{case} clause of a \Indexc{switch} statement to a single value.
    652656For multiple ©case© clauses associated with the same statement, it is necessary to have multiple ©case© clauses rather than multiple values.
    653 Requiring a ©case© clause for each value does not seem to be in the spirit of brevity normally associated with C.
    654 Therefore, the ©case© clause is extended with a list of values, as in:
     657Requiring a ©case© clause for each value is not in the spirit of brevity normally associated with C.
     658Therefore, the ©case© clause is extended with a list of values.
    655659\begin{cquote}
    656660\begin{tabular}{@{}l@{\hspace{3em}}l@{\hspace{2em}}l@{}}
     
    703707\subsection{\texorpdfstring{\LstKeywordStyle{switch} Statement}{switch Statement}}
    704708
    705 C allows a number of questionable forms for the ©switch© statement:
     709C allows a number of questionable forms for the \Indexc{switch} statement:
    706710\begin{enumerate}
    707711\item
    708 By default, the end of a ©case© clause\footnote{
     712By default, the end of a \Indexc{case} clause\footnote{
    709713In this section, the term \emph{case clause} refers to either a ©case© or ©default© clause.}
    710714\emph{falls through} to the next ©case© clause in the ©switch© statement;
    711 to exit a ©switch© statement from a ©case© clause requires explicitly terminating the clause with a transfer statement, most commonly ©break©:
     715to exit a ©switch© statement from a ©case© clause requires explicitly terminating the clause with a transfer statement, most commonly \Indexc{break}:
    712716\begin{cfa}
    713717switch ( i ) {
    714718  case 1:
    715719        ...
    716         // fall-through
     720        $\R{\LstCommentStyle{// fall-through}}$
    717721  case 2:
    718722        ...
    719         break;  // exit switch statement
     723        ®break;®        // exit switch statement
    720724}
    721725\end{cfa}
     
    763767}
    764768\end{cfa}
    765 This situation better handled without fall-through by allowing a list of case values \see{\VRef{s:caseClause}}.
     769This situation is better handled by a list of case values \see{\VRef{s:caseClause}}.
    766770While fall-through itself is not a problem, the problem occurs when fall-through is the default, as this semantics is unintuitive to many programmers and is different from most programming languages with a ©switch© statement.
    767771Hence, default fall-through semantics results in a large number of programming errors as programmers often \emph{forget} the ©break© statement at the end of a ©case© clause, resulting in inadvertent fall-through.
     
    777781                ...
    778782        } // if
    779   case 2:
    780         while ( j < 5 ) {
    781                 ...
    782           ®case 3:®             // transfer into "while" statement
    783                 ...
    784         } // while
    785 } // switch
    786783\end{cfa}
    787784This usage branches into control structures, which is known to cause both comprehension and technical difficulties.
     
    789786The technical problem results from the inability to ensure declaration and initialization of variables when blocks are not entered at the beginning.
    790787There are few arguments for this kind of control flow, and therefore, there is a strong impetus to eliminate it.
    791 Nevertheless, C does have an idiom where this capability is used, known as ``\Index*{Duff's device}''~\cite{Duff83}:
     788
     789This C idiom is known as ``\Index*{Duff's device}''~\cite{Duff83}, from this example:
    792790\begin{cfa}
    793791register int n = (count + 7) / 8;
     
    858856still works.
    859857Nevertheless, reversing the default action would have a non-trivial effect on case actions that compound, such as the above example of processing shell arguments.
    860 Therefore, to preserve backwards compatibility, it is necessary to introduce a new kind of ©switch© statement, called ©choose©, with no implicit fall-through semantics and an explicit fall-through if the last statement of a case-clause ends with the new keyword ©fallthrough©/©fallthru©, \eg:
     858Therefore, to preserve backwards compatibility, it is necessary to introduce a new kind of ©switch© statement, called \Indexc{choose}, with no implicit fall-through semantics and an explicit fall-through if the last statement of a case-clause ends with the new keyword \Indexc{fallthrough}/\Indexc{fallthru}, \eg:
    861859\begin{cfa}
    862860®choose® ( i ) {
     
    885883Therefore, no change is made for this issue.
    886884\item
    887 Dealing with unreachable code in a ©switch©/©choose© body is solved by restricting declarations and associated initialization to the start of statement body, which is executed \emph{before} the transfer to the appropriate ©case© clause\footnote{
     885Dealing with unreachable code in a ©switch©/©choose© body is solved by restricting declarations and initialization to the start of statement body, which is executed \emph{before} the transfer to the appropriate ©case© clause\footnote{
    888886Essentially, these declarations are hoisted before the ©switch©/©choose© statement and both declarations and statement are surrounded by a compound statement.} and precluding statements before the first ©case© clause.
    889887Further declarations at the same nesting level as the statement body are disallowed to ensure every transfer into the body is sound.
     
    908906\subsection{Non-terminating and Labelled \texorpdfstring{\LstKeywordStyle{fallthrough}}{Non-terminating and Labelled fallthrough}}
    909907
    910 The ©fallthrough© clause may be non-terminating within a ©case© clause or have a target label to common code from multiple case clauses.
     908The \Indexc{fallthrough} clause may be non-terminating within a \Indexc{case} clause or have a target label to common code from multiple case clauses.
    911909\begin{center}
    912910\begin{tabular}{@{}lll@{}}
     
    960958\end{tabular}
    961959\end{center}
    962 The target label must be below the ©fallthrough© and may not be nested in a control structure, and
    963 the target label must be at the same or higher level as the containing ©case© clause and located at
    964 the same level as a ©case© clause; the target label may be case ©default©, but only associated
    965 with the current ©switch©/©choose© statement.
     960The target label must be below the \Indexc{fallthrough} and may not be nested in a control structure, and
     961the target label must be at the same or higher level as the containing \Indexc{case} clause and located at
     962the same level as a ©case© clause; the target label may be case \Indexc{default}, but only associated
     963with the current \Indexc{switch}/\Indexc{choose} statement.
    966964
    967965\begin{figure}
     
    10761074Looping a fixed number of times, possibly with a loop index, occurs frequently.
    10771075\CFA condenses simply looping to facilitate coding speed and safety.
    1078 The ©for©/©while©/©do-while© loop-control is augmented as follows \see{examples in \VRef[Figure]{f:LoopControlExamples}}:
     1076The \Indexc{for}, \Indexc{while}, and \Indexc{do} loop-control is augmented as follows \see{examples in \VRef[Figure]{f:LoopControlExamples}}:
    10791077\begin{itemize}[itemsep=0pt]
    10801078\item
     
    11451143\subsection{\texorpdfstring{Labelled \LstKeywordStyle{continue} / \LstKeywordStyle{break} Statement}{Labelled continue / break Statement}}
    11461144
    1147 C ©continue© and ©break© statements, for altering control flow, are restricted to one level of nesting for a particular control structure.
     1145C \Indexc{continue} and \Indexc{break} statements, for altering control flow, are restricted to one level of nesting for a particular control structure.
    11481146This restriction forces programmers to use \Indexc{goto} to achieve the equivalent control-flow for more than one level of nesting.
    11491147To prevent having to switch to the ©goto©, \CFA extends the \Indexc{continue}\index{continue@©continue©!labelled}\index{labelled!continue@©continue©} and \Indexc{break}\index{break@©break©!labelled}\index{labelled!break@©break©} with a target label to support static multi-level exit\index{multi-level exit}\index{static multi-level exit}~\cite{Buhr85}, as in Java.
    1150 For both ©continue© and ©break©, the target label must be directly associated with a ©for©, ©while© or ©do© statement;
    1151 for ©break©, the target label can also be associated with a ©switch©, ©if© or compound (©{}©) statement.
     1148For both ©continue© and ©break©, the target label must be directly associated with a \Indexc{for}, \Indexc{while} or \Indexc{do} statement;
     1149for ©break©, the target label can also be associated with a \Indexc{switch}, \Indexc{if} or compound (©{}©) statement.
    11521150\VRef[Figure]{f:MultiLevelExit} shows a comparison between labelled ©continue© and ©break© and the corresponding C equivalent using ©goto© and labels.
    11531151The innermost loop has 8 exit points, which cause continuation or termination of one or more of the 7 \Index{nested control-structure}s.
     
    12241222\end{figure}
    12251223
    1226 Both labelled ©continue© and ©break© are a ©goto©\index{goto@©goto©!restricted} restricted in the following ways:
     1224Both labelled \Indexc{continue} and \Indexc{break} are a \Indexc{goto}\index{goto@©goto©!restricted} restricted in the following ways:
    12271225\begin{itemize}
    12281226\item
     
    12401238
    12411239
     1240\subsection{\texorpdfstring{Extended \LstKeywordStyle{else}}{Extended else}}
     1241\label{s:ExtendedElse}
     1242\index{extended ©else©}
     1243
     1244The ©if© statement has an optional ©else© clause executed if the conditional is false.
     1245This concept is extended to the \Indexc{while}, \Indexc{for}, and \Indexc{do} looping constructs (like Python).
     1246Hence, if the loop conditional becomes false, looping stops and the corresponding ©else© clause is executed, if present.
     1247
     1248The following example is a linear search for the key 3 in an array, where finding the key is handled with a ©break© and not finding with the ©else© clause on the loop construct.
     1249\begin{cquote}
     1250\begin{cfa}
     1251int a[10];
     1252\end{cfa}
     1253\begin{tabular}{@{}lll@{}}
     1254\begin{cfa}
     1255
     1256while ( int i = 0; i < 10 ) {
     1257  if ( a[i] == 3 ) break; // found
     1258        i += 1;
     1259} ®else® { // i == 10
     1260        sout | "not found";
     1261}
     1262\end{cfa}
     1263&
     1264\begin{cfa}
     1265
     1266for ( i; 10 ) {
     1267  if ( a[i] == 3 ) break; // found
     1268
     1269} ®else® { // i == 10
     1270        sout | "not found";
     1271}
     1272\end{cfa}
     1273&
     1274\begin{cfa}
     1275int i = 0;
     1276do {
     1277  if ( a[i] == 3 ) break; // found
     1278        i += 1;
     1279} while( i < 10 ) ®else® { // i == 10
     1280        sout | "not found";
     1281}
     1282\end{cfa}
     1283\end{tabular}
     1284\end{cquote}
     1285Note, \Index{dangling else} now occurs with \Indexc{if}, \Indexc{while}, \Indexc{for}, \Indexc{do}, and \Indexc{waitfor}.
     1286
     1287
    12421288%\subsection{\texorpdfstring{\protect\lstinline{with} Statement}{with Statement}}
    12431289\subsection{\texorpdfstring{\LstKeywordStyle{with} Statement}{with Statement}}
     
    12661312Therefore, reducing aggregate qualification is a useful language design goal.
    12671313
    1268 C allows unnamed nested aggregates that open their scope into the containing aggregate.
     1314C partially addresses the problem by eliminating qualification for enumerated types and unnamed \emph{nested} aggregates, which open their scope into the containing aggregate.
    12691315This feature is used to group fields for attributes and/or with ©union© aggregates.
    12701316\begin{cfa}
    12711317struct S {
    1272         struct { int g,  h; } __attribute__(( aligned(64) ));
     1318        struct $\R{\LstCommentStyle{/* unnamed */}}$ { int g,  h; } __attribute__(( aligned(64) ));
    12731319        int tag;
    1274         union {
     1320        union $\R{\LstCommentStyle{/* unnamed */}}$ {
    12751321                struct { char c1,  c2; } __attribute__(( aligned(128) ));
    12761322                struct { int i1,  i2; };
    12771323                struct { double d1,  d2; };
    12781324        };
    1279 };
    1280 s.g; s.h; s.tag; s.c1; s.c2; s.i1; s.i2; s.d1; s.d2;
     1325} s;
     1326enum { R, G, B };
     1327s.g; s.h;   s.tag = R;   s.c1; s.c2;   s.i1 = G; s.i2 = B;   s.d1; s.d2;
    12811328\end{cfa}
    12821329
     
    13231370\end{cfa}
    13241371where qualification is only necessary to disambiguate the shadowed variable ©i©.
    1325 
    1326 In detail, the ©with© statement may appear as the body of a function or nested within a function body.
     1372In detail, the ©with© statement may form a function body or be nested within a function body.
     1373
    13271374The ©with© clause takes a list of expressions, where each expression provides an aggregate type and object.
    13281375(Enumerations are already opened.)
     
    13331380\end{cfa}
    13341381The expression object is the implicit qualifier for the open structure-fields.
     1382
    13351383\CFA's ability to overload variables \see{\VRef{s:VariableOverload}} and use the left-side of assignment in type resolution means most fields with the same name but different types are automatically disambiguated, eliminating qualification.
    13361384All expressions in the expression list are open in parallel within the compound statement.
     
    13621410\end{cfa}
    13631411A cast or qualification can be used to disambiguate variables within a ©with© \emph{statement}.
    1364 A cast can be used to disambiguate among overload variables in a ©with© \emph{expression}:
     1412A cast can also be used to disambiguate among overload variables in a ©with© \emph{expression}:
    13651413\begin{cfa}
    13661414with ( w ) { ... }                                                      $\C{// ambiguous, same name and no context}$
     
    13711419Finally, there is an interesting problem between parameters and the function-body ©with©, \eg:
    13721420\begin{cfa}
    1373 void ?{}( S & s, int i ) with ( s ) { $\C{// constructor}$
    1374         ®s.i = i;®  j = 3;  m = 5.5; $\C{// initialize fields}$
    1375 }
    1376 \end{cfa}
    1377 Here, the assignment ©s.i = i© means ©s.i = s.i©, which is meaningless, and there is no mechanism to qualify the parameter ©i©, making the assignment impossible using the function-body ©with©.
    1378 To solve this problem, parameters are treated like an initialized aggregate:
    1379 \begin{cfa}
    1380 struct Params {
    1381         S & s;
    1382         int i;
     1421void f( S & s, char c ) with ( s ) {
     1422        ®s.c = c;®  i = 3;  d = 5.5;                    $\C{// initialize fields}$
     1423}
     1424\end{cfa}
     1425Here, the assignment ©s.c = c© means ©s.c = s.c©, which is meaningless, and there is no mechanism to qualify the parameter ©c©, making the assignment impossible using the function-body ©with©.
     1426To solve this problem, parameters \emph{not} explicitly opened are treated like an initialized aggregate:
     1427\begin{cfa}
     1428struct Params {                                                         $\C{// s explicitly opened so S \& s elided}$
     1429        char c;
    13831430} params;
    13841431\end{cfa}
    13851432and implicitly opened \emph{after} a function-body open, to give them higher priority:
    13861433\begin{cfa}
    1387 void ?{}( S & s, int ®i® ) with ( s ) ®with( $\emph{\R{params}}$ )® { // syntax not allowed, illustration only
    1388         s.i = ®i®; j = 3; m = 5.5;
     1434void f( S & s, char ®c® ) with ( s ) ®with( $\emph{\R{params}}$ )® { // syntax not allowed, illustration only
     1435        s.c = ®c;®  i = 3;  d = 5.5;
    13891436}
    13901437\end{cfa}
    13911438This implicit semantic matches with programmer expectation.
    1392 
    13931439
    13941440
     
    33973443This requirement is the same as for comma expressions in argument lists.
    33983444
    3399 Type qualifiers, \ie const and volatile, may modify a tuple type.
    3400 The meaning is the same as for a type qualifier modifying an aggregate type [Int99, x 6.5.2.3(7),x 6.7.3(11)], \ie the qualifier is distributed across all of the types in the tuple, \eg:
     3445Type qualifiers, \ie ©const© and ©volatile©, may modify a tuple type.
     3446The meaning is to distribute the qualifier across all of the types in the tuple, \eg:
    34013447\begin{cfa}
    34023448const volatile [ int, float, const int ] x;
     
    35973643Stream ©exit© implicitly returns ©EXIT_FAILURE© to the shell.
    35983644\begin{cfa}
    3599 ®exit®   | "x (" | x | ") negative value."; // terminate and return EXIT_FAILURE to shell
    3600 ®abort® | "x (" | x | ") negative value."; // terminate and generate stack trace and core file
     3645®exit®   | "x (" | x | ") negative value.";   // terminate and return EXIT_FAILURE to shell
     3646®abort® | "x (" | x | ") negative value.";   // terminate and generate stack trace and core file
    36013647\end{cfa}
    36023648Note, \CFA stream variables ©stdin©, ©stdout©, ©stderr©, ©exit©, and ©abort© overload C variables ©stdin©, ©stdout©, ©stderr©, and functions ©exit© and ©abort©, respectively.
     
    42674313        sout | '1' | '2' | '3';
    42684314        sout | 1 | "" | 2 | "" | 3;
    4269         sout | "x (" | 1 | "x [" | 2 | "x {" | 3 | "x =" | 4 | "x $" | 5 | "x £" | 6 | "x ¥"
    4270                 | 7 | "x ¡" | 8 | "x ¿" | 9 | "x «" | 10;
     4315        sout | "x (" | 1 | "x [" | 2 | "x {" | 3 | "x =" | 4 | "x $" | 5 | "x £" | 6 | "x Â¥"
     4316                | 7 | "x ¡" | 8 | "x ¿" | 9 | "x «" | 10;
    42714317        sout | 1 | ", x" | 2 | ". x" | 3 | "; x" | 4 | "! x" | 5 | "? x" | 6 | "% x"
    4272                 | 7 | "¢ x" | 8 | "» x" | 9 | ") x" | 10 | "] x" | 11 | "} x";
     4318                | 7 | "¢ x" | 8 | "» x" | 9 | ") x" | 10 | "] x" | 11 | "} x";
    42734319        sout | "x`" | 1 | "`x'" | 2 | "'x\"" | 3 | "\"x:" | 4 | ":x " | 5 | " x\t" | 6 | "\tx";
    42744320        sout | "x ( " | 1 | " ) x" | 2 | " , x" | 3 | " :x: " | 4;
     
    44464492The common usage is the short form of the mutex statement\index{ostream@©ostream©!mutex@©mutex©} to lock a stream during a single cascaded I/O expression, \eg:
    44474493\begin{cfa}
    4448 $\emph{thread\(_1\)}$ : ®mutex()® sout | "abc " | "def ";
    4449 $\emph{thread\(_2\)}$ : ®mutex()® sout | "uvw " | "xyz ";
     4494$\emph{thread\(_1\)}$ : ®mutex( sout )® sout | "abc " | "def ";
     4495$\emph{thread\(_2\)}$ : ®mutex( sout )® sout | "uvw " | "xyz ";
    44504496\end{cfa}
    44514497Now, the order of the thread execution is still non-deterministic, but the output is constrained to two possible lines in either order.
     
    44704516®mutex( sout )® {
    44714517        sout | 1;
    4472         ®mutex() sout® | 2 | 3;                         $\C{// unnecessary, but ok because of recursive lock}$
     4518        ®mutex( sout ) sout® | 2 | 3;                           $\C{// unnecessary, but ok because of recursive lock}$
    44734519        sout | 4;
    44744520} // implicitly release sout lock
     
    44824528        int x, y, z, w;
    44834529        sin | x;
    4484         ®mutex() sin® | y | z;                          $\C{// unnecessary, but ok because of recursive lock}$
     4530        ®mutex( sin )® sin | y | z;                                     $\C{// unnecessary, but ok because of recursive lock}$
    44854531        sin | w;
    44864532} // implicitly release sin lock
     
    44914537\Textbf{WARNING:} The general problem of \Index{nested locking} can occur if routines are called in an I/O sequence that block, \eg:
    44924538\begin{cfa}
    4493 ®mutex() sout® | "data:" | rtn( mon );  $\C{// mutex call on monitor}$
     4539®mutex( sout )® sout | "data:" | rtn( mon );    $\C{// mutex call on monitor}$
    44944540\end{cfa}
    44954541If the thread executing the I/O expression blocks in the monitor with the ©sout© lock, other threads writing to ©sout© also block until the thread holding the lock is unblocked and releases it.
     
    44984544\begin{cfa}
    44994545int ®data® = rtn( mon );
    4500 mutex() sout | "data:" | ®data®;
    4501 \end{cfa}
     4546mutex( sout ) sout | "data:" | ®data®;
     4547\end{cfa}
     4548
     4549
     4550\subsection{Locale}
     4551\index{stream!locale}
     4552\index{locale!stream}
     4553
     4554Cultures use different syntax, called a \newterm{locale}, for printing numbers so they are easier to read, \eg:
     4555\begin{cfa}
     455612®,®345®.®123          $\C[1.25in]{// comma separator, period decimal-point}$
     455712®.®345®,®123          $\C{// period separator, comma decimal-point}$
     455812$\Sp$345®,®123®.®     $\C{// space separator, comma decimal-point, period terminator}\CRT$
     4559\end{cfa}
     4560A locale is selected with function ©setlocale©, and the corresponding locale package \emph{must} be installed on the underlying system;
     4561©setlocale© returns ©0p© if the requested locale is unavailable.
     4562Furthermore, a locale covers the syntax for many cultural items, \eg address, measurement, money, etc.
     4563This discussion applies to item ©LC_NUMERIC© for formatting non-monetary integral and floating-point values.
     4564\VRef[Figure]{f:StreamLocale} shows selecting different cultural syntax, which may be associated with one or more countries.
     4565
     4566\begin{figure}
     4567\begin{cfa}
     4568#include <fstream.hfa>
     4569#include <locale.h>                                                     $\C{// setlocale}$
     4570#include <stdlib.h>                                                     $\C{// getenv}$
     4571
     4572int main() {
     4573        void print() {
     4574                sout | 12 | 123 | 1234 | 12345 | 123456 | 1234567;
     4575                sout | 12. | 123.1 | 1234.12 | 12345.123 | 123456.1234 | 1234567.12345;
     4576                sout | nl;
     4577        }
     4578        sout | "Default locale off";
     4579        print();
     4580        sout | "Locale on" | ®setlocale( LC_NUMERIC, getenv( "LANG" ) )®;  // enable local locale
     4581        print();
     4582        sout | "German" | ®setlocale( LC_NUMERIC, "de_DE.UTF-8" )®;  // enable German locale
     4583        print();
     4584        sout | "Ukraine" | ®setlocale( LC_NUMERIC, "uk_UA.utf8" )®;  // enable Ukraine locale
     4585        print();
     4586        sout | "Default locale off" | ®setlocale( LC_NUMERIC, "C" )®;  // disable locale
     4587        print();
     4588}
     4589
     4590Default locale off
     459112 123 1234 12345 123456 1234567
     459212. 123.1 1234.12 12345.123 123456.1234 1234567.12345
     4593
     4594Locale on en_US.UTF-8
     459512 123 1®,®234 12®,®345 123®,®456 1®,®234®,®567
     459612®.® 123®.®1 1®,®234®.®12 12®,®345®.®123 123®,®456®.®1234 1®,®234®,®567®.®12345
     4597
     4598German de_DE.UTF-8
     459912 123 1®.®234 12®.®345 123®.®456 1®.®234®.®567
     460012®.® 123®,®1®.® 1®.®234®,®12 12®.®345®,®123 123®.®456®,®1234 1®.®234®.®567®,®12345
     4601
     4602Ukraine uk_UA.utf8
     460312 123 1 234 12 345 123 456 1 234 567
     460412®.® 123®,®1®.® 1$\Sp$234®,®12®.® 12$\Sp$ 345®,®123®.® 123$\Sp$ 456®,®1234®.® 1$\Sp$ 234$\Sp$567®,®12345®.®
     4605
     4606Default locale off C
     460712 123 1234 12345 123456 1234567
     460812. 123.1 1234.12 12345.123 123456.1234 1234567.12345
     4609\end{cfa}
     4610\caption{Stream Locale}
     4611\label{f:StreamLocale}
     4612\end{figure}
    45024613
    45034614
     
    45554666\end{figure}
    45564667
     4668
    45574669\begin{comment}
    45584670\section{Types}
     
    46374749
    46384750
    4639 \subsection{Structures}
     4751\section{Structures}
    46404752
    46414753Structures in \CFA are basically the same as structures in C.
     
    52705382\subsection{Coroutine}
    52715383
    5272 \Index{Coroutines} are the precursor to tasks.
     5384\Index{Coroutines} are the precursor to threads.
    52735385\VRef[Figure]{f:FibonacciCoroutine} shows a coroutine that computes the \Index*{Fibonacci} numbers.
    52745386
     
    53725484
    53735485
    5374 \subsection{Tasks}
     5486\subsection{Threads}
    53755487
    53765488\CFA also provides a simple mechanism for creating and utilizing user level threads.
    5377 A task provides mutual exclusion like a monitor, and also has its own execution state and a thread of control.
    5378 Similar to a monitor, a task is defined like a structure:
     5489A thread provides mutual exclusion like a monitor, and also has its own execution state and a thread of control.
     5490Similar to a monitor, a thread is defined like a structure:
    53795491
    53805492\begin{figure}
     
    54205532}
    54215533\end{cfa}
    5422 \caption{Simple Tasks}
    5423 \label{f:SimpleTasks}
     5534\caption{Simple Threads}
     5535\label{f:SimpleThreads}
    54245536\end{figure}
    54255537
     
    67886900In \CFA, there are ambiguous cases with dereference and operator identifiers, \eg ©int *?*?()©, where the string ©*?*?© can be interpreted as:
    67896901\begin{cfa}
    6790 *?$\R{\textvisiblespace}$*? $\C{// dereference operator, dereference operator}$
    6791 *$\R{\textvisiblespace}$?*? $\C{// dereference, multiplication operator}$
     6902*?$\Sp$*? $\C{// dereference operator, dereference operator}$
     6903*$\Sp$?*? $\C{// dereference, multiplication operator}$
    67926904\end{cfa}
    67936905By default, the first interpretation is selected, which does not yield a meaningful parse.
     
    68136925Therefore, it is necessary to disambiguate these cases with a space:
    68146926\begin{cfa}
    6815 i++$\R{\textvisiblespace}$? i : 0;
    6816 i?$\R{\textvisiblespace}$++i : 0;
     6927i++$\Sp$? i : 0;
     6928i?$\Sp$++i : 0;
    68176929\end{cfa}
    68186930
     
    74307542char random( void );$\indexc{random}$
    74317543char random( char u ); $\C{// [0,u)}$
    7432 char random( char l, char u ); $\C{// [l,u)}$
     7544char random( char l, char u ); $\C{// [l,u]}$
    74337545int random( void );
    74347546int random( int u ); $\C{// [0,u)}$
    7435 int random( int l, int u ); $\C{// [l,u)}$
     7547int random( int l, int u ); $\C{// [l,u]}$
    74367548unsigned int random( void );
    74377549unsigned int random( unsigned int u ); $\C{// [0,u)}$
    7438 unsigned int random( unsigned int l, unsigned int u ); $\C{// [l,u)}$
     7550unsigned int random( unsigned int l, unsigned int u ); $\C{// [l,u]}$
    74397551long int random( void );
    74407552long int random( long int u ); $\C{// [0,u)}$
    7441 long int random( long int l, long int u ); $\C{// [l,u)}$
     7553long int random( long int l, long int u ); $\C{// [l,u]}$
    74427554unsigned long int random( void );
    74437555unsigned long int random( unsigned long int u ); $\C{// [0,u)}$
    7444 unsigned long int random( unsigned long int l, unsigned long int u ); $\C{// [l,u)}$
     7556unsigned long int random( unsigned long int l, unsigned long int u ); $\C{// [l,u]}$
    74457557float random( void );                                            $\C{// [0.0, 1.0)}$
    74467558double random( void );                                           $\C{// [0.0, 1.0)}$
     
    81048216Duration boot(); $\C{// monotonic duration since computer boot}$
    81058217\end{cfa}
     8218
     8219
     8220\section{Pseudo Random Number Generator}
     8221\label{s:PRNG}
     8222
     8223Random numbers are values generated independently, i.e., new values do not depend on previous values (independent trials), \eg lottery numbers, shuffled cards, dice roll, coin flip.
     8224While a primary goal of programming is computing values that are \emph{not} random, random values are useful in simulation, cryptography, games, etc.
     8225A random-number generator is an algorithm computing independent values.
     8226If the algorithm uses deterministic computation (predictable sequence of values), it generates \emph{pseudo} random numbers versus \emph{true} random numbers.
     8227
     8228All \newterm{pseudo random-number generators} (\newterm{PRNG}) involve some technique to scramble bits of a value, \eg multiplicative recurrence:
     8229\begin{cfa}
     8230rand = 36973 * (rand & 65535) + (rand >> 16); // scramble bits
     8231\end{cfa}
     8232Multiplication of large values adds new least-significant bits and drops most-significant bits.
     8233\begin{quote}
     8234\begin{tabular}{@{}r|l@{}}
     8235bits 63--32 (most)      & bits 31--0 (least)    \\
     8236\hline
     82370x0                                     & 0x3e8e36                              \\
     82380x5f                            & 0x718c25e1                    \\
     82390xad3e                          & 0x7b5f1dbe                    \\
     82400xbc3b                          & 0xac69ff19                    \\
     82410x1070f                         & 0x2d258dc6                    \\
     8242\end{tabular}
     8243\end{quote}
     8244By dropping bits 63--32, bits 31--0 become scrambled after each multiply.
     8245The least-significant bits \emph{appear} random but the same bits are always generated given a fixed starting value, called the \newterm{seed} (value 0x3e8e36 above).
     8246Hence, if a program uses the same seed, the same sequence of pseudo-random values is generated from the PRNG.
     8247Often the seed is set to another random value like a program's process identifier (©getpid©\index{getpid@©getpid©}) or time when the program is run;
     8248hence, one random value bootstraps another.
     8249Finally, a PRNG usually generates a range of large values, \eg ©[0, UINT_MAX]©, which are scaled using the modulus operator, \eg ©prng() % 5© produces random values in the range 0--4.
     8250
     8251\CFA provides a sequential and concurrent PRNGs.
     8252\begin{itemize}
     8253\item
     8254For sequential programs, like coroutining, the PRNG is used to randomize behaviour or values during execution, \eg in games, a character makes a random move or an object takes on a random value.
     8255\begin{cfa}
     8256struct PRNG { ... }; $\C[3.75in]{// opaque type}$
     8257void ?{}( PRNG & prng ); $\C{// random seed}$
     8258void ?{}( PRNG & prng, uint32_t seed ); $\C{// fixed seed}$
     8259void set_seed( PRNG & prng, uint32_t seed_ ); $\C{// set seed}$
     8260uint32_t get_seed( PRNG & prng ); $\C{// get seed}$
     8261uint32_t prng( PRNG & prng ); $\C{// [0,UINT\_MAX]}$
     8262uint32_t prng( PRNG & prng, uint32_t u ); $\C{// [0,u)}$
     8263uint32_t prng( PRNG & prng, uint32_t l, uint32_t u ); $\C{// [l,u]}$
     8264uint32_t calls( PRNG & prng ); $\C{// number of calls}\CRT$
     8265\end{cfa}
     8266Sequential execution is repeatable given the same starting seeds for all ©PRNG©s.
     8267In this scenario, it is useful to have multiple ©PRNG©, \eg one per player or object so a type is provided to generate multiple instances.
     8268\VRef[Figure]{f:SequentialPRNG} shows an example that creates two sequential ©PRNG©s, sets both to the same seed (1009), and illustrates the 3 forms for generating random values, where both ©PRNG©s generate the same sequence of values.
     8269
     8270\begin{figure}
     8271\begin{cfa}
     8272PRNG prng1, prng2;
     8273®set_seed( prng1, 1009 )®;   ®set_seed( prng2, 1009 )®;
     8274for ( 10 ) {
     8275        // Do not cascade prng calls because side-effect functions called in arbitrary order.
     8276        sout | nlOff | ®prng( prng1 )®;  sout | ®prng( prng1, 5 )®;  sout | ®prng( prng1, 0, 5 )® | '\t';
     8277        sout | ®prng( prng2 )®;  sout | ®prng( prng2, 5 )®;  sout | ®prng( prng2, 0, 5 )® | nlOn;
     8278}
     8279\end{cfa}
     8280\begin{cquote}
     8281\begin{tabular}{@{}ll@{}}
     8282\begin{cfa}
     828337301721 2 2
     82841681308562 1 3
     8285290112364 3 2
     82861852700364 4 3
     8287733221210 1 3
     82881775396023 2 3
     8289123981445 2 3
     82902062557687 2 0
     8291283934808 1 0
     8292672325890 1 3
     8293\end{cfa}
     8294&
     8295\begin{cfa}
     829637301721 2 2
     82971681308562 1 3
     8298290112364 3 2
     82991852700364 4 3
     8300733221210 1 3
     83011775396023 2 3
     8302123981445 2 3
     83032062557687 2 0
     8304283934808 1 0
     8305672325890 1 3
     8306\end{cfa}
     8307\end{tabular}
     8308\end{cquote}
     8309\vspace{-10pt}
     8310\caption{Sequential PRNG}
     8311\label{f:SequentialPRNG}
     8312\end{figure}
     8313
     8314\item
     8315For concurrent programs, it is important the PRNG is thread-safe and not a point of contention.
     8316A PRNG in concurrent programs is often used to randomize execution in short-running programs, \eg ©yield( prng() % 5 )©.
     8317
     8318Because concurrent execution is non-deterministic, seeding the concurrent PRNG is less important, as repeatable execution is impossible.
     8319Hence, there is one system-wide PRNG (global seed) but each \CFA thread has its own non-contended PRNG state.
     8320If the global seed is set, threads start with this seed, until it is reset and than threads start with the reset seed.
     8321Hence, these threads generate the same sequence of random numbers from their specific starting seed.
     8322If the global seed is \emph{not} set, threads start with a random seed, until the global seed is set.
     8323Hence, these threads generate different sequences of random numbers.
     8324If each thread needs its own seed, use a sequential ©PRNG© in each thread.
     8325
     8326There are two versions of the PRNG functions to manipulate the thread-local PRNG-state, which are differentiated by performance.
     8327\begin{cfa}
     8328void set_seed( uint32_t seed ); $\C[3.75in]{// set global seed}$
     8329uint32_t get_seed(); $\C{// get global seed}$
     8330// SLOWER
     8331uint32_t prng(); $\C{// [0,UINT\_MAX]}$
     8332uint32_t prng( uint32_t u ); $\C{// [0,u)}$
     8333uint32_t prng( uint32_t l, uint32_t u ); $\C{// [l,u]}$
     8334// FASTER
     8335uint32_t prng( $thread\LstStringStyle{\textdollar}$ & th );     $\C{// [0,UINT\_MAX]}$
     8336uint32_t prng( $thread\LstStringStyle{\textdollar}$ & th, uint32_t u ); $\C{// [0,u)}$
     8337uint32_t prng( $thread\LstStringStyle{\textdollar}$ & th, uint32_t l, uint32_t u );     $\C{// [l,u]}\CRT$
     8338\end{cfa}
     8339The slower ©prng© functions call ©active_thread© internally to access the thread-local PRNG-state, while the faster ©prng© functions are passed a pointer to the active thread.
     8340If the thread pointer is known, \eg in a thread ©main©, eliminating the call to ©active_thread© significantly reduces the cost for accessing the thread's PRNG state.
     8341\VRef[Figure]{f:ConcurrentPRNG} shows an example using the slower/faster concurrent PRNG in the program main and a thread.
     8342
     8343\begin{figure}
     8344\begin{cfa}
     8345thread T {};
     8346void main( ®T & th® ) {  // thread address
     8347        for ( i; 10 ) {
     8348                sout | nlOff | ®prng()®;  sout | ®prng( 5 )®;  sout | ®prng( 0, 5 )® | '\t';  // SLOWER
     8349                sout | nlOff | ®prng( th )®;  sout | ®prng( th, 5 )®;  sout | ®prng( th, 0, 5 )® | nlOn;  // FASTER
     8350        }
     8351}
     8352int main() {
     8353        set_seed( 1009 );
     8354        $\R{thread\LstStringStyle{\textdollar}}$ ®& th = *active_thread()®;  // program-main thread-address
     8355        for ( i; 10 ) {
     8356                sout | nlOff | ®prng()®; sout | ®prng( 5 )®; sout | ®prng( 0, 5 )® | '\t';  // SLOWER
     8357                sout | nlOff | ®prng( th )®; sout | ®prng( th, 5 )®; sout | ®prng( th, 0, 5 )® | nlOn;  // FASTER
     8358        }
     8359        sout | nl;
     8360        T t; // run thread
     8361}
     8362\end{cfa}
     8363\begin{cquote}
     8364\begin{tabular}{@{}ll@{}}
     8365\begin{cfa}
     836637301721 2 2
     8367290112364 3 2
     8368733221210 1 3
     8369123981445 2 3
     8370283934808 1 0
     83711414344101 1 3
     8372871831898 3 4
     83732142057611 4 4
     8374802117363 0 4
     83752346353643 1 3
     8376\end{cfa}
     8377&
     8378\begin{cfa}
     83791681308562 1 3
     83801852700364 4 3
     83811775396023 2 3
     83822062557687 2 0
     8383672325890 1 3
     8384873424536 3 4
     8385866783532 0 1
     838617310256 2 5
     8387492964499 0 0
     83882143013105 3 2
     8389\end{cfa}
     8390\end{tabular}
     8391\begin{cfa}
     8392// same output as above from thread t
     8393\end{cfa}
     8394\end{cquote}
     8395\caption{Concurrent PRNG}
     8396\label{f:ConcurrentPRNG}
     8397\end{figure}
     8398\end{itemize}
    81068399
    81078400
Note: See TracChangeset for help on using the changeset viewer.