Changeset 6b4a1bf for doc/user

Timestamp:

Mar 6, 2020, 2:22:49 PM (4 years ago)

Author:

Thierry Delisle <tdelisle@…>

Branches:

ADT, arm-eh, ast-experimental, enum, forall-pointer-decay, jacob/cs343-translation, jenkins-sandbox, master, new-ast, new-ast-unique-expr, pthread-emulation, qualifiedEnum

Children:

c4fd4ef, c88f0cf

Parents:

9c6f459 (diff), ca7949b (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:software/cfa/cfa-cc

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 : Thu Mar  5 12:09:42 2020
-%% Update Count     : 3885
+%% Last Modified On : Fri Mar  6 13:34:52 2020
+%% Update Count     : 3924
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -6621 +6621 @@
 An array may be filled, resized, or aligned.
 \end{description}
-\VRef[Table]{t:AllocationVersusCapabilities} shows allocation routines supporting different combinations of storage-management capabilities:
+\VRef[Table]{t:AllocationVersusCapabilities} shows allocation routines supporting different combinations of storage-management capabilities.
 \begin{table}
 \centering
+\begin{minipage}{0.75\textwidth}
 \begin{tabular}{@{}r|l|l|l|l|l@{}}
 \multicolumn{1}{c}{}&           & \multicolumn{1}{c|}{fill}     & resize        & alignment     & array \\
@@ -6631 +6632 @@
                 & ©realloc©                     & copy                  & yes           & no            & no    \\
                 & ©memalign©            & no                    & no            & yes           & no    \\
-                & ©aligned_alloc©       & no                    & no            & yes           & no    \\
+                & ©aligned_alloc©\footnote{Same as ©memalign© but size is an integral multiple of alignment, which is universally ignored.}
+                                                        & no                    & no            & yes           & no    \\
                 & ©posix_memalign©      & no                    & no            & yes           & no    \\
+                & ©valloc©                      & no                    & no            & yes (page size)& no   \\
+                & ©pvalloc©\footnote{Same as ©valloc© but rounds size to multiple of page size.}
+                                                        & no                    & no            & yes (page size)& no   \\
 \hline
 \CFA    & ©cmemalign©           & yes (0 only)  & no            & yes           & yes   \\
                 & ©realloc©                     & copy                  & yes           & yes           & no    \\
-                & ©alloc©                       & no                    & no            & no            & no    \\
-                & ©alloc©                       & copy                  & no/yes        & no            & yes   \\
-                & ©alloc©                       & no/copy/yes   & no/yes        & no            & yes   \\
-                & ©alloc_set©           & no/yes                & no            & yes           & yes   \\
-                & ©alloc_align©         & no/yes                & no            & yes           & yes   \\
-                & ©alloc_align_set©     & no/yes                & no            & yes           & yes   \\
+                & ©alloc©                       & no                    & yes           & no            & yes   \\
+                & ©alloc_set©           & yes                   & yes           & no            & yes   \\
+                & ©alloc_align©         & no                    & yes           & yes           & yes   \\
+                & ©alloc_align_set©     & yes                   & yes           & yes           & yes   \\
 \end{tabular}
+\end{minipage}
 \caption{Allocation Routines versus Storage-Management Capabilities}
 \label{t:AllocationVersusCapabilities}
 \end{table}
+
+\CFA memory management extends the type safety of all allocations by using the type of the left-hand-side type to determine the allocation size and return a matching type for the new storage.
+Type-safe allocation is provided for all C allocation routines and new \CFA allocation routines, \eg in
+\begin{cfa}
+int * ip = (int *)malloc( sizeof(int) );                §\C{// C}§
+int * ip = malloc();                                                    §\C{// \CFA type-safe version of C malloc}§
+int * ip = alloc();                                                             §\C{// \CFA type-safe uniform alloc}§
+\end{cfa}
+the latter two allocations determine the allocation size from the type of ©p© (©int©) and cast the pointer to the allocated storage to ©int *©.
+
+\CFA memory management extends allocation safety by implicitly honouring all alignment requirements, \eg in
+\begin{cfa}
+struct S { int i; } __attribute__(( aligned( 128 ) )); // cache-line alignment
+S * sp = malloc();                                                              §\C{// honour type alignment}§
+\end{cfa}
+the storage allocation is implicitly aligned to 128 rather than the default 16.
+The alignment check is performed at compile time so there is no runtime cost.
 
 \CFA memory management extends the resize capability with the notion of \newterm{sticky properties}.
@@ -6652 +6673 @@
 Without sticky properties it is dangerous to use ©realloc©, resulting in an idiom of manually performing the reallocation to maintain correctness.
 
+\CFA memory management extends allocation to support constructors for initialization of allocated storage, \eg in
+\begin{cfa}
+struct S { int i; };                                                    §\C{// cache-line aglinment}§
+void ?{}( S & s, int i ) { s.i = i; }
+// assume ?|? operator for printing an S
+
+S & sp = *®new®( 3 );                                                   §\C{// call constructor after allocation}§
+sout | sp.i;
+®delete®( &sp );
+
+S * spa = ®anew®( 10, 5 );                                              §\C{// allocate array and initialize each array element}§
+for ( i; 10 ) sout | spa[i] | nonl;
+sout | nl;
+®adelete®( 10, spa );
+\end{cfa}
+Allocation routines ©new©/©anew© allocate a variable/array and initialize storage using the allocated type's constructor.
+Note, the matching deallocation routines ©delete©/©adelete©.
 
 \leavevmode