Changes in doc/user/user.tex [4ab767a:9b71679]

File:

• doc/user/user.tex (modified) (23 diffs)

doc/user/user.tex

@@ -11 +11 @@
 %% Created On       : Wed Apr  6 14:53:29 2016
 %% Last Modified By : Peter A. Buhr
-%% Last Modified On : Sat May  8 08:51:33 2021
-%% Update Count     : 5062
+%% Last Modified On : Sun Apr 25 19:03:03 2021
+%% Update Count     : 4951
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -65 +65 @@
 % keyword escape ¶...¶ (pilcrow symbol) emacs: C-q M-^
 % math escape $...$ (dollar symbol)
-\usepackage{common}                                                                             % common CFA document macros
-%\input{common}                                                                                 % common CFA document macros
+\input{common}                                          % common CFA document macros
 \setlength{\gcolumnposn}{3in}
 \CFAStyle                                                                                               % use default CFA format-style
@@ -586 +585 @@
 For example, the octal ©0© or hexadecimal ©0x© prefix may end with an underscore ©0_377© or ©0x_ff©;
 the exponent infix ©E© may start or end with an underscore ©1.0_E10©, ©1.0E_10© or ©1.0_E_10©;
-the type suffixes ©U©, ©L©, \etc may start with an underscore ©1_U©, ©1_ll© or ©1.0E10_f©.
+the type suffixes ©U©, ©L©, etc. may start with an underscore ©1_U©, ©1_ll© or ©1.0E10_f©.
 \end{enumerate}
 It is significantly easier to read and enter long constants when they are broken up into smaller groupings (many cultures use comma and/or period among digits for the same purpose).
@@ -1571 +1570 @@
 \end{cquote}
 
-All type qualifiers, \eg ©const©, ©volatile©, \etc, are used in the normal way with the new declarations and also appear left to right, \eg:
+All type qualifiers, \eg ©const©, ©volatile©, etc., are used in the normal way with the new declarations and also appear left to right, \eg:
 \begin{cquote}
 \begin{tabular}{@{}l@{\hspace{1em}}l@{\hspace{1em}}l@{}}
@@ -1591 +1590 @@
 \end{tabular}
 \end{cquote}
