Index: doc/user/user.tex =================================================================== --- doc/user/user.tex (revision d6fb3c7e3fd2b09068679e165b082afc47930b28) +++ doc/user/user.tex (revision 6065b3aad7ca045ec48fc6103d1c55f0b5fb74b0) @@ -11,6 +11,6 @@ %% 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 : Thu Jun 1 22:46:09 2017 +%% Update Count : 2126 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -5242,77 +5242,86 @@ \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}§ +extern "C" { void * calloc( size_t dim, size_t size ); }§\indexc{calloc}§ +extern "C" { void * realloc( void * ptr, size_t size ); }§\indexc{realloc}§ +extern "C" { void * memalign( size_t align, size_t size ); }§\indexc{memalign}§ +extern "C" { 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 ); } +extern "C" { 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}