Changeset f94ca7e for doc/user

Timestamp:

Jun 2, 2017, 5:42:10 PM (8 years ago)

Author:

Rob Schluntz <rschlunt@…>

Branches:

ADT, aaron-thesis, arm-eh, ast-experimental, cleanup-dtors, deferred_resn, demangler, enum, forall-pointer-decay, jacob/cs343-translation, jenkins-sandbox, master, new-ast, new-ast-unique-expr, new-env, no_list, persistent-indexer, pthread-emulation, qualifiedEnum, resolv-new, with_gc

Children:

0db6fc0

Parents:

2164637 (diff), 2c6c893 (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.

Message:

Merge branch 'master' of plg.uwaterloo.ca:/u/cforall/software/cfa/cfa-cc

File:

• doc/user/user.tex (modified) (3 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 : Tue May 30 11:45:46 2017
-%% Update Count     : 2098
+%% Last Modified On : Fri Jun  2 10:07:51 2017
+%% Update Count     : 2128
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -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 user manual for the \CFA programming language, targeted at \CFA programmers.
+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.
 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.
 
@@ -5242 +5244 @@
 \begin{description}
 \item[fill]
-after allocation the storage is or is not filled with a specified character.
+after allocation the storage is 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 or may not be filled.
+For an increase in storage size, new storage after the copied data may 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 or not be filled, resized, or aligned.
+An array may be filled, resized, or aligned.
 \end{description}
-
-The following table show the allocation routines supporting different combinations of storage-management capabilities:
+The table shows allocation routines supporting different combinations of storage-management capabilities:
 \begin{center}
-\begin{tabular}{@{}r|l|l|l|l@{}}
-                                        & fill                          & resize        & alignment     & array \\
+\begin{tabular}{@{}lr|l|l|l|l@{}}
+                &                                       & \multicolumn{1}{c|}{fill}     & resize        & alignment     & array \\
 \hline
-©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    \\
+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   \\
 \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]
-// 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
+// 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
 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}§
 
-// 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}§
+// §\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}§
 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 );
+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 );
 \end{cfa}