Ignore:
Timestamp:
Apr 19, 2022, 8:52:42 AM (23 months ago)
Author:
Peter A. Buhr <pabuhr@…>
Branches:
ADT, ast-experimental, master, pthread-emulation, qualifiedEnum
Children:
2e9b59b
Parents:
75cd27b
Message:

complete proofreading allocator chapter

File:
1 edited

Legend:

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

    r75cd27b rbb7c77d  
    175175More operating system support is required to make this model viable, but there is still the serially-reusable problem with user-level threading.
    176176Leaving the 1:1 model with no atomic actions along the fastpath and no special operating-system support required.
    177 The 1:1 model still has the serially-reusable problem with user-level threading, which is addressed in \VRef{}, and the greatest potential for heap blowup for certain allocation patterns.
     177The 1:1 model still has the serially-reusable problem with user-level threading, which is addressed in \VRef{s:UserlevelThreadingSupport}, and the greatest potential for heap blowup for certain allocation patterns.
    178178
    179179
     
    216216To obtain $O(1)$ external latency means obtaining one large storage area from the operating system and subdividing it across all program allocations, which requires a good guess at the program storage high-watermark and potential large external fragmentation.
    217217Excluding real-time operating-systems, operating-system operations are unbounded, and hence some external latency is unavoidable.
    218 The mitigating factor is that operating-system calls can often be reduced if a programmer has a sense of the storage high-watermark and the allocator is capable of using this information (see @malloc_expansion@ \VRef{}).
     218The mitigating factor is that operating-system calls can often be reduced if a programmer has a sense of the storage high-watermark and the allocator is capable of using this information (see @malloc_expansion@ \VPageref{p:malloc_expansion}).
    219219Furthermore, while operating-system calls are unbounded, many are now reasonably fast, so their latency is tolerable and infrequent.
    220220
     
    504504
    505505
    506 \section{Statistics and Debugging Modes}
     506\section{Statistics and Debugging}
    507507
    508508llheap can be built to accumulate fast and largely contention-free allocation statistics to help understand allocation behaviour.
     
    547547There is an unfortunate problem in detecting unfreed storage because some library routines assume their allocations have life-time duration, and hence, do not free their storage.
    548548For example, @printf@ allocates a 1024 buffer on first call and never deletes this buffer.
    549 To prevent a false positive for unfreed storage, it is possible to specify an amount of storage that is never freed (see \VRef{}), and it is subtracted from the total allocate/free difference.
     549To prevent a false positive for unfreed storage, it is possible to specify an amount of storage that is never freed (see @malloc_unfreed@ \VPageref{p:malloc_unfreed}), and it is subtracted from the total allocate/free difference.
    550550Determining the amount of never-freed storage is annoying, but once done, any warnings of unfreed storage are application related.
    551551
     
    554554
    555555\section{User-level Threading Support}
     556\label{s:UserlevelThreadingSupport}
    556557
    557558The serially-reusable problem (see \VRef{s:AllocationFastpath}) occurs for kernel threads in the ``T:H model, H = number of CPUs'' model and for user threads in the ``1:1'' model, where llheap uses the ``1:1'' model.
     
    670671It is possible to zero fill or align an allocation but not both.
    671672\item
    672 It is \emph{only} possible to zero fill and array allocation.
     673It is \emph{only} possible to zero fill an array allocation.
    673674\item
    674675It is not possible to resize a memory allocation without data copying.
     
    687688void free( void * ptr );
    688689void * memalign( size_t alignment, size_t size );
     690void * aligned_alloc( size_t alignment, size_t size );
     691int posix_memalign( void ** memptr, size_t alignment, size_t size );
    689692void * valloc( size_t size );
    690693void * pvalloc( size_t size );
     694
    691695struct mallinfo mallinfo( void );
    692696int mallopt( int param, int val );
     
    707711Most allocators use @nullptr@ to indicate an allocation failure, specifically out of memory;
    708712hence the need to return an alternate value for a zero-sized allocation.
    709 The alternative is to abort a program when out of memory.
    710 In theory, notifying the programmer allows recovery;
    711 in practice, it is almost impossible to gracefully recover when out of memory, so the cheaper approach of returning @nullptr@ for a zero-sized allocation is chosen for llheap.
     713A different approach allowed by the C API is to abort a program when out of memory and return @nullptr@ for a zero-sized allocation.
     714In theory, notifying the programmer of memory failure allows recovery;
     715in practice, it is almost impossible to gracefully recover when out of memory.
     716Hence, the cheaper approach of returning @nullptr@ for a zero-sized allocation is chosen because no pseudo allocation is necessary.
    712717
    713718
    714719\subsection{C Interface}
    715720
    716 Within the C type-system, it is still possible to increase orthogonality and functionality of the dynamic-memory API to make the allocator more usable for programmers.
     721For C, it is possible to increase functionality and orthogonality of the dynamic-memory API to make allocation better for programmers.
     722
     723For existing C allocation routines:
     724\begin{itemize}
     725\item
     726@calloc@ sets the sticky zero-fill property.
     727\item
     728@memalign@, @aligned_alloc@, @posix_memalign@, @valloc@ and @pvalloc@ set the sticky alignment property.
     729\item
     730@realloc@ and @reallocarray@ preserve sticky properties.
     731\end{itemize}
     732
     733The C dynamic-memory API is extended with the following routines:
    717734
    718735\paragraph{\lstinline{void * aalloc( size_t dim, size_t elemSize )}}
    719 @aalloc@ is an extension of malloc.
    720 It allows programmer to allocate a dynamic array of objects without calculating the total size of array explicitly.
    721 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.
    722 \paragraph{Usage}
     736extends @calloc@ for allocating a dynamic array of objects without calculating the total size of array explicitly but \emph{without} zero-filling the memory.
     737@aalloc@ is significantly faster than @calloc@, which is the only alternative.
     738
     739\noindent\textbf{Usage}
    723740@aalloc@ takes two parameters.
    724 
    725 \begin{itemize}
    726 \item
    727 @dim@: number of objects in the array
    728 \item
    729 @elemSize@: size of the object in the array.
    730 \end{itemize}
    731 It returns address of dynamic object allocated on heap that can contain dim number of objects of the size elemSize.
    732 On failure, it returns a @NULL@ pointer.
     741\begin{itemize}
     742\item
     743@dim@: number of array objects
     744\item
     745@elemSize@: size of array object
     746\end{itemize}
     747It returns the address of the dynamic array or @NULL@ if either @dim@ or @elemSize@ are zero.
    733748
    734749\paragraph{\lstinline{void * resize( void * oaddr, size_t size )}}
    735 @resize@ is an extension of relloc.
    736 It allows programmer to reuse a currently allocated dynamic object with a new size requirement.
    737 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.
    738 \paragraph{Usage}
     750extends @realloc@ for resizing an existing allocation \emph{without} copying previous data into the new allocation or preserving sticky properties.
     751@resize@ is significantly faster than @realloc@, which is the only alternative.
     752
     753\noindent\textbf{Usage}
    739754@resize@ takes two parameters.
    740 
    741 \begin{itemize}
    742 \item
    743 @oaddr@: the address of the old object that needs to be resized.
    744 \item
    745 @size@: the new size requirement of the to which the old object needs to be resized.
    746 \end{itemize}
    747 It returns an object that is of the size given but it does not preserve the data in the old object.
    748 On failure, it returns a @NULL@ pointer.
     755\begin{itemize}
     756\item
     757@oaddr@: address to be resized
     758\item
     759@size@: new allocation size (smaller or larger than previous)
     760\end{itemize}
     761It returns the address of the old or new storage with the specified new size or @NULL@ if @size@ is zero.
     762
     763\paragraph{\lstinline{void * amemalign( size_t alignment, size_t dim, size_t elemSize )}}
     764extends @aalloc@ and @memalign@ for allocating an aligned dynamic array of objects.
     765Sets sticky alignment property.
     766
     767\noindent\textbf{Usage}
     768@amemalign@ takes three parameters.
     769\begin{itemize}
     770\item
     771@alignment@: alignment requirement
     772\item
     773@dim@: number of array objects
     774\item
     775@elemSize@: size of array object
     776\end{itemize}
     777It returns the address of the aligned dynamic-array or @NULL@ if either @dim@ or @elemSize@ are zero.
     778
     779\paragraph{\lstinline{void * cmemalign( size_t alignment, size_t dim, size_t elemSize )}}
     780extends @amemalign@ with zero fill and has the same usage as @amemalign@.
     781Sets sticky zero-fill and alignment property.
     782It returns the address of the aligned, zero-filled dynamic-array or @NULL@ if either @dim@ or @elemSize@ are zero.
     783
     784\paragraph{\lstinline{size_t malloc_alignment( void * addr )}}
     785returns the alignment of the dynamic object for use in aligning similar allocations.
     786
     787\noindent\textbf{Usage}
     788@malloc_alignment@ takes one parameter.
     789\begin{itemize}
     790\item
     791@addr@: address of an allocated object.
     792\end{itemize}
     793It returns the alignment of the given object, where objects not allocated with alignment return the minimal allocation alignment.
     794
     795\paragraph{\lstinline{bool malloc_zero_fill( void * addr )}}
     796returns true if the object has the zero-fill sticky property for use in zero filling similar allocations.
     797
     798\noindent\textbf{Usage}
     799@malloc_zero_fill@ takes one parameters.
     800
     801\begin{itemize}
     802\item
     803@addr@: address of an allocated object.
     804\end{itemize}
     805It returns true if the zero-fill sticky property is set and false otherwise.
     806
     807\paragraph{\lstinline{size_t malloc_size( void * addr )}}
     808returns the request size of the dynamic object (updated when an object is resized) for use in similar allocations.
     809See also @malloc_usable_size@.
     810
     811\noindent\textbf{Usage}
     812@malloc_size@ takes one parameters.
     813\begin{itemize}
     814\item
     815@addr@: address of an allocated object.
     816\end{itemize}
     817It returns the request size or zero if @addr@ is @NULL@.
     818
     819\paragraph{\lstinline{int malloc_stats_fd( int fd )}}
     820changes the file descriptor where @malloc_stats@ writes statistics (default @stdout@).
     821
     822\noindent\textbf{Usage}
     823@malloc_stats_fd@ takes one parameters.
     824\begin{itemize}
     825\item
     826@fd@: files description.
     827\end{itemize}
     828It returns the previous file descriptor.
     829
     830\paragraph{\lstinline{size_t malloc_expansion()}}
     831\label{p:malloc_expansion}
     832set the amount (bytes) to extend the heap when there is insufficient free storage to service an allocation request.
     833It returns the heap extension size used throughout a program, \ie called once at heap initialization.
     834
     835\paragraph{\lstinline{size_t malloc_mmap_start()}}
     836set the crossover between allocations occurring in the @sbrk@ area or separately mapped.
     837It returns the crossover point used throughout a program, \ie called once at heap initialization.
     838
     839\paragraph{\lstinline{size_t malloc_unfreed()}}
     840\label{p:malloc_unfreed}
     841amount subtracted to adjust for unfreed program storage (debug only).
     842It returns the new subtraction amount and called by @malloc_stats@.
     843
     844
     845\subsection{\CC Interface}
     846
     847The following extensions take advantage of overload polymorphism in the \CC type-system.
    749848
    750849\paragraph{\lstinline{void * resize( void * oaddr, size_t nalign, size_t size )}}
    751 This @resize@ is an extension of the above @resize@ (FIX ME: cite above resize).
    752 In addition to resizing the size of of an old object, it can also realign the old object to a new alignment requirement.
    753 \paragraph{Usage}
    754 This resize takes three parameters.
    755 It takes an additional parameter of nalign as compared to the above resize (FIX ME: cite above resize).
    756 
    757 \begin{itemize}
    758 \item
    759 @oaddr@: the address of the old object that needs to be resized.
    760 \item
    761 @nalign@: the new alignment to which the old object needs to be realigned.
    762 \item
    763 @size@: the new size requirement of the to which the old object needs to be resized.
    764 \end{itemize}
    765 It returns an object with the size and alignment given in the parameters.
    766 On failure, it returns a @NULL@ pointer.
    767 
    768 \paragraph{\lstinline{void * amemalign( size_t alignment, size_t dim, size_t elemSize )}}
    769 amemalign is a hybrid of memalign and aalloc.
    770 It allows programmer to allocate an aligned dynamic array of objects without calculating the total size of the array explicitly.
    771 It frees the programmer from calculating the total size of the array.
    772 \paragraph{Usage}
    773 amemalign takes three parameters.
    774 
    775 \begin{itemize}
    776 \item
    777 @alignment@: the alignment to which the dynamic array needs to be aligned.
    778 \item
    779 @dim@: number of objects in the array
    780 \item
    781 @elemSize@: size of the object in the array.
    782 \end{itemize}
    783 It returns a dynamic array of objects that has the capacity to contain dim number of objects of the size of elemSize.
    784 The returned dynamic array is aligned to the given alignment.
    785 On failure, it returns a @NULL@ pointer.
    786 
    787 \paragraph{\lstinline{void * cmemalign( size_t alignment, size_t dim, size_t elemSize )}}
    788 cmemalign is a hybrid of amemalign and calloc.
    789 It allows programmer to allocate an aligned dynamic array of objects that is 0 filled.
    790 The current way to do this in other allocators is to allocate an aligned object with memalign and then fill it with 0 explicitly.
    791 This routine provides both features of aligning and 0 filling, implicitly.
    792 \paragraph{Usage}
    793 cmemalign takes three parameters.
    794 
    795 \begin{itemize}
    796 \item
    797 @alignment@: the alignment to which the dynamic array needs to be aligned.
    798 \item
    799 @dim@: number of objects in the array
    800 \item
    801 @elemSize@: size of the object in the array.
    802 \end{itemize}
    803 It returns a dynamic array of objects that has the capacity to contain dim number of objects of the size of elemSize.
    804 The returned dynamic array is aligned to the given alignment and is 0 filled.
    805 On failure, it returns a @NULL@ pointer.
    806 
    807 \paragraph{\lstinline{size_t malloc_alignment( void * addr )}}
    808 @malloc_alignment@ returns the alignment of a currently allocated dynamic object.
    809 It allows the programmer in memory management and personal bookkeeping.
    810 It helps the programmer in verifying the alignment of a dynamic object especially in a scenario similar to producer-consumer where a producer allocates a dynamic object and the consumer needs to assure that the dynamic object was allocated with the required alignment.
    811 \paragraph{Usage}
    812 @malloc_alignment@ takes one parameters.
    813 
    814 \begin{itemize}
    815 \item
    816 @addr@: the address of the currently allocated dynamic object.
    817 \end{itemize}
    818 @malloc_alignment@ returns the alignment of the given dynamic object.
    819 On failure, it return the value of default alignment of the llheap allocator.
    820 
    821 \paragraph{\lstinline{bool malloc_zero_fill( void * addr )}}
    822 @malloc_zero_fill@ returns whether a currently allocated dynamic object was initially zero filled at the time of allocation.
    823 It allows the programmer in memory management and personal bookkeeping.
    824 It helps the programmer in verifying the zero filled property of a dynamic object especially in a scenario similar to producer-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.
    825 \paragraph{Usage}
    826 @malloc_zero_fill@ takes one parameters.
    827 
    828 \begin{itemize}
    829 \item
    830 @addr@: the address of the currently allocated dynamic object.
    831 \end{itemize}
    832 @malloc_zero_fill@ returns true if the dynamic object was initially zero filled and return false otherwise.
    833 On failure, it returns false.
    834 
    835 \paragraph{\lstinline{size_t malloc_size( void * addr )}}
    836 @malloc_size@ returns the request size of a currently allocated dynamic object.
    837 It allows the programmer in memory management and personal bookkeeping.
    838 It helps the programmer in verifying the alignment of a dynamic object especially in a scenario similar to producer-consumer where a producer allocates a dynamic object and the consumer needs to assure that the dynamic object was allocated with the required size.
    839 Its current alternate in the other allocators is @malloc_usable_size@.
    840 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.
    841 On the other hand, @malloc_size@ returns the size that was given to the allocator at the allocation of the dynamic object.
    842 This size is updated when an object is realloced, resized, or passed through a similar allocator routine.
    843 \paragraph{Usage}
    844 @malloc_size@ takes one parameters.
    845 
    846 \begin{itemize}
    847 \item
    848 @addr@: the address of the currently allocated dynamic object.
    849 \end{itemize}
    850 @malloc_size@ returns the request size of the given dynamic object.
    851 On failure, it return zero.
    852 
    853 
    854 \subsection{\CC Interface}
     850extends @resize@ with an alignment re\-quirement.
     851
     852\noindent\textbf{Usage}
     853takes three parameters.
     854\begin{itemize}
     855\item
     856@oaddr@: address to be resized
     857\item
     858@nalign@: alignment requirement
     859\item
     860@size@: new allocation size (smaller or larger than previous)
     861\end{itemize}
     862It returns the address of the old or new storage with the specified new size and alignment, or @NULL@ if @size@ is zero.
    855863
    856864\paragraph{\lstinline{void * realloc( void * oaddr, size_t nalign, size_t size )}}
    857 This @realloc@ is an extension of the default @realloc@ (FIX ME: cite default @realloc@).
    858 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.
    859 \paragraph{Usage}
    860 This @realloc@ takes three parameters.
    861 It takes an additional parameter of nalign as compared to the default @realloc@.
    862 
    863 \begin{itemize}
    864 \item
    865 @oaddr@: the address of the old object that needs to be reallocated.
    866 \item
    867 @nalign@: the new alignment to which the old object needs to be realigned.
    868 \item
    869 @size@: the new size requirement of the to which the old object needs to be resized.
    870 \end{itemize}
    871 It returns an object with the size and alignment given in the parameters that preserves the data in the old object.
    872 On failure, it returns a @NULL@ pointer.
     865extends @realloc@ with an alignment re\-quirement and has the same usage as aligned @resize@.
    873866
    874867
    875868\subsection{\CFA Interface}
    876 We added some routines to the @malloc@ interface of \CFA.
    877 These routines can only be used in \CFA and not in our stand-alone llheap allocator as these routines use some features that are only provided by \CFA and not by C.
    878 It makes the allocator even more usable to the programmers.
    879 \CFA provides the liberty to know the returned type of a call to the allocator.
    880 So, mainly in these added routines, we removed the object size parameter from the routine as allocator can calculate the size of the object from the returned type.
    881 
    882 \subsection{\lstinline{T * malloc( void )}}
    883 This @malloc@ is a simplified polymorphic form of default @malloc@ (FIX ME: cite malloc).
    884 It does not take any parameter as compared to default @malloc@ that takes one parameter.
    885 \paragraph{Usage}
    886 This @malloc@ takes no parameters.
    887 It returns a dynamic object of the size of type @T@.
    888 On failure, it returns a @NULL@ pointer.
    889 
    890 \subsection{\lstinline{T * aalloc( size_t dim )}}
    891 This @aalloc@ is a simplified polymorphic form of above @aalloc@ (FIX ME: cite aalloc).
    892 It takes one parameter as compared to the above @aalloc@ that takes two parameters.
    893 \paragraph{Usage}
    894 aalloc takes one parameters.
    895 
    896 \begin{itemize}
    897 \item
    898 @dim@: required number of objects in the array.
    899 \end{itemize}
    900 It returns a dynamic object that has the capacity to contain dim number of objects, each of the size of type @T@.
    901 On failure, it returns a @NULL@ pointer.
    902 
    903 \subsection{\lstinline{T * calloc( size_t dim )}}
    904 This @calloc@ is a simplified polymorphic form of default @calloc@ (FIX ME: cite calloc).
    905 It takes one parameter as compared to the default @calloc@ that takes two parameters.
    906 \paragraph{Usage}
    907 This @calloc@ takes one parameter.
    908 
    909 \begin{itemize}
    910 \item
    911 @dim@: required number of objects in the array.
    912 \end{itemize}
    913 It returns a dynamic object that has the capacity to contain dim number of objects, each of the size of type @T@.
    914 On failure, it returns a @NULL@ pointer.
    915 
    916 \subsection{\lstinline{T * resize( T * ptr, size_t size )}}
    917 This resize is a simplified polymorphic form of above resize (FIX ME: cite resize with alignment).
    918 It takes two parameters as compared to the above resize that takes three parameters.
    919 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.
    920 \paragraph{Usage}
    921 This resize takes two parameters.
    922 
    923 \begin{itemize}
    924 \item
    925 @ptr@: address of the old object.
    926 \item
    927 @size@: the required size of the new object.
    928 \end{itemize}
    929 It returns a dynamic object of the size given in parameters.
    930 The returned object is aligned to the alignment of type @T@.
    931 On failure, it returns a @NULL@ pointer.
    932 
    933 \subsection{\lstinline{T * realloc( T * ptr, size_t size )}}
    934 This @realloc@ is a simplified polymorphic form of default @realloc@ (FIX ME: cite @realloc@ with align).
    935 It takes two parameters as compared to the above @realloc@ that takes three parameters.
    936 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.
    937 \paragraph{Usage}
    938 This @realloc@ takes two parameters.
    939 
    940 \begin{itemize}
    941 \item
    942 @ptr@: address of the old object.
    943 \item
    944 @size@: the required size of the new object.
    945 \end{itemize}
    946 It returns a dynamic object of the size given in parameters that preserves the data in the given object.
    947 The returned object is aligned to the alignment of type @T@.
    948 On failure, it returns a @NULL@ pointer.
    949 
    950 \subsection{\lstinline{T * memalign( size_t align )}}
    951 This memalign is a simplified polymorphic form of default memalign (FIX ME: cite memalign).
    952 It takes one parameters as compared to the default memalign that takes two parameters.
    953 \paragraph{Usage}
    954 memalign takes one parameters.
    955 
    956 \begin{itemize}
    957 \item
    958 @align@: the required alignment of the dynamic object.
    959 \end{itemize}
    960 It returns a dynamic object of the size of type @T@ that is aligned to given parameter align.
    961 On failure, it returns a @NULL@ pointer.
    962 
    963 \subsection{\lstinline{T * amemalign( size_t align, size_t dim )}}
    964 This amemalign is a simplified polymorphic form of above amemalign (FIX ME: cite amemalign).
    965 It takes two parameter as compared to the above amemalign that takes three parameters.
    966 \paragraph{Usage}
    967 amemalign takes two parameters.
    968 
    969 \begin{itemize}
    970 \item
    971 @align@: required alignment of the dynamic array.
    972 \item
    973 @dim@: required number of objects in the array.
    974 \end{itemize}
    975 It returns a dynamic object that has the capacity to contain dim number of objects, each of the size of type @T@.
    976 The returned object is aligned to the given parameter align.
    977 On failure, it returns a @NULL@ pointer.
    978 
    979 \subsection{\lstinline{T * cmemalign( size_t align, size_t dim  )}}
    980 This cmemalign is a simplified polymorphic form of above cmemalign (FIX ME: cite cmemalign).
    981 It takes two parameter as compared to the above cmemalign that takes three parameters.
    982 \paragraph{Usage}
    983 cmemalign takes two parameters.
    984 
    985 \begin{itemize}
    986 \item
    987 @align@: required alignment of the dynamic array.
    988 \item
    989 @dim@: required number of objects in the array.
    990 \end{itemize}
    991 It returns a dynamic object that has the capacity to contain dim number of objects, each of the size of type @T@.
    992 The returned object is aligned to the given parameter align and is zero filled.
    993 On failure, it returns a @NULL@ pointer.
    994 
    995 \subsection{\lstinline{T * aligned_alloc( size_t align )}}
    996 This @aligned_alloc@ is a simplified polymorphic form of default @aligned_alloc@ (FIX ME: cite @aligned_alloc@).
    997 It takes one parameter as compared to the default @aligned_alloc@ that takes two parameters.
    998 \paragraph{Usage}
    999 This @aligned_alloc@ takes one parameter.
    1000 
    1001 \begin{itemize}
    1002 \item
    1003 @align@: required alignment of the dynamic object.
    1004 \end{itemize}
    1005 It returns a dynamic object of the size of type @T@ that is aligned to the given parameter.
    1006 On failure, it returns a @NULL@ pointer.
    1007 
    1008 \subsection{\lstinline{int posix_memalign( T ** ptr, size_t align )}}
    1009 This @posix_memalign@ is a simplified polymorphic form of default @posix_memalign@ (FIX ME: cite @posix_memalign@).
    1010 It takes two parameters as compared to the default @posix_memalign@ that takes three parameters.
    1011 \paragraph{Usage}
    1012 This @posix_memalign@ takes two parameter.
    1013 
    1014 \begin{itemize}
    1015 \item
    1016 @ptr@: variable address to store the address of the allocated object.
    1017 \item
    1018 @align@: required alignment of the dynamic object.
    1019 \end{itemize}
    1020 
    1021 It stores address of the dynamic object of the size of type @T@ in given parameter ptr.
    1022 This object is aligned to the given parameter.
    1023 On failure, it returns a @NULL@ pointer.
    1024 
    1025 \subsection{\lstinline{T * valloc( void )}}
    1026 This @valloc@ is a simplified polymorphic form of default @valloc@ (FIX ME: cite @valloc@).
    1027 It takes no parameters as compared to the default @valloc@ that takes one parameter.
    1028 \paragraph{Usage}
    1029 @valloc@ takes no parameters.
    1030 It returns a dynamic object of the size of type @T@ that is aligned to the page size.
    1031 On failure, it returns a @NULL@ pointer.
    1032 
    1033 \subsection{\lstinline{T * pvalloc( void )}}
    1034 \paragraph{Usage}
    1035 @pvalloc@ takes no parameters.
    1036 It returns a dynamic object of the size that is calculated by rounding the size of type @T@.
    1037 The returned object is also aligned to the page size.
    1038 On failure, it returns a @NULL@ pointer.
    1039 
    1040 \subsection{Alloc Interface}
    1041 In addition to improve allocator interface both for \CFA and our stand-alone allocator llheap in C.
    1042 We also added a new alloc interface in \CFA that increases usability of dynamic memory allocation.
    1043 This interface helps programmers in three major ways.
    1044 
    1045 \begin{itemize}
    1046 \item
    1047 Routine Name: alloc interface frees programmers from remembering different routine names for different kind of dynamic allocations.
    1048 \item
    1049 Parameter Positions: alloc interface frees programmers from remembering parameter positions in call to routines.
    1050 \item
    1051 Object Size: alloc interface does not require programmer to mention the object size as \CFA allows allocator to determine the object size from returned type of alloc call.
    1052 \end{itemize}
    1053 
    1054 Alloc interface uses polymorphism, backtick routines (FIX ME: cite backtick) and ttype parameters of \CFA (FIX ME: cite ttype) to provide a very simple dynamic memory allocation interface to the programmers.
    1055 The new interface has just one routine name alloc that can be used to perform a wide range of dynamic allocations.
    1056 The parameters use backtick functions to provide a similar-to named parameters feature for our alloc interface so that programmers do not have to remember parameter positions in alloc call except the position of dimension (dim) parameter.
    1057 
    1058 \subsection{Routine: \lstinline{T * alloc( ...
    1059 )}}
    1060 Call to alloc without any parameter returns one object of size of type @T@ allocated dynamically.
    1061 Only the dimension (dim) parameter for array allocation has the fixed position in the alloc routine.
    1062 If programmer wants to allocate an array of objects that the required number of members in the array has to be given as the first parameter to the alloc routine.
    1063 alloc routine accepts six kinds of arguments.
    1064 Using different combinations of than parameters, different kind of allocations can be performed.
    1065 Any combination of parameters can be used together except @`realloc@ and @`resize@ that should not be used simultaneously in one call to routine as it creates ambiguity about whether to reallocate or resize a currently allocated dynamic object.
    1066 If both @`resize@ and @`realloc@ are used in a call to alloc then the latter one will take effect or unexpected resulted might be produced.
    1067 
    1068 \paragraph{Dim}
    1069 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.
    1070 It has to be passed at the first position to alloc call in-case of an array allocation of objects of type @T@.
    1071 It represents the required number of members in the array allocation as in \CFA's @aalloc@ (FIX ME: cite aalloc).
    1072 This parameter should be of type @size_t@.
    1073 
    1074 Example: @int a = alloc( 5 )@
    1075 This call will return a dynamic array of five integers.
    1076 
    1077 \paragraph{Align}
    1078 This parameter is position-free and uses a backtick routine align (@`align@).
    1079 The parameter passed with @`align@ should be of type @size_t@.
    1080 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.
    1081 
    1082 Example: @int b = alloc( 5 , 64`align )@
    1083 This call will return a dynamic array of five integers.
    1084 It will align the allocated object to 64.
    1085 
    1086 \paragraph{Fill}
    1087 This parameter is position-free and uses a backtick routine fill (@`fill@).
    1088 In case of @realloc@, only the extra space after copying the data in the old object will be filled with given parameter.
    1089 Three types of parameters can be passed using `fill.
    1090 
    1091 \begin{itemize}
    1092 \item
    1093 @char@: A char can be passed with @`fill@ to fill the whole dynamic allocation with the given char recursively till the end of required allocation.
    1094 \item
    1095 Object of returned type: An object of type of returned type can be passed with @`fill@ to fill the whole dynamic allocation with the given object recursively till the end of required allocation.
    1096 \item
    1097 Dynamic object of returned type: A dynamic object of type of returned type can be passed with @`fill@ to fill the dynamic allocation with the given dynamic object.
    1098 In this case, the allocated memory is not filled recursively till the end of allocation.
    1099 The filling happen until the end object passed to @`fill@ or the end of requested allocation reaches.
    1100 \end{itemize}
    1101 
    1102 Example: @int b = alloc( 5 , 'a'`fill )@
    1103 This call will return a dynamic array of five integers.
    1104 It will fill the allocated object with character 'a' recursively till the end of requested allocation size.
    1105 
    1106 Example: @int b = alloc( 5 , 4`fill )@
    1107 This call will return a dynamic array of five integers.
    1108 It will fill the allocated object with integer 4 recursively till the end of requested allocation size.
    1109 
    1110 Example: @int b = alloc( 5 , a`fill )@ where @a@ is a pointer of int type
    1111 This call will return a dynamic array of five integers.
    1112 It will copy data in a to the returned object non-recursively until end of a or the newly allocated object is reached.
    1113 
    1114 \paragraph{Resize}
    1115 This parameter is position-free and uses a backtick routine resize (@`resize@).
    1116 It represents the old dynamic object (oaddr) that the programmer wants to
    1117 \begin{itemize}
    1118 \item
    1119 resize to a new size.
    1120 \item
    1121 realign to a new alignment
    1122 \item
    1123 fill with something.
    1124 \end{itemize}
    1125 The data in old dynamic object will not be preserved in the new object.
    1126 The type of object passed to @`resize@ and the returned type of alloc call can be different.
    1127 
    1128 Example: @int b = alloc( 5 , a`resize )@
    1129 This call will resize object a to a dynamic array that can contain 5 integers.
    1130 
    1131 Example: @int b = alloc( 5 , a`resize , 32`align )@
    1132 This call will resize object a to a dynamic array that can contain 5 integers.
    1133 The returned object will also be aligned to 32.
    1134 
    1135 Example: @int b = alloc( 5 , a`resize , 32`align , 2`fill )@
    1136 This call will resize object a to a dynamic array that can contain 5 integers.
    1137 The returned object will also be aligned to 32 and will be filled with 2.
    1138 
    1139 \paragraph{Realloc}
    1140 This parameter is position-free and uses a backtick routine @realloc@ (@`realloc@).
    1141 It represents the old dynamic object (oaddr) that the programmer wants to
    1142 \begin{itemize}
    1143 \item
    1144 realloc to a new size.
    1145 \item
    1146 realign to a new alignment
    1147 \item
    1148 fill with something.
    1149 \end{itemize}
    1150 The data in old dynamic object will be preserved in the new object.
    1151 The type of object passed to @`realloc@ and the returned type of alloc call cannot be different.
    1152 
    1153 Example: @int b = alloc( 5 , a`realloc )@
    1154 This call will realloc object a to a dynamic array that can contain 5 integers.
    1155 
    1156 Example: @int b = alloc( 5 , a`realloc , 32`align )@
    1157 This call will realloc object a to a dynamic array that can contain 5 integers.
    1158 The returned object will also be aligned to 32.
    1159 
    1160 Example: @int b = alloc( 5 , a`realloc , 32`align , 2`fill )@
    1161 This call will resize object a to a dynamic array that can contain 5 integers.
    1162 The returned object will also be aligned to 32.
    1163 The extra space after copying data of a to the returned object will be filled with 2.
     869
     870The following extensions take advantage of overload polymorphism in the \CFA type-system.
     871The key safety advantage of the \CFA type system is using the return type to select overloads;
     872hence, a polymorphic routine knows the returned type and its size.
     873This capability is used to remove the object size parameter and correctly cast the return storage to match the result type.
     874For example, the following is the \CFA wrapper for C @malloc@:
     875\begin{cfa}
     876forall( T & | sized(T) ) {
     877        T * malloc( void ) {
     878                if ( _Alignof(T) <= libAlign() ) return @(T *)@malloc( @sizeof(T)@ ); // C allocation
     879                else return @(T *)@memalign( @_Alignof(T)@, @sizeof(T)@ ); // C allocation
     880        } // malloc
     881\end{cfa}
     882and is used as follows:
     883\begin{lstlisting}
     884int * i = malloc();
     885double * d = malloc();
     886struct Spinlock { ... } __attribute__(( aligned(128) ));
     887Spinlock * sl = malloc();
     888\end{lstlisting}
     889where each @malloc@ call provides the return type as @T@, which is used with @sizeof@, @_Alignof@, and casting the storage to the correct type.
     890This interface removes many of the common allocation errors in C programs.
     891\VRef[Figure]{f:CFADynamicAllocationAPI} show the \CFA wrappers for the equivalent C/\CC allocation routines with same semantic behaviour.
     892
     893\begin{figure}
     894\begin{lstlisting}
     895T * malloc( void );
     896T * aalloc( size_t dim );
     897T * calloc( size_t dim );
     898T * resize( T * ptr, size_t size );
     899T * realloc( T * ptr, size_t size );
     900T * memalign( size_t align );
     901T * amemalign( size_t align, size_t dim );
     902T * cmemalign( size_t align, size_t dim  );
     903T * aligned_alloc( size_t align );
     904int posix_memalign( T ** ptr, size_t align );
     905T * valloc( void );
     906T * pvalloc( void );
     907\end{lstlisting}
     908\caption{\CFA C-Style Dynamic-Allocation API}
     909\label{f:CFADynamicAllocationAPI}
     910\end{figure}
     911
     912In addition to the \CFA C-style allocator interface, a new allocator interface is provided to further increase orthogonality and usability of dynamic-memory allocation.
     913This interface helps programmers in three ways.
     914\begin{itemize}
     915\item
     916naming: \CFA regular and @ttype@ polymorphism is used to encapsulate a wide range of allocation functionality into a single routine name, so programmers do not have to remember multiple routine names for different kinds of dynamic allocations.
     917\item
     918named arguments: individual allocation properties are specified using postfix function call, so programmers do have to remember parameter positions in allocation calls.
     919\item
     920object size: like the \CFA C-style interface, programmers do not have to specify object size or cast allocation results.
     921\end{itemize}
     922Note, postfix function call is an alternative call syntax, using backtick @`@, where the argument appears before the function name, \eg
     923\begin{cfa}
     924duration ?@`@h( int h );                // ? denote the position of the function operand
     925duration ?@`@m( int m );
     926duration ?@`@s( int s );
     927duration dur = 3@`@h + 42@`@m + 17@`@s;
     928\end{cfa}
     929@ttype@ polymorphism is similar to \CC variadic templates.
     930
     931\paragraph{\lstinline{T * alloc( ... )} or \lstinline{T * alloc( size_t dim, ... )}}
     932is overloaded with a variable number of specific allocation routines, or an integer dimension parameter followed by a variable number specific allocation routines.
     933A call without parameters returns a dynamically allocated object of type @T@ (@malloc@).
     934A call with only the dimension (dim) parameter returns a dynamically allocated array of objects of type @T@ (@aalloc@).
     935The variable number of arguments consist of allocation properties, which can be combined to produce different kinds of allocations.
     936The only restriction is for properties @realloc@ and @resize@, which cannot be combined.
     937
     938The allocation property functions are:
     939\subparagraph{\lstinline{T_align ?`align( size_t alignment )}}
     940to align the allocation.
     941The alignment parameter must be $\ge$ the default alignment (@libAlign()@ in \CFA) and a power of two, \eg:
     942\begin{cfa}
     943int * i0 = alloc( @4096`align@ );  sout | i0 | nl;
     944int * i1 = alloc( 3, @4096`align@ );  sout | i1; for (i; 3 ) sout | &i1[i]; sout | nl;
     945
     9460x555555572000
     9470x555555574000 0x555555574000 0x555555574004 0x555555574008
     948\end{cfa}
     949returns a dynamic object and object array aligned on a 4096-byte boundary.
     950
     951\subparagraph{\lstinline{S_fill(T) ?`fill ( /* various types */ )}}
     952to initialize storage.
     953There are three ways to fill storage:
     954\begin{enumerate}
     955\item
     956A char fills each byte of each object.
     957\item
     958An object of the returned type fills each object.
     959\item
     960An object array pointer fills some or all of the corresponding object array.
     961\end{enumerate}
     962For example:
     963\begin{cfa}[numbers=left]
     964int * i0 = alloc( @0n`fill@ );  sout | *i0 | nl;  // disambiguate 0
     965int * i1 = alloc( @5`fill@ );  sout | *i1 | nl;
     966int * i2 = alloc( @'\xfe'`fill@ ); sout | hex( *i2 ) | nl;
     967int * i3 = alloc( 5, @5`fill@ );  for ( i; 5 ) sout | i3[i]; sout | nl;
     968int * i4 = alloc( 5, @0xdeadbeefN`fill@ );  for ( i; 5 ) sout | hex( i4[i] ); sout | nl;
     969int * i5 = alloc( 5, @i3`fill@ );  for ( i; 5 ) sout | i5[i]; sout | nl;
     970int * i6 = alloc( 5, @[i3, 3]`fill@ );  for ( i; 5 ) sout | i6[i]; sout | nl;
     971\end{cfa}
     972\begin{lstlisting}[numbers=left]
     9730
     9745
     9750xfefefefe
     9765 5 5 5 5
     9770xdeadbeef 0xdeadbeef 0xdeadbeef 0xdeadbeef 0xdeadbeef
     9785 5 5 5 5
     9795 5 5 -555819298 -555819298  // two undefined values
     980\end{lstlisting}
     981Examples 1 to 3, fill an object with a value or characters.
     982Examples 4 to 7, fill an array of objects with values, another array, or part of an array.
     983
     984\subparagraph{\lstinline{S_resize(T) ?`resize( void * oaddr )}}
     985used to resize, realign, and fill, where the old object data is not copied to the new object.
     986The old object type may be different from the new object type, since the values are not used.
     987For example:
     988\begin{cfa}[numbers=left]
     989int * i = alloc( @5`fill@ );  sout | i | *i;
     990i = alloc( @i`resize@, @256`align@, @7`fill@ );  sout | i | *i;
     991double * d = alloc( @i`resize@, @4096`align@, @13.5`fill@ );  sout | d | *d;
     992\end{cfa}
     993\begin{lstlisting}[numbers=left]
     9940x55555556d5c0 5
     9950x555555570000 7
     9960x555555571000 13.5
     997\end{lstlisting}
     998Examples 2 to 3 change the alignment, fill, and size for the initial storage of @i@.
     999
     1000\begin{cfa}[numbers=left]
     1001int * ia = alloc( 5, @5`fill@ );  for ( i; 5 ) sout | ia[i]; sout | nl;
     1002ia = alloc( 10, @ia`resize@, @7`fill@ ); for ( i; 10 ) sout | ia[i]; sout | nl;
     1003sout | ia; ia = alloc( 5, @ia`resize@, @512`align@, @13`fill@ ); sout | ia; for ( i; 5 ) sout | ia[i]; sout | nl;;
     1004ia = alloc( 3, @ia`resize@, @4096`align@, @2`fill@ );  sout | ia; for ( i; 3 ) sout | &ia[i] | ia[i]; sout | nl;
     1005\end{cfa}
     1006\begin{lstlisting}[numbers=left]
     10075 5 5 5 5
     10087 7 7 7 7 7 7 7 7 7
     10090x55555556d560 0x555555571a00 13 13 13 13 13
     10100x555555572000 0x555555572000 2 0x555555572004 2 0x555555572008 2
     1011\end{lstlisting}
     1012Examples 2 to 4 change the array size, alignment and fill for the initial storage of @ia@.
     1013
     1014\subparagraph{\lstinline{S_realloc(T) ?`realloc( T * a ))}}
     1015used to resize, realign, and fill, where the old object data is copied to the new object.
     1016The old object type must be the same as the new object type, since the values used.
     1017Note, for @fill@, only the extra space after copying the data from the old object is filled with the given parameter.
     1018For example:
     1019\begin{cfa}[numbers=left]
     1020int * i = alloc( @5`fill@ );  sout | i | *i;
     1021i = alloc( @i`realloc@, @256`align@ );  sout | i | *i;
     1022i = alloc( @i`realloc@, @4096`align@, @13`fill@ );  sout | i | *i;
     1023\end{cfa}
     1024\begin{lstlisting}[numbers=left]
     10250x55555556d5c0 5
     10260x555555570000 5
     10270x555555571000 5
     1028\end{lstlisting}
     1029Examples 2 to 3 change the alignment for the initial storage of @i@.
     1030The @13`fill@ for example 3 does nothing because no extra space is added.
     1031
     1032\begin{cfa}[numbers=left]
     1033int * ia = alloc( 5, @5`fill@ );  for ( i; 5 ) sout | ia[i]; sout | nl;
     1034ia = alloc( 10, @ia`realloc@, @7`fill@ ); for ( i; 10 ) sout | ia[i]; sout | nl;
     1035sout | ia; ia = alloc( 1, @ia`realloc@, @512`align@, @13`fill@ ); sout | ia; for ( i; 1 ) sout | ia[i]; sout | nl;;
     1036ia = alloc( 3, @ia`realloc@, @4096`align@, @2`fill@ );  sout | ia; for ( i; 3 ) sout | &ia[i] | ia[i]; sout | nl;
     1037\end{cfa}
     1038\begin{lstlisting}[numbers=left]
     10395 5 5 5 5
     10405 5 5 5 5 7 7 7 7 7
     10410x55555556c560 0x555555570a00 5
     10420x555555571000 0x555555571000 5 0x555555571004 2 0x555555571008 2
     1043\end{lstlisting}
     1044Examples 2 to 4 change the array size, alignment and fill for the initial storage of @ia@.
     1045The @13`fill@ for example 3 does nothing because no extra space is added.
     1046
     1047These \CFA allocation features are used extensively in the development of the \CFA runtime.
Note: See TracChangeset for help on using the changeset viewer.