# Changeset cc28780 for doc

Ignore:
Timestamp:
Nov 8, 2021, 5:28:21 PM (6 months ago)
Branches:
enum, forall-pointer-decay, master
Children:
36a05d7
Parents:
949339b (diff), 5ee153d (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

Location:
doc
Files:
1 deleted
8 edited

Unmodified
Removed
• ## doc/theses/mubeen_zulfiqar_MMath/allocator.tex

 r949339b \end{itemize} The new features added to uHeapLmmm (incl. @malloc_size@ routine) The new features added to uHeapLmmm (incl. @malloc\_size@ routine) \CFA alloc interface with examples. \begin{itemize} \item We added a few more features and routines to the allocator's C interface that can make the allocator more usable to the programmers. THese features will programmer more control on the dynamic memory allocation. \subsubsection void * aalloc( size_t dim, size_t elemSize ) \subsubsection void * aalloc( size\_t dim, size\_t elemSize ) aalloc is an extension of malloc. It allows programmer to allocate a dynamic array of objects without calculating the total size of array explicitly. The only alternate of this routine in the other allocators is calloc but calloc also fills the dynamic memory with 0 which makes it slower for a programmer who only wants to dynamically allocate an array of objects without filling it with 0. \paragraph{Usage} aalloc takes two parameters. \begin{itemize} \item It returns address of dynamic object allocatoed on heap that can contain dim number of objects of the size elemSize. On failure, it returns NULL pointer. \subsubsection void * resize( void * oaddr, size_t size ) \subsubsection void * resize( void * oaddr, size\_t size ) resize is an extension of relloc. It allows programmer to reuse a cuurently allocated dynamic object with a new size requirement. Its alternate in the other allocators is realloc but relloc also copy the data in old object to the new object which makes it slower for the programmer who only wants to reuse an old dynamic object for a new size requirement but does not want to preserve the data in the old object to the new object. \paragraph{Usage} resize takes two parameters. \begin{itemize} \item It returns an object that is of the size given but it does not preserve the data in the old object. On failure, it returns NULL pointer. \subsubsection void * resize( void * oaddr, size_t nalign, size_t size ) \subsubsection void * resize( void * oaddr, size\_t nalign, size\_t size ) This resize is an extension of the above resize (FIX ME: cite above resize). In addition to resizing the size of of an old object, it can also realign the old object to a new alignment requirement. \paragraph{Usage} This resize takes three parameters. It takes an additional parameter of nalign as compared to the above resize (FIX ME: cite above resize). \begin{itemize} \item It returns an object with the size and alignment given in the parameters. On failure, it returns a NULL pointer. \subsubsection void * amemalign( size_t alignment, size_t dim, size_t elemSize ) \subsubsection void * amemalign( size\_t alignment, size\_t dim, size\_t elemSize ) amemalign is a hybrid of memalign and aalloc. It allows programmer to allocate an aligned dynamic array of objects without calculating the total size of the array explicitly. It frees the programmer from calculating the total size of the array. \paragraph{Usage} amemalign takes three parameters. \begin{itemize} \item It returns a dynamic array of objects that has the capacity to contain dim number of objects of the size of elemSize. The returned dynamic array is aligned to the given alignment. On failure, it returns NULL pointer. \subsubsection void * cmemalign( size_t alignment, size_t dim, size_t elemSize ) \subsubsection void * cmemalign( size\_t alignment, size\_t dim, size\_t elemSize ) cmemalign is a hybrid of amemalign and calloc. It allows programmer to allocate an aligned dynamic array of objects that is 0 filled. The current way to do this in other allocators is to allocate an aligned object with memalign and then fill it with 0 explicitly. This routine provides both features of aligning and 0 filling, implicitly. \paragraph{Usage} cmemalign takes three parameters. \begin{itemize} \item It returns a dynamic array of objects that has the capacity to contain dim number of objects of the size of elemSize. The returned dynamic array is aligned to the given alignment and is 0 filled. On failure, it returns NULL pointer. \subsubsection size_t malloc_alignment( void * addr ) malloc_alignment returns the alignment of a currently allocated dynamic object. It allows the programmer in memory management and personal bookkeeping. It helps the programmer in verofying the alignment of a dynamic object especially in a scenerio similar to prudcer-consumer where a producer allocates a dynamic object and the consumer needs to assure that the dynamic object was allocated with the required alignment. \paragraph{Usage} malloc_alignment takes one parameters. \subsubsection size\_t malloc\_alignment( void * addr ) malloc\_alignment returns the alignment of a currently allocated dynamic object. It allows the programmer in memory management and personal bookkeeping. It helps the programmer in verofying the alignment of a dynamic object especially in a scenerio similar to prudcer-consumer where a producer allocates a dynamic object and the consumer needs to assure that the dynamic object was allocated with the required alignment. \paragraph{Usage} malloc\_alignment takes one parameters. \begin{itemize} \item addr: the address of the currently allocated dynamic object. \end{itemize} malloc_alignment returns the alignment of the given dynamic object. On failure, it return the value of default alignment of the uHeapLmmm allocator. \subsubsection bool malloc_zero_fill( void * addr ) malloc_zero_fill returns whether a currently allocated dynamic object was initially zero filled at the time of allocation. It allows the programmer in memory management and personal bookkeeping. It helps the programmer in verifying the zero filled property of a dynamic object especially in a scenerio similar to prudcer-consumer where a producer allocates a dynamic object and the consumer needs to assure that the dynamic object was zero filled at the time of allocation. \paragraph{Usage} malloc_zero_fill takes one parameters. malloc\_alignment returns the alignment of the given dynamic object. On failure, it return the value of default alignment of the uHeapLmmm allocator. \subsubsection bool malloc\_zero\_fill( void * addr ) malloc\_zero\_fill returns whether a currently allocated dynamic object was initially zero filled at the time of allocation. It allows the programmer in memory management and personal bookkeeping. It helps the programmer in verifying the zero filled property of a dynamic object especially in a scenerio similar to prudcer-consumer where a producer allocates a dynamic object and the consumer needs to assure that the dynamic object was zero filled at the time of allocation. \paragraph{Usage} malloc\_zero\_fill takes one parameters. \begin{itemize} \item addr: the address of the currently allocated dynamic object. \end{itemize} malloc_zero_fill returns true if the dynamic object was initially zero filled and return false otherwise. On failure, it returns false. \subsubsection size_t malloc_size( void * addr ) malloc_size returns the allocation size of a currently allocated dynamic object. It allows the programmer in memory management and personal bookkeeping. It helps the programmer in verofying the alignment of a dynamic object especially in a scenerio similar to prudcer-consumer where a producer allocates a dynamic object and the consumer needs to assure that the dynamic object was allocated with the required size. Its current alternate in the other allocators is malloc_usable_size. But, malloc_size is different from malloc_usable_size as malloc_usabe_size returns the total data capacity of dynamic object including the extra space at the end of the dynamic object. On the other hand, malloc_size returns the size that was given to the allocator at the allocation of the dynamic object. This size is updated when an object is realloced, resized, or passed through a similar allocator routine. \paragraph{Usage} malloc_size takes one parameters. malloc\_zero\_fill returns true if the dynamic object was initially zero filled and return false otherwise. On failure, it returns false. \subsubsection size\_t malloc\_size( void * addr ) malloc\_size returns the allocation size of a currently allocated dynamic object. It allows the programmer in memory management and personal bookkeeping. It helps the programmer in verofying the alignment of a dynamic object especially in a scenerio similar to prudcer-consumer where a producer allocates a dynamic object and the consumer needs to assure that the dynamic object was allocated with the required size. Its current alternate in the other allocators is malloc\_usable\_size. But, malloc\_size is different from malloc\_usable\_size as malloc\_usabe\_size returns the total data capacity of dynamic object including the extra space at the end of the dynamic object. On the other hand, malloc\_size returns the size that was given to the allocator at the allocation of the dynamic object. This size is updated when an object is realloced, resized, or passed through a similar allocator routine. \paragraph{Usage} malloc\_size takes one parameters. \begin{itemize} \item addr: the address of the currently allocated dynamic object. \end{itemize} malloc_size returns the allocation size of the given dynamic object. On failure, it return zero. \subsubsection void * realloc( void * oaddr, size_t nalign, size_t size ) malloc\_size returns the allocation size of the given dynamic object. On failure, it return zero. \subsubsection void * realloc( void * oaddr, size\_t nalign, size\_t size ) This realloc is an extension of the default realloc (FIX ME: cite default realloc). In addition to reallocating an old object and preserving the data in old object, it can also realign the old object to a new alignment requirement. \paragraph{Usage} This realloc takes three parameters. It takes an additional parameter of nalign as compared to the default realloc. \begin{itemize} \item It returns a dynamic object of the size of type T. On failure, it return NULL pointer. \subsubsection T * aalloc( size_t dim ) \subsubsection T * aalloc( size\_t dim ) This aalloc is a simplified polymorphic form of above aalloc (FIX ME: cite aalloc). It takes one parameter as compared to the above aalloc that takes two parameters. \paragraph{Usage} aalloc takes one parameters. \begin{itemize} \item It returns a dynamic object that has the capacity to contain dim number of objects, each of the size of type T. On failure, it return NULL pointer. \subsubsection T * calloc( size_t dim ) \subsubsection T * calloc( size\_t dim ) This calloc is a simplified polymorphic form of defualt calloc (FIX ME: cite calloc). It takes one parameter as compared to the default calloc that takes two parameters. \paragraph{Usage} This calloc takes one parameter. \begin{itemize} \item It returns a dynamic object that has the capacity to contain dim number of objects, each of the size of type T. On failure, it return NULL pointer. \subsubsection T * resize( T * ptr, size_t size ) \subsubsection T * resize( T * ptr, size\_t size ) This resize is a simplified polymorphic form of above resize (FIX ME: cite resize with alignment). It takes two parameters as compared to the above resize that takes three parameters. It frees the programmer from explicitly mentioning the alignment of the allocation as CFA provides gives allocator the liberty to get the alignment of the returned type. \paragraph{Usage} This resize takes two parameters. \begin{itemize} \item It returns a dynamic object of the size given in paramters. The returned object is aligned to the alignemtn of type T. On failure, it return NULL pointer. \subsubsection T * realloc( T * ptr, size_t size ) \subsubsection T * realloc( T * ptr, size\_t size ) This realloc is a simplified polymorphic form of defualt realloc (FIX ME: cite realloc with align). It takes two parameters as compared to the above realloc that takes three parameters. It frees the programmer from explicitly mentioning the alignment of the allocation as CFA provides gives allocator the liberty to get the alignment of the returned type. \paragraph{Usage} This realloc takes two parameters. \begin{itemize} \item It returns a dynamic object of the size given in paramters that preserves the data in the given object. The returned object is aligned to the alignemtn of type T. On failure, it return NULL pointer. \subsubsection T * memalign( size_t align ) \subsubsection T * memalign( size\_t align ) This memalign is a simplified polymorphic form of defualt memalign (FIX ME: cite memalign). It takes one parameters as compared to the default memalign that takes two parameters. \paragraph{Usage} memalign takes one parameters. \begin{itemize} \item It returns a dynamic object of the size of type T that is aligned to given parameter align. On failure, it return NULL pointer. \subsubsection T * amemalign( size_t align, size_t dim ) \subsubsection T * amemalign( size\_t align, size\_t dim ) This amemalign is a simplified polymorphic form of above amemalign (FIX ME: cite amemalign). It takes two parameter as compared to the above amemalign that takes three parameters. \paragraph{Usage} amemalign takes two parameters. \begin{itemize} \item It returns a dynamic object that has the capacity to contain dim number of objects, each of the size of type T. The returned object is aligned to the given parameter align. On failure, it return NULL pointer. \subsubsection T * cmemalign( size_t align, size_t dim  ) \subsubsection T * cmemalign( size\_t align, size\_t dim  ) This cmemalign is a simplified polymorphic form of above cmemalign (FIX ME: cite cmemalign). It takes two parameter as compared to the above cmemalign that takes three parameters. \paragraph{Usage} cmemalign takes two parameters. \begin{itemize} \item It returns a dynamic object that has the capacity to contain dim number of objects, each of the size of type T. The returned object is aligned to the given parameter align and is zero filled. On failure, it return NULL pointer. \subsubsection T * aligned_alloc( size_t align ) This aligned_alloc is a simplified polymorphic form of defualt aligned_alloc (FIX ME: cite aligned_alloc). It takes one parameter as compared to the default aligned_alloc that takes two parameters. \paragraph{Usage} This aligned_alloc takes one parameter. \subsubsection T * aligned\_alloc( size\_t align ) This aligned\_alloc is a simplified polymorphic form of defualt aligned\_alloc (FIX ME: cite aligned\_alloc). It takes one parameter as compared to the default aligned\_alloc that takes two parameters. \paragraph{Usage} This aligned\_alloc takes one parameter. \begin{itemize} \item It returns a dynamic object of the size of type T that is aligned to the given parameter. On failure, it return NULL pointer. \subsubsection int posix_memalign( T ** ptr, size_t align ) This posix_memalign is a simplified polymorphic form of defualt posix_memalign (FIX ME: cite posix_memalign). It takes two parameters as compared to the default posix_memalign that takes three parameters. \paragraph{Usage} This posix_memalign takes two parameter. \subsubsection int posix\_memalign( T ** ptr, size\_t align ) This posix\_memalign is a simplified polymorphic form of defualt posix\_memalign (FIX ME: cite posix\_memalign). It takes two parameters as compared to the default posix\_memalign that takes three parameters. \paragraph{Usage} This posix\_memalign takes two parameter. \begin{itemize} \item align: required alignment of the dynamic object. \end{itemize} It stores address of the dynamic object of the size of type T in given parameter ptr. This object is aligned to the given parameter. On failure, it return NULL pointer. It returns a dynamic object of the size that is calcutaed by rouding the size of type T. The returned object is also aligned to the page size. On failure, it return NULL pointer. \subsection{Alloc Interface} \subsection Alloc Interface In addition to improve allocator interface both for CFA and our standalone allocator uHeapLmmm in C. We also added a new alloc interface in CFA that increases usability of dynamic memory allocation. This interface helps programmers in three major ways. \begin{itemize} \item This is the only parameter in the alloc routine that has a fixed-position and it is also the only parameter that does not use a backtick function. It has to be passed at the first position to alloc call in-case of an array allocation of objects of type T. It represents the required number of members in the array allocation as in CFA's aalloc (FIX ME: cite aalloc). This parameter should be of type size_t. This parameter should be of type size\_t. Example: int a = alloc( 5 ) \paragraph{Align} This parameter is position-free and uses a backtick routine align (align). The parameter passed with align should be of type size_t. If the alignment parameter is not a power of two or is less than the default alignment of the allocator (that can be found out using routine libAlign in CFA) then the passed alignment parameter will be rejected and the default alignment will be used. This parameter is position-free and uses a backtick routine align (align). The parameter passed with align should be of type size\_t. If the alignment parameter is not a power of two or is less than the default alignment of the allocator (that can be found out using routine libAlign in CFA) then the passed alignment parameter will be rejected and the default alignment will be used. Example: int b = alloc( 5 , 64align ) This parameter is position-free and uses a backtick routine fill (fill). In case of realloc, only the extra space after copying the data in the old object will be filled with given parameter. Three types of parameters can be passed using `fill. \begin{itemize} \item

• ## doc/theses/mubeen_zulfiqar_MMath/benchmarks.tex

 r949339b *** FIX ME: Insert a figure of above benchmark with description \paragrpah{Relevant Knobs} \paragraph{Relevant Knobs} *** FIX ME: Insert Relevant Knobs
• ## doc/theses/mubeen_zulfiqar_MMath/intro.tex

 r949339b %% 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 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \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. 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. \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. \begin{cfa} int ®data® = rtn( mon ); sout | acquire | "data:" | ®data®; mutex() sout | "data:" | ®data®; \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. 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} 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}