source: doc/theses/mubeen_zulfiqar_MMath/allocator.tex @ 1eec0b0

ADTast-experimentalenumpthread-emulationqualifiedEnum
Last change on this file since 1eec0b0 was 1eec0b0, checked in by Peter A. Buhr <pabuhr@…>, 3 years ago

organizes figures into directories, update Makefile, add text from allocator paper as starting point

  • Property mode set to 100644
File size: 28.2 KB
Line 
1\chapter{Allocator}
2
3\noindent
4====================
5
6Writing Points:
7\begin{itemize}
8\item
9Objective of uHeapLmmm.
10\item
11Design philosophy.
12\item
13Background and previous design of uHeapLmmm.
14\item
15Distributed design of uHeapLmmm.
16
17----- SHOULD WE GIVE IMPLEMENTATION DETAILS HERE? -----
18
19\PAB{Maybe. There might be an Implementation chapter.}
20\item
21figure.
22\item
23Advantages of distributed design.
24\end{itemize}
25
26The new features added to uHeapLmmm (incl. @malloc_size@ routine)
27\CFA alloc interface with examples.
28
29\begin{itemize}
30\item
31Why did we need it?
32\item
33The added benefits.
34\end{itemize}
35
36
37%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
38%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
39%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% uHeapLmmm Design
40%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
41%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
42
43\section{Objective of uHeapLmmm}
44UHeapLmmm is a lightweight memory allocator. The objective behind uHeapLmmm is to design a minimal concurrent memory allocator that has new features and also fulfills GNU C Library requirements (FIX ME: cite requirements).
45
46\subsection{Design philosophy}
47The objective of uHeapLmmm's new design was to fulfill following requirements:
48\begin{itemize}
49\item It should be concurrent to be used in multi-threaded programs.
50\item It should avoid global locks, on resources shared across all threads, as much as possible.
51\item It's performance (FIX ME: cite performance benchmarks) should be comparable to the commonly used allocators (FIX ME: cite common allocators).
52\item It should be a lightweight memory allocator.
53\end{itemize}
54
55%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
56
57\section{Background and previous design of uHeapLmmm}
58uHeapLmmm was originally designed by X in X (FIX ME: add original author after confirming with Peter).
59(FIX ME: make and add figure of previous design with description)
60
61%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
62
63\section{Distributed design of uHeapLmmm}
64uHeapLmmm's design was reviewed and changed to fulfill new requirements (FIX ME: cite allocator philosophy). For this purpose, following two designs of uHeapLmm were proposed:
65
66\paragraph{Design 1: Decentralized}
67Fixed number of heaps: shard the heap into N heaps each with a bump-area allocated from the @sbrk@ area.
68Kernel threads (KT) are assigned to the N heaps.
69When KTs $\le$ N, the heaps are uncontented.
70When KTs $>$ N, the heaps are contented.
71By adjusting N, this approach reduces storage at the cost of speed due to contention.
72In all cases, a thread acquires/releases a lock, contented or uncontented.
73\begin{cquote}
74\centering
75\input{AllocDS1}
76\end{cquote}
77Problems: need to know when a KT is created and destroyed to know when to assign/un-assign a heap to the KT.
78
79\paragraph{Design 2: Centralized}
80One heap, but lower bucket sizes are N-shared across KTs.
81This design leverages the fact that 95\% of allocation requests are less than 512 bytes and there are only 3--5 different request sizes.
82When KTs $\le$ N, the important bucket sizes are uncontented.
83When KTs $>$ N, the free buckets are contented.
84Therefore, threads are only contending for a small number of buckets, which are distributed among them to reduce contention.
85\begin{cquote}
86\centering
87\input{AllocDS2}
88\end{cquote}
89Problems: need to know when a kernel thread (KT) is created and destroyed to know when to assign a shared bucket-number.
90When no thread is assigned a bucket number, its free storage is unavailable. All KTs will be contended for one lock on sbrk for their initial allocations (before free-lists gets populated).
91
92Out of the two designs, Design 1 was chosen because it's concurrency is better across all bucket-sizes as design-2 shards a few buckets of selected sizes while design-1 shards all the buckets. Design-2 shards the whole heap which has all the buckets with the addition of sharding sbrk area.
93
94\subsection{Advantages of distributed design}
95The distributed design of uHeapLmmm is concurrent to work in multi-threaded applications.
96
97Some key benefits of the distributed design of uHeapLmmm are as follows:
98
99\begin{itemize}
100\item
101The bump allocation is concurrent as memory taken from sbrk is sharded across all heaps as bump allocation reserve. The lock on bump allocation (on memory taken from sbrk) will only be contended if KTs $<$ N. The contention on sbrk area is less likely as it will only happen in the case if heaps assigned to two KTs get short of bump allocation reserve simultanously.
102\item
103N heaps are created at the start of the program and destroyed at the end of program. When a KT is created, we only assign it to one of the heaps. When a KT is destroyed, we only dissociate it from the assigned heap but we do not destroy that heap. That heap will go back to our pool-of-heaps, ready to be used by some new KT. And if that heap was shared among multiple KTs (like the case of KTs $<$ N) then, on deletion of one KT, that heap will be still in-use of the other KTs. This will prevent creation and deletion of heaps during run-time as heaps are re-usable which helps in keeping low-memory footprint.
104\item
105It is possible to use sharing and stealing techniques to share/find unused storage, when a free list is unused or empty.
106\item
107Distributed design avoids unnecassry locks on resources shared across all KTs.
108\end{itemize}
109
110FIX ME: Cite performance comparison of the two heap designs if required
111
112%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
113
114\section{Added Features and Methods}
115To improve the UHeapLmmm allocator (FIX ME: cite uHeapLmmm) interface and make it more user friendly, we added a few more routines to the C allocator. Also, we built a \CFA (FIX ME: cite cforall) interface on top of C interface to increase the usability of the allocator.
116
117\subsection{C Interface}
118We 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.
119
120\subsection{\lstinline{void * aalloc( size_t dim, size_t elemSize )}}
121@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.
122\paragraph{Usage}
123@aalloc@ takes two parameters.
124
125\begin{itemize}
126\item
127@dim@: number of objects in the array
128\item
129@elemSize@: size of the object in the array.
130\end{itemize}
131It returns address of dynamic object allocatoed on heap that can contain dim number of objects of the size elemSize. On failure, it returns a @NULL@ pointer.
132
133\subsection{\lstinline{void * resize( void * oaddr, size_t size )}}
134@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.
135\paragraph{Usage}
136@resize@ takes two parameters.
137
138\begin{itemize}
139\item
140@oaddr@: the address of the old object that needs to be resized.
141\item
142@size@: the new size requirement of the to which the old object needs to be resized.
143\end{itemize}
144It returns an object that is of the size given but it does not preserve the data in the old object. On failure, it returns a @NULL@ pointer.
145
146\subsection{\lstinline{void * resize( void * oaddr, size_t nalign, size_t size )}}
147This @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.
148\paragraph{Usage}
149This resize takes three parameters. It takes an additional parameter of nalign as compared to the above resize (FIX ME: cite above resize).
150
151\begin{itemize}
152\item
153@oaddr@: the address of the old object that needs to be resized.
154\item
155@nalign@: the new alignment to which the old object needs to be realigned.
156\item
157@size@: the new size requirement of the to which the old object needs to be resized.
158\end{itemize}
159It returns an object with the size and alignment given in the parameters. On failure, it returns a @NULL@ pointer.
160
161\subsection{\lstinline{void * amemalign( size_t alignment, size_t dim, size_t elemSize )}}
162amemalign 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.
163\paragraph{Usage}
164amemalign takes three parameters.
165
166\begin{itemize}
167\item
168@alignment@: the alignment to which the dynamic array needs to be aligned.
169\item
170@dim@: number of objects in the array
171\item
172@elemSize@: size of the object in the array.
173\end{itemize}
174It 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 a @NULL@ pointer.
175
176\subsection{\lstinline{void * cmemalign( size_t alignment, size_t dim, size_t elemSize )}}
177cmemalign 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.
178\paragraph{Usage}
179cmemalign takes three parameters.
180
181\begin{itemize}
182\item
183@alignment@: the alignment to which the dynamic array needs to be aligned.
184\item
185@dim@: number of objects in the array
186\item
187@elemSize@: size of the object in the array.
188\end{itemize}
189It 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 a @NULL@ pointer.
190
191\subsection{\lstinline{size_t malloc_alignment( void * addr )}}
192@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.
193\paragraph{Usage}
194@malloc_alignment@ takes one parameters.
195
196\begin{itemize}
197\item
198@addr@: the address of the currently allocated dynamic object.
199\end{itemize}
200@malloc_alignment@ returns the alignment of the given dynamic object. On failure, it return the value of default alignment of the uHeapLmmm allocator.
201
202\subsection{\lstinline{bool malloc_zero_fill( void * addr )}}
203@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.
204\paragraph{Usage}
205@malloc_zero_fill@ takes one parameters.
206
207\begin{itemize}
208\item
209@addr@: the address of the currently allocated dynamic object.
210\end{itemize}
211@malloc_zero_fill@ returns true if the dynamic object was initially zero filled and return false otherwise. On failure, it returns false.
212
213\subsection{\lstinline{size_t malloc_size( void * addr )}}
214@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.
215\paragraph{Usage}
216@malloc_size@ takes one parameters.
217
218\begin{itemize}
219\item
220@addr@: the address of the currently allocated dynamic object.
221\end{itemize}
222@malloc_size@ returns the allocation size of the given dynamic object. On failure, it return zero.
223
224\subsection{\lstinline{void * realloc( void * oaddr, size_t nalign, size_t size )}}
225This @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.
226\paragraph{Usage}
227This @realloc@ takes three parameters. It takes an additional parameter of nalign as compared to the default @realloc@.
228
229\begin{itemize}
230\item
231@oaddr@: the address of the old object that needs to be reallocated.
232\item
233@nalign@: the new alignment to which the old object needs to be realigned.
234\item
235@size@: the new size requirement of the to which the old object needs to be resized.
236\end{itemize}
237It returns an object with the size and alignment given in the parameters that preserves the data in the old object. On failure, it returns a @NULL@ pointer.
238
239\subsection{\CFA Malloc Interface}
240We added some routines to the malloc interface of \CFA. These routines can only be used in \CFA and not in our standalone uHeapLmmm allocator as these routines use some features that are only provided by \CFA and not by C. It makes the allocator even more usable to the programmers.
241\CFA provides the liberty to know the returned type of a call to the allocator. 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.
242
243\subsection{\lstinline{T * malloc( void )}}
244This malloc is a simplified polymorphic form of defualt malloc (FIX ME: cite malloc). It does not take any parameter as compared to default malloc that takes one parameter.
245\paragraph{Usage}
246This malloc takes no parameters.
247It returns a dynamic object of the size of type @T@. On failure, it returns a @NULL@ pointer.
248
249\subsection{\lstinline{T * aalloc( size_t dim )}}
250This 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.
251\paragraph{Usage}
252aalloc takes one parameters.
253
254\begin{itemize}
255\item
256@dim@: required number of objects in the array.
257\end{itemize}
258It returns a dynamic object that has the capacity to contain dim number of objects, each of the size of type @T@. On failure, it returns a @NULL@ pointer.
259
260\subsection{\lstinline{T * calloc( size_t dim )}}
261This 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.
262\paragraph{Usage}
263This calloc takes one parameter.
264
265\begin{itemize}
266\item
267@dim@: required number of objects in the array.
268\end{itemize}
269It returns a dynamic object that has the capacity to contain dim number of objects, each of the size of type @T@. On failure, it returns a @NULL@ pointer.
270
271\subsection{\lstinline{T * resize( T * ptr, size_t size )}}
272This 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.
273\paragraph{Usage}
274This resize takes two parameters.
275
276\begin{itemize}
277\item
278@ptr@: address of the old object.
279\item
280@size@: the required size of the new object.
281\end{itemize}
282It returns a dynamic object of the size given in paramters. The returned object is aligned to the alignemtn of type @T@. On failure, it returns a @NULL@ pointer.
283
284\subsection{\lstinline{T * realloc( T * ptr, size_t size )}}
285This @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.
286\paragraph{Usage}
287This @realloc@ takes two parameters.
288
289\begin{itemize}
290\item
291@ptr@: address of the old object.
292\item
293@size@: the required size of the new object.
294\end{itemize}
295It 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 returns a @NULL@ pointer.
296
297\subsection{\lstinline{T * memalign( size_t align )}}
298This 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.
299\paragraph{Usage}
300memalign takes one parameters.
301
302\begin{itemize}
303\item
304@align@: the required alignment of the dynamic object.
305\end{itemize}
306It returns a dynamic object of the size of type @T@ that is aligned to given parameter align. On failure, it returns a @NULL@ pointer.
307
308\subsection{\lstinline{T * amemalign( size_t align, size_t dim )}}
309This 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.
310\paragraph{Usage}
311amemalign takes two parameters.
312
313\begin{itemize}
314\item
315@align@: required alignment of the dynamic array.
316\item
317@dim@: required number of objects in the array.
318\end{itemize}
319It 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 returns a @NULL@ pointer.
320
321\subsection{\lstinline{T * cmemalign( size_t align, size_t dim  )}}
322This 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.
323\paragraph{Usage}
324cmemalign takes two parameters.
325
326\begin{itemize}
327\item
328@align@: required alignment of the dynamic array.
329\item
330@dim@: required number of objects in the array.
331\end{itemize}
332It 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 returns a @NULL@ pointer.
333
334\subsection{\lstinline{T * aligned_alloc( size_t align )}}
335This @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.
336\paragraph{Usage}
337This @aligned_alloc@ takes one parameter.
338
339\begin{itemize}
340\item
341@align@: required alignment of the dynamic object.
342\end{itemize}
343It returns a dynamic object of the size of type @T@ that is aligned to the given parameter. On failure, it returns a @NULL@ pointer.
344
345\subsection{\lstinline{int posix_memalign( T ** ptr, size_t align )}}
346This @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.
347\paragraph{Usage}
348This @posix_memalign@ takes two parameter.
349
350\begin{itemize}
351\item
352@ptr@: variable address to store the address of the allocated object.
353\item
354@align@: required alignment of the dynamic object.
355\end{itemize}
356
357It 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 returns a @NULL@ pointer.
358
359\subsection{\lstinline{T * valloc( void )}}
360This @valloc@ is a simplified polymorphic form of defualt @valloc@ (FIX ME: cite @valloc@). It takes no parameters as compared to the default @valloc@ that takes one parameter.
361\paragraph{Usage}
362@valloc@ takes no parameters.
363It returns a dynamic object of the size of type @T@ that is aligned to the page size. On failure, it returns a @NULL@ pointer.
364
365\subsection{\lstinline{T * pvalloc( void )}}
366\paragraph{Usage}
367@pvalloc@ takes no parameters.
368It 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 returns a @NULL@ pointer.
369
370\subsection{Alloc Interface}
371In 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.
372This interface helps programmers in three major ways.
373
374\begin{itemize}
375\item
376Routine Name: alloc interfce frees programmers from remmebring different routine names for different kind of dynamic allocations.
377\item
378Parametre Positions: alloc interface frees programmers from remembering parameter postions in call to routines.
379\item
380Object Size: alloc interface does not require programmer to mention the object size as \CFA allows allocator to determince the object size from returned type of alloc call.
381\end{itemize}
382
383Alloc 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. The new interfece has just one routine name alloc that can be used to perform a wide range of dynamic allocations. 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.
384
385\subsection{Routine: \lstinline{T * alloc( ... )}}
386Call to alloc wihout any parameter returns one object of size of type @T@ allocated dynamically.
387Only the dimension (dim) parameter for array allocation has the fixed position in the alloc routine. 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.
388alocc routine accepts six kinds of arguments. Using different combinations of tha parameters, different kind of allocations can be performed. Any combincation of parameters can be used together except @`realloc@ and @`resize@ that should not be used simultanously in one call to routine as it creates ambiguity about whether to reallocate or resize a currently allocated dynamic object. 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.
389
390\paragraph{Dim}
391This 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@.
392It represents the required number of members in the array allocation as in \CFA's aalloc (FIX ME: cite aalloc).
393This parameter should be of type @size_t@.
394
395Example: @int a = alloc( 5 )@
396This call will return a dynamic array of five integers.
397
398\paragraph{Align}
399This 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.
400
401Example: @int b = alloc( 5 , 64`align )@
402This call will return a dynamic array of five integers. It will align the allocated object to 64.
403
404\paragraph{Fill}
405This 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.
406Three types of parameters can be passed using `fill.
407
408\begin{itemize}
409\item
410@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.
411\item
412Object 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.
413\item
414Dynamic 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. In this case, the allocated memory is not filled recursively till the end of allocation. The filling happen untill the end object passed to @`fill@ or the end of requested allocation reaches.
415\end{itemize}
416
417Example: @int b = alloc( 5 , 'a'`fill )@
418This call will return a dynamic array of five integers. It will fill the allocated object with character 'a' recursively till the end of requested allocation size.
419
420Example: @int b = alloc( 5 , 4`fill )@
421This call will return a dynamic array of five integers. It will fill the allocated object with integer 4 recursively till the end of requested allocation size.
422
423Example: @int b = alloc( 5 , a`fill )@ where @a@ is a pointer of int type
424This call will return a dynamic array of five integers. It will copy data in a to the returned object non-recursively untill end of a or the newly allocated object is reached.
425
426\paragraph{Resize}
427This parameter is position-free and uses a backtick routine resize (@`resize@). It represents the old dynamic object (oaddr) that the programmer wants to
428\begin{itemize}
429\item
430resize to a new size.
431\item
432realign to a new alignment
433\item
434fill with something.
435\end{itemize}
436The data in old dynamic object will not be preserved in the new object. The type of object passed to @`resize@ and the returned type of alloc call can be different.
437
438Example: @int b = alloc( 5 , a`resize )@
439This call will resize object a to a dynamic array that can contain 5 integers.
440
441Example: @int b = alloc( 5 , a`resize , 32`align )@
442This call will resize object a to a dynamic array that can contain 5 integers. The returned object will also be aligned to 32.
443
444Example: @int b = alloc( 5 , a`resize , 32`align , 2`fill )@
445This call will resize object a to a dynamic array that can contain 5 integers. The returned object will also be aligned to 32 and will be filled with 2.
446
447\paragraph{Realloc}
448This parameter is position-free and uses a backtick routine @realloc@ (@`realloc@). It represents the old dynamic object (oaddr) that the programmer wants to
449\begin{itemize}
450\item
451realloc to a new size.
452\item
453realign to a new alignment
454\item
455fill with something.
456\end{itemize}
457The data in old dynamic object will be preserved in the new object. The type of object passed to @`realloc@ and the returned type of alloc call cannot be different.
458
459Example: @int b = alloc( 5 , a`realloc )@
460This call will realloc object a to a dynamic array that can contain 5 integers.
461
462Example: @int b = alloc( 5 , a`realloc , 32`align )@
463This call will realloc object a to a dynamic array that can contain 5 integers. The returned object will also be aligned to 32.
464
465Example: @int b = alloc( 5 , a`realloc , 32`align , 2`fill )@
466This call will resize object a to a dynamic array that can contain 5 integers. The returned object will also be aligned to 32. The extra space after copying data of a to the returned object will be filled with 2.
Note: See TracBrowser for help on using the repository browser.