HALCON Extension Package Programmer's Manual

40 CHAPTER 3. STYLE GUIDE FOR PROGRAMMINGFig. 3.1 shows HALCON routines to allocate/deallocate temporary memory blocks. Internally,those blocks are stored within a stack. Therefore, the memory must be deallocated in reverseorder of it’s allocation. There are two major advantages of using these routines:¯ The underlying stacks are initialy allocated as large blocks of memory. Thus, the memoryis not fragmented and memory allocation is fast for subsequent calls.¯ An automatic garbage collection deallocates all temporary data after a HALCON operatorwas executed. This is especially of importance in case of an error during the execution ofthe operator (otherwise, the data should have been deallocated anyway).ÀÐÐÓÌÑÔ is used for arbitrary data with the corresponding deallocation routine ÀÖÌÑÔ.ÀÖÆÌÑÔ deallocates the last ÒÙÑ blocks allocated by ÀÐÐÓÌÑÔ, ÀÖÍÔÌÓÌÑÔ deallocatesall recently allocated blocks up to (and including) the specified block. ÀÖÐÐÌÑÔ deallocatesall temporary blocks.ÀÐÐÓÊÄÌÑÔ and ÀÐÐÓÊÄÆÙÑÌÑÔ are convenience routines that are based on ÀÐÐÓÌÑÔ.ÀÐÐÓÊÄÌÑÔ allocates as much memory as is necessary for the largest region actuallystored in the HALCON data base (the minimal size is ÊÄ ÄÆÌÀ = 50000 chords).ÀÐÐÓÊÄÆÙÑÌÑÔ allows to determine the size of memory to be allocated by specifying thenumber of chords. Furthermore, ÀÐÐÓÊÄÌÑÔ and ÀÐÐÓÊÄÆÙÑÌÑÔ initialize the data structureÀÖÐÖÓÒ for the new region (see section 4.2 for a description of ÀÖÐÖÓÒ). Note, thatsince these routines are based on ÀÐÐÓÌÑÔ the corresponding memory blocks are interleavedwith the blocks allocated directly via ÀÐÐÓÌÑÔ. This has to be considered while deallocatingthe corresponding memory.Temporary data on arbitrary heap positionsThe temporary data management routines described so far use a stack. This is of advantageconcerning runtime, but it lecks flexibility if you do not want to deallocate memory in a fixedorder again. Therefore, HALCON also provides routines for allocating temporary memory onan arbitrary position of the heap, see Fig. 3.2. Memory blocks allocated by ÀÐÐÓÄÓÐ can bedeallocated by ÀÖÄÓÐ in an arbitrary order. However, similar to the stack-based temporarydata management, all these blocks are automatically deallocated at the end of a HALCONoperator. Again this mainly aims on preventing memory leaks in case of errors. As usual,the routine ÀÊÐÐÓÄÓÐ is used to allocate a new memory block with modified size whilepreserving the data of the original memory block. The latter is deallocated. So never try toaccess ÔÓÒØÖ subsequent to ÀÊÐÐÓÄÓÐ – use ÒÛ ÔÓÒØÖ exclusively.The convenience routines ÀÐÐÓÊÄÄÓÐ, ÀÐÐÓÊÄÆÙÑÄÓÐ, ÀÊÐÐÓÊÄÆÙÑÄÓÐ, andÀÖÊÄÄÓÐ are used for handling temporary region data based on ÀÐÐÓÄÓÐ. Otherwisetheir behaviour is similar to ÀÐÐÓÊÄÌÑÔ etc., see above. However, note that it ispossible to change the size of regions (i.e., the number of chords) using this set of routines(ÀÊÐÐÓÊÄÆÙÑÄÓÐ) since the underlying memory blocks are not allocated within the internalstacks.HALCON Extension Package Interface / 2000-11-16