Changes in doc/user/user.tex [421a287:55f5c59]

File:

• doc/user/user.tex (modified) (4 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 : Fri Jun  2 10:07:51 2017
-%% Update Count     : 2128
+%% Last Modified On : Tue May 30 11:42:47 2017
+%% Update Count     : 2097
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -185 +185 @@
 While the \CFA I/O looks similar to the \Index*[C++]{\CC{}} output style, there are important differences, such as automatic spacing between variables as in \Index*{Python} (see~\VRef{s:IOLibrary}).
 
-This document is a programmer reference-manual for the \CFA programming language.
-The manual covers the core features of the language and runtime-system, with simple examples illustrating syntax and semantics of each feature.
-The manual does not teach programming, i.e., how to combine the new constructs to build complex programs.
-A reader should already have an intermediate knowledge of control flow, data structures, and concurrency issues to understand the ideas presented as well as some experience programming in C/\CC.
+This document is a user manual for the \CFA programming language, targeted at \CFA programmers.
 Implementers may refer to the \CFA Programming Language Specification for details about the language syntax and semantics.
+In its current state, this document covers the intended core features of the language.
 Changes to the syntax and additional features are expected to be included in later revisions.
 
@@ -5166 +5164 @@
 \Celeven prescribes the following standard header-files~\cite[\S~7.1.2]{C11} and \CFA adds to this list:
 \begin{quote2}
-\lstset{deletekeywords={float}}
+\lstset{deletekeywords={float},deletekeywords=[2]{signal}}
 \begin{tabular}{@{}llll|l@{}}
 \multicolumn{4}{c|}{C11} & \multicolumn{1}{c}{\CFA}             \\
@@ -5244 +5242 @@
 \begin{description}
 \item[fill]
-after allocation the storage is filled with a specified character.
+after allocation the storage is or is not filled with a specified character.
 \item[resize]
 an existing allocation is decreased or increased in size.
 In either case, new storage may or may not be allocated and, if there is a new allocation, as much data from the existing allocation is copied.
-For an increase in storage size, new storage after the copied data may be filled.
+For an increase in storage size, new storage after the copied data may or may not be filled.
 \item[alignment]
 an allocation starts on a specified memory boundary, e.g., an address multiple of 64 or 128 for cache-line purposes.
 \item[array]
 the allocation size is scaled to the specified number of array elements.
-An array may be filled, resized, or aligned.
+An array may or not be filled, resized, or aligned.
 \end{description}
-The table shows allocation routines supporting different combinations of storage-management capabilities:
+
+The following table show the allocation routines supporting different combinations of storage-management capabilities:
 \begin{center}
-\begin{tabular}{@{}lr|l|l|l|l@{}}
-                &                                       & \multicolumn{1}{c|}{fill}     & resize        & alignment     & array \\
+\begin{tabular}{@{}r|l|l|l|l@{}}
+                                        & fill                          & resize        & alignment     & array \\
 \hline
-C               & ©malloc©                      & no                    & no            & no            & no    \\
-                & ©calloc©                      & yes (0 only)  & no            & no            & yes   \\
-                & ©realloc©                     & no/copy               & yes           & no            & no    \\
-                & ©memalign©            & no                    & no            & yes           & no    \\
-                & ©posix_memalign©      & no                    & no            & yes           & no    \\
-C11             & ©aligned_alloc©       & no                    & no            & yes           & no    \\
-\CFA    & ©alloc©                       & no/copy/yes   & no/yes        & no            & yes   \\
-                & ©align_alloc©         & no/yes                & no            & yes           & yes   \\
+©malloc©                        & no/yes                        & no/yes        & no            & no    \\
+©amalloc©                       & no/copy data/yes      & no/yes        & no            & yes   \\
+©calloc©                        & yes (0 only)          & no            & no            & yes   \\
+©realloc©                       & no/copy data          & yes           & no            & no    \\
+©memalign©                      & no/yes                        & no            & yes           & no    \\
+©amemalign©                     & no/yes                        & no            & yes           & yes   \\
+©align_alloc©           & no                            & no            & yes           & no    \\
+©posix_memalign©        & no                            & no            & yes           & no    \\
 \end{tabular}
 \end{center}
+% When ©amalloc© resizes and fills, the space after the copied data from the source is set to the fill character.
 It is impossible to resize with alignment because the underlying ©realloc© allocates storage if more space is needed, and it does not honour alignment from the original allocation.
 
 \leavevmode
 \begin{cfa}[aboveskip=0pt,belowskip=0pt]
-// C unsafe allocation
-extern "C" {
-void * mallac( size_t size );§\indexc{memset}§
-void * calloc( size_t dim, size_t size );§\indexc{calloc}§
-void * realloc( void * ptr, size_t size );§\indexc{realloc}§
-void * memalign( size_t align, size_t size );§\indexc{memalign}§
-int posix_memalign( void ** ptr, size_t align, size_t size );§\indexc{posix_memalign}§
-}
-
-// §\CFA§ safe equivalents, i.e., implicit size specification
-forall( dtype T | sized(T) ) T * malloc( void );
-forall( dtype T | sized(T) ) T * calloc( size_t dim );
-forall( dtype T | sized(T) ) T * realloc( T * ptr, size_t size );
-forall( dtype T | sized(T) ) T * memalign( size_t align );
-forall( dtype T | sized(T) ) T * aligned_alloc( size_t align );
-forall( dtype T | sized(T) ) int posix_memalign( T ** ptr, size_t align );
-
-// §\CFA§ safe general allocation, fill, resize, array
-forall( dtype T | sized(T) ) T * alloc( void );§\indexc{alloc}§
-forall( dtype T | sized(T) ) T * alloc( char fill );
-forall( dtype T | sized(T) ) T * alloc( size_t dim );
-forall( dtype T | sized(T) ) T * alloc( size_t dim, char fill );
-forall( dtype T | sized(T) ) T * alloc( T ptr[], size_t dim );
-forall( dtype T | sized(T) ) T * alloc( T ptr[], size_t dim, char fill );
-
-// §\CFA§ safe general allocation, align, fill, array
-forall( dtype T | sized(T) ) T * align_alloc( size_t align );
-forall( dtype T | sized(T) ) T * align_alloc( size_t align, char fill );
-forall( dtype T | sized(T) ) T * align_alloc( size_t align, size_t dim );
-forall( dtype T | sized(T) ) T * align_alloc( size_t align, size_t dim, char fill );
-
-// C unsafe initialization/copy
-extern "C" {
-void * memset( void * dest, int c, size_t size );
-void * memcpy( void * dest, const void * src, size_t size );
-}
-
-// §\CFA§ safe initialization/copy
+// allocation, non-array types
+forall( dtype T | sized(T) ) T * malloc( void );§\indexc{malloc}§
+forall( dtype T | sized(T) ) T * malloc( char fill );
+
+// allocation, array types
+forall( dtype T | sized(T) ) T * calloc( size_t dim );§\indexc{cmalloc}§
+forall( dtype T | sized(T) ) T * amalloc( size_t dim );§\indexc{amalloc}§  // alternate name for calloc
+forall( dtype T | sized(T) ) T * amalloc( size_t dim, char fill );
+
+// resize, non-array types
+forall( dtype T | sized(T) ) T * realloc( T * ptr, size_t size );§\indexc{realloc}§
+forall( dtype T | sized(T) ) T * realloc( T * ptr, size_t size, char fill );
+forall( dtype T | sized(T) ) T * malloc( T * ptr, size_t size );  // alternate name for realloc
+forall( dtype T | sized(T) ) T * malloc( T * ptr, size_t size, char fill );
+
+// resize, array types
+forall( dtype T | sized(T) ) T * amalloc( T * ptr, size_t dim );
+forall( dtype T | sized(T) ) T * amalloc( T * ptr, size_t dim, char fill );
+
+// alignment, non-array types
+forall( dtype T | sized(T) ) T * memalign( size_t alignment );§\indexc{memalign}§
+forall( dtype T | sized(T) ) T * memalign( size_t alignment, char fill );
+forall( dtype T | sized(T) ) T * aligned_alloc( size_t alignment );§\indexc{aligned_alloc}§
+forall( dtype T | sized(T) ) int posix_memalign( T ** ptr, size_t alignment );§\indexc{posix_memalign}§
+
+// alignment, array types
+forall( dtype T | sized(T) ) T * amemalign( size_t alignment, size_t dim );§\indexc{amemalign}§
+forall( dtype T | sized(T) ) T * amemalign( size_t alignment, size_t dim, char fill );
+
+// data, non-array types
 forall( dtype T | sized(T) ) T * memset( T * dest, char c );§\indexc{memset}§
 forall( dtype T | sized(T) ) T * memcpy( T * dest, const T * src );§\indexc{memcpy}§
 
-// §\CFA§ safe initialization/copy array
-forall( dtype T | sized(T) ) T * memset( T dest[], size_t dim, char c );
-forall( dtype T | sized(T) ) T * memcpy( T dest[], const T src[], size_t dim );
-
-// §\CFA§ allocation/deallocation and constructor/destructor
-forall( dtype T | sized(T), ttype Params | { void ?{}( T *, Params ); } ) T * new( Params p );§\indexc{new}§
+// data, array types
+forall( dtype T | sized(T) ) T * amemset( T * dest, size_t dim, char c );§\indexc{amemset}§
+forall( dtype T | sized(T) ) T * amemcpy( T * dest, const T * src, size_t dim );§\indexc{amemcpy}§
+
+// allocation/deallocation and constructor/destructor
+forall( dtype T, ttype Params | sized(T) | { void ?{}(T *, Params); } ) T * new( Params p );§\indexc{new}§
 forall( dtype T | { void ^?{}( T * ); } ) void delete( T * ptr );§\indexc{delete}§
-forall( dtype T, ttype Params | { void ^?{}( T * ); void delete( Params ); } )
-  void delete( T * ptr, Params rest );
-
-// §\CFA§ allocation/deallocation and constructor/destructor, array
-forall( dtype T | sized(T), ttype Params | { void ?{}( T *, Params ); } ) T * anew( size_t dim, Params p );§\indexc{anew}§
-forall( dtype T | sized(T) | { void ^?{}( T * ); } ) void adelete( size_t dim, T arr[] );§\indexc{adelete}§
-forall( dtype T | sized(T) | { void ^?{}( T * ); }, ttype Params | { void adelete( Params ); } )
-  void adelete( size_t dim, T arr[], Params rest );
+forall( dtype T, ttype Params | { void ^?{}( T * ); void delete(Params); } ) void delete( T * ptr, Params rest );
 \end{cfa}