-All declaration qualifiers, \eg ©extern©, ©static©, \etc, are used in the normal way with the new declarations but can only appear at the start of a \CFA routine declaration,\footnote{\label{StorageClassSpecifier}
+All declaration qualifiers, \eg ©extern©, ©static©, etc., are used in the normal way with the new declarations but can only appear at the start of a \CFA routine declaration,\footnote{\label{StorageClassSpecifier}
 The placement of a storage-class specifier other than at the beginning of the declaration specifiers in a declaration is an obsolescent feature.~\cite[\S~6.11.5(1)]{C11}} \eg:
 \begin{cquote}
@@ -3148 +3147 @@
 also, it is unnecessary to specify all the fields of a struct in a multiple record-field tuple.
 
-Since tuple-index expressions are a form of member-access expression, it is possible to use tuple-index expressions in conjunction with member-access expressions to restructure a tuple (\eg, rearrange components, drop components, duplicate components, \etc).
+Since tuple-index expressions are a form of member-access expression, it is possible to use tuple-index expressions in conjunction with member-access expressions to restructure a tuple (\eg, rearrange components, drop components, duplicate components, etc.).
 \begin{cfa}
 [ int, int, long, double ] x;
@@ -3313 +3312 @@
 
 \section{Tuples}
-\label{tuples}
 
 In C and \CFA, lists of elements appear in several contexts, such as the parameter list for a routine call.
@@ -3422 +3420 @@
 
 \subsection{Tuple Coercions}
-\label{tuple coercions}\label{coercions!tuple}
 
 There are four coercions that can be performed on tuples and tuple variables: closing, opening, flattening and structuring.
@@ -3467 +3464 @@
 
 \subsection{Mass Assignment}
-\label{mass assignment}\label{assignment!mass}
 
 \CFA permits assignment to several variables at once using mass assignment~\cite{CLU}.
@@ -3508 +3504 @@
 
 \subsection{Multiple Assignment}
-\label{multiple assignment}\label{assignment!multiple}
 
 \CFA also supports the assignment of several values at once, known as multiple assignment~\cite{CLU,Galletly96}.
@@ -3550 +3545 @@
 
 \subsection{Cascade Assignment}
-\index{cascade assignment}\index{assignment!cascade}
 
 As in C, \CFA mass and multiple assignments can be cascaded, producing cascade assignment.
@@ -3570 +3564 @@
 \section{Stream I/O Library}
 \label{s:StreamIOLibrary}
-\index{input}\index{output}
-\index{stream library}\index{library!stream}
+\index{input/output stream library}
+\index{stream library}
 
 The goal of \CFA stream input/output (I/O) is to simplify the common cases\index{I/O!common case}, while fully supporting polymorphism and user defined types in a consistent way.
 Stream I/O can be implicitly or explicitly formatted.
-Implicit formatting means \CFA selects the output or input format for values that matches the variable's type.
+Implicit formatting means \CFA selects the output or input format for values that match with the type of a variable.
 Explicit formatting means additional information is specified to augment how an output or input of value is interpreted.
-\CFA formatting incorporates ideas from C ©printf©, \CC ©stream© manipulators, and Python implicit spacing and newline.
+\CFA formatting is a cross between C ©printf© and \CC ©cout© manipulators, and Python implicit spacing and newline.
 Specifically:
 \begin{itemize}
@@ -3590 +3584 @@
 Hence, it is common programming practice to toggle manipulators on and then back to the default to prevent downstream side-effects.
 Without this programming style, errors occur when moving prints, as manipulator effects incorrectly flow into the new location.
-Furthermore, to guarantee no side-effects, manipulator values must be saved and restored across function calls.
-\item
-\CFA has more sophisticated implicit value spacing than Python, plus implicit newline at the end of a print.
+(To guarantee no side-effects, manipulator values must be saved and restored across function calls.)
+\item
+\CFA has more sophisticated implicit spacing between values than Python, plus implicit newline at the end of a print.
 \end{itemize}
-
-The standard polymorphic I/Os stream are ©stdin©/©sin© (input), ©stdout©/©sout© and ©stderr©/©serr© (output) (like C++ ©cin©/©cout©/©cerr©).
-Polymorphic streams ©exit© and ©abort© provide implicit program termination without and with generating a stack trace and core file.
-Stream ©exit© implicitly returns ©EXIT_FAILURE© to the shell.
-\begin{cfa}
-®exit®   | "x (" | x | ") negative value."; // terminate and return EXIT_FAILURE to shell
-®abort® | "x (" | x | ") negative value."; // terminate and generate stack trace and core file
-\end{cfa}
-Note, \CFA stream variables ©stdin©, ©stdout©, ©stderr©, ©exit©, and ©abort© overload C variables ©stdin©, ©stdout©, ©stderr©, and functions ©exit© and ©abort©, respectively.
 The \CFA header file for the I/O library is \Indexc{fstream.hfa}.
-
-
-\subsection{Basic I/O}
 
 For implicit formatted output, the common case is printing a series of variables separated by whitespace.
@@ -3619 +3601 @@
 \begin{cfa}
 
-cout  <<  x  ®<< " "®  <<  y  ®<< " "®  <<  z  << endl;
+cout << x ®<< " "® << y ®<< " "® << z << endl;
 \end{cfa}
 &
@@ -3671 +3653 @@
 \end{tabular}
 \end{cquote}
-Input and output use a uniform operator, ©|©, rather than \CC's ©>>© and ©<<© input/output operators.
+Input and output use a uniform operator, ©|©, rather than separate operators, as in ©>>© and ©<<© for \CC.
 There is a weak similarity between the \CFA logical-or operator and the \Index{Shell pipe-operator} for moving data, where data flows in the correct direction for input but the opposite direction for output.
 
@@ -3716 +3698 @@
 \end{cquote}
 
-\VRef[Figure]{f:CFACommand-LineProcessing} shows idiomatic \CFA command-line processing and copying an input file to an output file.
-Note, a stream variable may be copied because it is a reference to an underlying stream data-structures.
-All I/O errors are handles as exceptions, but end-of-file is not an exception as C programmers are use to explicitly checking for it.
-
-\begin{figure}
-\begin{cfa}
-#include ®<fstream.hfa>®
-
-int main( int argc, char * argv[] ) {
-        ®ifstream® in  = stdin;                                 $\C{// copy default files}$
-        ®ofstream® out = stdout;
-
-        try {
-                choose ( argc ) {
-                  case 2, 3:
-                        ®open®( in, argv[1] );                  $\C{// open input file first as output creates file}$
-                        if ( argc == 3 ) ®open®( out, argv[2] ); $\C{// do not create output unless input opens}$
-                  case 1: ;                                                     $\C{// use default files}$
-                  default:
-                        ®exit® | "Usage" | argv[0] | "[ input-file (default stdin) "
-                                   "[ output-file (default stdout) ] ]";
-                } // choose
-        } catch( ®Open_Failure® * ex; ex->istream == &in ) {
-                ®exit® | "Unable to open input file" | argv[1];
-        } catch( ®Open_Failure® * ex; ex->ostream == &out ) {
-                ®close®( in );                                          $\C{// optional}$
-                ®exit® | "Unable to open output file" | argv[2];
-        } // try
-
-        out | nlOff;                                                    $\C{// turn off auto newline}$
-        in | nlOn;                                                              $\C{// turn on reading newline}$
-        char ch;
-        for () {                                                                $\C{// read/write characters}$
-                in | ch;
-          if ( eof( in ) ) break;                               $\C{// eof ?}$
-                out | ch;
-        } // for
-} // main
-\end{cfa}
-\caption{\CFA Command-Line Processing}
-\label{f:CFACommand-LineProcessing}
-\end{figure}
-
-\VRef[Figure]{f:StreamFunctions} shows the stream operations.
-\begin{itemize}[topsep=4pt,itemsep=2pt,parsep=0pt]
-\item
-\Indexc{fail} tests the stream error-indicator, returning nonzero if it is set.
-\item
-\Indexc{clear} resets the stream error-indicator.
-\item
-\Indexc{flush} (©ofstream© only) causes any unwritten data for a stream to be written to the file.
-\item
-\Indexc{eof} (©ifstream© only) tests the end-of-file indicator for the stream pointed to by stream.
-Returns true if the end-of-file indicator is set, otherwise false.
-\item
-\Indexc{open} binds the file with ©name© to a stream accessed with ©mode© (see ©fopen©).
-\item
-\Indexc{close} flushes the stream and closes the file.
-\item
-\Indexc{write} (©ofstream© only) write ©size© bytes to the stream.
-The bytes are written lazily to file when internal buffers fill.
-Eager buffer writes are done with ©flush©
-\item
-\Indexc{read} (©ifstream© only) read ©size© bytes to the stream.
-\item
-\Indexc{ungetc} (©ifstream© only) pushes the character back to the input stream.
-Pushed-back characters returned by subsequent reads in the reverse order of pushing.
-\end{itemize}
-The constructor functions:
-\begin{itemize}[topsep=4pt,itemsep=2pt,parsep=0pt]
-\item
-create an unbound stream, which is subsequently bound to a file with ©open©.
-\item
-create a bound stream to the associated file with given ©mode©.
-\end{itemize}
-The destructor closes the stream.
-
-\begin{figure}
-\begin{cfa}
-// *********************************** ofstream ***********************************
-
-bool fail( ofstream & );$\indexc{fail}\index{ofstream@©ofstream©!©fail©}$
-void clear( ofstream & );$\indexc{clear}\index{ofstream@©ofstream©!©clear©}$
-int flush( ofstream & );$\indexc{flush}\index{ofstream@©ofstream©!©flush©}$
-void open( ofstream &, const char name[], const char mode[] = "w" );$\indexc{open}\index{ofstream@©ofstream©!©open©}$
-void close( ofstream & );$\indexc{close}\index{ofstream@©ofstream©!©close©}$
-ofstream & write( ofstream &, const char data[], size_t size );$\indexc{write}\index{ofstream@©ofstream©!©write©}$
-
-void ?{}( ofstream & );$\index{ofstream@©ofstream©!©?{}©}$
-void ?{}( ofstream &, const char name[], const char mode[] = "w" );
-void ^?{}( ofstream & );$\index{ofstream@©ofstream©!©^?{}©}$
-
-// *********************************** ifstream ***********************************
-
-bool fail( ifstream & is );$\indexc{fail}\index{ifstream@©ifstream©!©fail©}$
-void clear( ifstream & );$\indexc{clear}\index{ifstream@©ifstream©!©clear©}$
-bool eof( ifstream & is );$\indexc{eof}\index{ifstream@©ifstream©!©eof©}$
-void open( ifstream & is, const char name[], const char mode[] = "r" );$\indexc{open}\index{ifstream@©ifstream©!©open©}$
-void close( ifstream & is );$\indexc{close}\index{ifstream@©ifstream©!©close©}$
-ifstream & read( ifstream & is, char data[], size_t size );$\indexc{read}\index{ifstream@©ifstream©!©read©}$
-ifstream & ungetc( ifstream & is, char c );$\indexc{unget}\index{ifstream@©ifstream©!©unget©}$
-
-void ?{}( ifstream & is );$\index{ifstream@©ifstream©!©?{}©}$
-void ?{}( ifstream & is, const char name[], const char mode[] = "r" );
-void ^?{}( ifstream & is );$\index{ifstream@©ifstream©!©^?{}©}$
-\end{cfa}
-\caption{Stream Functions}
-\label{f:StreamFunctions}
-\end{figure}
 
 
@@ -3973 +3846 @@
 
 \item
-\Indexc{sepOn}\index{manipulator!sepOn@©sepOn©} and \Indexc{sepOff}\index{manipulator!sepOff@©sepOff©} toggle printing the separator with respect to the next printed item, and then return to the global separator setting.
+\Indexc{sepOn}\index{manipulator!sepOn@©sepOn©} and \Indexc{sepOff}\index{manipulator!sepOff@©sepOff©} toggle printing the separator with respect to the next printed item, and then return to the global seperator setting.
 \begin{cfa}[belowskip=0pt]
 sout | 1 | sepOff | 2 | 3; $\C{// turn off implicit separator for the next item}$
@@ -4157 +4030 @@
 sout | wd( 4, "ab" ) | wd( 3, "ab" ) | wd( 2, "ab" );
 \end{cfa}
-\begin{cfa}[showspaces=true,aboveskip=0pt]
+\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
 ®  ®34 ® ®34 34
 ®  ®4.000000 ® ®4.000000 4.000000
@@ -4505 +4378 @@
 \end{cfa}
 
-
-\section{String Stream}
-
-All the stream formatting capabilities are available to format text to/from a C string rather than to a stream file.
-\VRef[Figure]{f:StringStreamProcessing} shows writing (output) and reading (input) from a C string.
-\begin{figure}
-\begin{cfa}
-#include <fstream.hfa>
-#include <strstream.hfa>
-
-int main() {
-        enum { size = 256 };
-        char buf[size]; $\C{// output buffer}$
-        ®ostrstream osstr = { buf, size };® $\C{// bind output buffer/size}$
-        int i = 3, j = 5, k = 7;
-        double x = 12345678.9, y = 98765.4321e-11;
-
-        osstr | i | hex(j) | wd(10, k) | sci(x) | unit(eng(y)); $\C{// same lines of output}$
-        write( osstr );
-        printf( "%s", buf );
-        sout | i | hex(j) | wd(10, k) | sci(x) | unit(eng(y));
-
-        char buf2[] = "12 14 15 3.5 7e4"; $\C{// input buffer}$
-        ®istrstream isstr = { buf2 };®
-        isstr | i | j | k | x | y;
-        sout | i | j | k | x | y;
-}
-\end{cfa}
-\caption{String Stream Processing}
-\label{f:StringStreamProcessing}
-\end{figure}
-
-\VRef[Figure]{f:StringStreamFunctions} shows the string stream operations.
-\begin{itemize}[topsep=4pt,itemsep=2pt,parsep=0pt]
-\item
-\Indexc{write} (©ostrstream© only) writes all the buffered characters to the specified stream (©stdout© default).
-\end{itemize}
-The constructor functions:
-\begin{itemize}[topsep=4pt,itemsep=2pt,parsep=0pt]
-\item
-create a bound stream to a write buffer (©ostrstream©) of ©size© or a read buffer (©istrstream©) containing a C string terminated with ©'\0'©.
-\end{itemize}
-
-\begin{figure}
-\begin{cfa}
-// *********************************** ostrstream ***********************************
-
-ostrstream & write( ostrstream & os, FILE * stream = stdout );
-
-void ?{}( ostrstream &, char buf[], size_t size );
-
-// *********************************** istrstream ***********************************
-
-void ?{}( istrstream & is, char buf[] );
-\end{cfa}
-\caption{String Stream Functions}
-\label{f:StringStreamFunctions}
-\end{figure}
+\Textbf{WARNING:} ©printf©\index{printf@©printf©}, ©scanf©\index{scanf@©scanf©} and their derivatives are unsafe when used with user-level threading, as in \CFA.
+These stream routines use kernel-thread locking (©futex©\index{futex@©futex©}), which block kernel threads, to prevent interleaving of I/O.
+However, the following simple example illustrates how a deadlock can occur (other complex scenarios are possible).
+Assume a single kernel thread and two user-level threads calling ©printf©.
+One user-level thread acquires the I/O lock and is time-sliced while performing ©printf©.
+The other user-level thread then starts execution, calls ©printf©, and blocks the only kernel thread because it cannot acquire the I/O lock.
+It does not help if the kernel lock is multiple acquisition, \ie, the lock owner can acquire it multiple times, because it then results in two user threads in the ©printf© critical section, corrupting the stream.
 
 
@@ -5660 +5482 @@
 \item
 Package: a container to organize modules for distribution; It has attributes like name, author,
-version, dependences, \etc.
-\item
-Project: a working set for a \CFA project; It has attributes like name, author, version, dependences, \etc.
+version, dependences, etc.
+\item
+Project: a working set for a \CFA project; It has attributes like name, author, version, dependences, etc.
 \end{itemize}
 
@@ -5799 +5621 @@
 
 A package is defined by putting a project description file, Do.prj, with one or more modules into a directory.
-This project description file contains the package's meta data, including package name, author, version, dependences, \etc.
+This project description file contains the package's meta data, including package name, author, version, dependences, etc.
 It should be in the root of the package directory.
 
@@ -5856 +5678 @@
 Module: a container to organize a set of related types and methods; It has a module name, and several interfaces visible from outside
 \item
-Package: a container to organize modules for distribution; It has attributes like name, author, version, dependences, \etc.
-\item
-Project: a working set for a \CFA project; It has attributes like name, author, version, dependences, \etc.
+Package: a container to organize modules for distribution; It has attributes like name, author, version, dependences, etc.
+\item
+Project: a working set for a \CFA project; It has attributes like name, author, version, dependences, etc.
 \end{itemize}
 
@@ -8289 +8111 @@
 \begin{cquote}
 \begin{tabular}{@{}l@{\hspace{\parindentlnth}}|@{\hspace{\parindentlnth}}l@{}}
-\multicolumn{1}{@{}c|@{\hspace{\parindentlnth}}}{\textbf{\CFA}} & \multicolumn{1}{@{\hspace{\parindentlnth}}c@{}}{\textbf{C}}   \\
+\multicolumn{1}{@{}c|@{\hspace{\parindentlnth}}}{\textbf{\CFA}} & \multicolumn{1}{@{\hspace{\parindentlnth}}c}{\textbf{C}@{}}   \\
 \hline
 \begin{cfa}
-#include <gmp.hfa>$\indexc{gmp}$
+#include <gmp>$\indexc{gmp}$
 int main( void ) {
         sout | "Factorial Numbers";