Changeset d4d4ac8 for doc/user

Timestamp:

Oct 10, 2021, 5:11:28 PM (3 years ago)

Author:

Peter A. Buhr <pabuhr@…>

Branches:

ADT, ast-experimental, enum, forall-pointer-decay, master, pthread-emulation, qualifiedEnum

Children:

a73c16e

Parents:

321a1b15

Message:

remove discussion of I/O acquire and replace with mutex statement, add section on string stream

File:

• doc/user/user.tex (modified) (7 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 : Mon May 31 09:03:34 2021
-%% Update Count     : 5071
+%% Last Modified On : Sun Oct 10 12:45:00 2021
+%% Update Count     : 5095
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -4444 +4444 @@
 \CFA provides a fine-grained solution where a \Index{recursive lock} is acquired and released indirectly via a manipulator ©acquire© or instantiating an \Index{RAII} type specific for the kind of stream: ©osacquire©\index{ostream@©ostream©!osacquire@©osacquire©} for output streams and ©isacquire©\index{isacquire@©isacquire©}\index{istream@©istream©!isacquire@©isacquire©} for input streams.
 
-The common usage is manipulator ©acquire©\index{ostream@©ostream©!acquire@©acquire©} to lock a stream during a single cascaded I/O expression, with the manipulator appearing as the first item in a cascade list, \eg:
-\begin{cfa}
-$\emph{thread\(_1\)}$ : sout | ®acquire® | "abc " | "def ";   // manipulator
-$\emph{thread\(_2\)}$ : sout | ®acquire® | "uvw " | "xyz ";
+The 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:
+\begin{cfa}
+$\emph{thread\(_1\)}$ : ®mutex()® sout | "abc " | "def ";
+$\emph{thread\(_2\)}$ : ®mutex()® sout | "uvw " | "xyz ";
 \end{cfa}
 Now, the order of the thread execution is still non-deterministic, but the output is constrained to two possible lines in either order.
@@ -4466 +4466 @@
 In summary, the stream lock is acquired by the ©acquire© manipulator and implicitly released at the end of the cascaded I/O expression ensuring all operations in the expression occur atomically.
 
-To lock a stream across multiple I/O operations, an object of type ©osacquire© or ©isacquire© is declared to implicitly acquire/release the stream lock providing mutual exclusion for the object's duration, \eg:
-\begin{cfa}
-{       // acquire sout for block duration
-        ®osacquire® acq = { sout };                             $\C{// named stream locker}$
+To lock a stream across multiple I/O operations, he long form of the mutex statement is used, \eg:
+\begin{cfa}
+®mutex( sout )® {
         sout | 1;
-        sout | ®acquire® | 2 | 3;                               $\C{// unnecessary, but ok to acquire and release again}$
+        ®mutex() sout® | 2 | 3;                         $\C{// unnecessary, but ok because of recursive lock}$
         sout | 4;
-}       // implicitly release the lock when "acq" is deallocated
-\end{cfa}
-Note, the unnecessary ©acquire© manipulator works because the recursive stream-lock can be acquired/released multiple times by the owner thread.
+} // implicitly release sout lock
+\end{cfa}
+Note, the unnecessary ©mutex© in the middle of the mutex statement, works because the recursive stream-lock can be acquired/released multiple times by the owner thread.
 Hence, calls to functions that also acquire a stream lock for their output do not result in \Index{deadlock}.
 
 The previous values written by threads 1 and 2 can be read in concurrently:
 \begin{cfa}
-{       // acquire sin lock for block duration
-        ®isacquire acq = { sin };®                              $\C{// named stream locker}$
+®mutex( sin )® {
         int x, y, z, w;
         sin | x;
-        sin | ®acquire® | y | z;                                $\C{// unnecessary, but ok to acquire and release again}$
+        ®mutex() sin® | y | z;                          $\C{// unnecessary, but ok because of recursive lock}$
         sin | w;
-}       // implicitly release the lock when "acq" is deallocated
+} // implicitly release sin lock
 \end{cfa}
 Again, the order of the reading threads is non-deterministic.
@@ -4493 +4491 @@
 \Textbf{WARNING:} The general problem of \Index{nested locking} can occur if routines are called in an I/O sequence that block, \eg:
 \begin{cfa}
-sout | ®acquire® | "data:" | rtn( mon );        $\C{// mutex call on monitor}$
+®mutex() sout® | "data:" | rtn( mon );  $\C{// mutex call on monitor}$
 \end{cfa}
 If 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.
@@ -4500 +4498 @@
 \begin{cfa}
 int ®data® = rtn( mon );
-sout | acquire | "data:" | ®data®;
+mutex() sout | "data:" | ®data®;
 \end{cfa}
 
@@ -4506 +4504 @@
 \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.
+The stream types ©ostrstream© and ©istrstream© provide all the stream formatting capabilities to/from a C string rather than a stream file.
+\VRef[Figure]{f:StringStreamProcessing} shows writing (output) to and reading (input) from a C string.
+The only string stream operations different from a file stream are:
+\begin{itemize}[topsep=4pt,itemsep=2pt,parsep=0pt]
+\item
+constructors to create a stream that writes to a write buffer (©ostrstream©) of ©size©, or reads from a read buffer (©istrstream©) containing a C string terminated with ©'\0'©.
+\begin{cfa}
+void ?{}( ostrstream &, char buf[], size_t size );
+void ?{}( istrstream & is, char buf[] );
+\end{cfa}
+\item
+\Indexc{write} (©ostrstream© only) writes all the buffered characters to the specified stream (©stdout© default).
+\begin{cfa}
+ostrstream & write( ostrstream & os, FILE * stream = stdout );
+\end{cfa}
+There is no ©read© for ©istrstream©.
+\end{itemize}
+
 \begin{figure}
 \begin{cfa}
@@ -4520 +4534 @@
         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}$
+        osstr | i | hex(j) | wd(10, k) | sci(x) | unit(eng(y)) | "abc";
+        write( osstr ); $\C{// write string to stdout}$
+        printf( "%s", buf ); $\C{// same lines of output}$
+        sout | i | hex(j) | wd(10, k) | sci(x) | unit(eng(y)) | "abc";
+
+        char buf2[] = "12 14 15 3.5 7e4 abc"; $\C{// input buffer}$
         ®istrstream isstr = { buf2 };®
-        isstr | i | j | k | x | y;
-        sout | i | j | k | x | y;
-}
+        char s[10];
+        isstr | i | j | k | x | y | s;
+        sout  | i | j | k | x | y | s;
+}
+
+3 0x5          7 1.234568e+07 987.654n abc
+3 0x5          7 1.234568e+07 987.654n abc
+3 0x5          7 1.234568e+07 987.654n abc
+12 14 15 3.5 70000. abc
 \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}
-
 
 \begin{comment}