Skip to content

Managing memory in extension packagesπŸ”—

HALCON provides a sophisticated memory management not only to handle iconic objects, but also to allocate/deallocate arbitrary data. Please use the corresponding HALCON Extension Package Interface routines exclusively. Do not create/destroy memory blocks on the heap with the standard routines of the operating system (like malloc and free) since the HALCON routines provide a caching mechanism, garbage collection for temporary data, and debugging facilities. See Managing memory for details on the caching mechanisms in HALCON.

We strongly recommend not to use global variables within HALCON operators. If they are not avoidable at least make them static within the file of usage. If even this is undesirable group them into structures to keep the number of global names small.

If you use static variables, be aware that they are shared between multiple threads. Please note that HALCON uses multithreading to exploit multi-processor or multi-core hardware. This means, that multiple instances of your code will actually share all the static variables! Furthermore, be aware that large static arrays consume a lot of memory – keep in mind that HALCON is a very large system enfolding hundreds of operators.

Temporary dataπŸ”—

Names

HAllocTmp, HFreeTmp, HFreeNTmp, HFreeUpToTmp, HFreeAllTmp,
HAllocRLTmp, HAllocRLNumTmp, HFreeRLTmp

Synopsis

HALCON stack management for temporary data
#include "Halcon.h"

Herror HAllocTmp(       Hproc_handle proc_handle,
                        void         **pointer,
                        size_t       size)

Herror HFreeTmp(        Hproc_handle proc_handle,
                        void         *pointer)

Herror HFreeUpToTmp(    Hproc_handle proc_handle,
                        void         *pointer)

Herror HFreeAllTmp(     Hproc_handle proc_handle)

Herror HAllocRLTmp(     Hproc_handle proc_handle,
                        Hrlregion    **region)

Herror HAllocRLNumTmp(  Hproc_handle proc_handle,
                        Hrlregion    **region,
                        size_t       size)

Herror HFreeRLTmp(      Hproc_handle proc_handle,
                        Hrlregion    *region)

HALCON stack management for temporary data shows HALCON routines to allocate/deallocate temporary memory blocks. Internally, those blocks are stored within a stack. Therefore, the memory must be deallocated in reverse order of it’s allocation. There are two major advantages of using these routines:

  • The underlying stacks are initially allocated as large blocks of memory. Thus, the memory is not fragmented and memory allocation is fast for subsequent calls.
  • An automatic garbage collection deallocates all temporary data after a HALCON operator was executed. This is especially of importance in case of an error during the execution of the operator (otherwise, the data should have been deallocated anyway).

HAllocTmp is used for arbitrary data with the corresponding deallocation routine HFreeTmp. HFreeUpToTmp deallocates all recently allocated blocks up to (and including) the specified block. HFreeAllTmp deallocates all temporary blocks.

HAllocRLTmp and HAllocRLNumTmp are convenience routines that are based on HAllocTmp. HAllocRLTmp allocates as much memory as is necessary for the largest region currently stored in the HALCON database of iconic objects (the minimal size is DEF_RL_LENGTH = 50000 chords). Using HIncrRL (HIncrRL), HAllocRLTmp allocates more memory. HAllocRLNumTmp allows you to determine the size of memory to be allocated by specifying the number of chords. Furthermore, HAllocRLTmp and HAllocRLNumTmp initialize the data structure Hrlregion for the new region (see Region data (Hrlregion) for a description of Hrlregion). Note that since these routines are based on HAllocTmp the corresponding memory blocks are interleaved with the blocks allocated directly via HAllocTmp. This has to be considered while deallocating the corresponding memory.

Temporary data on arbitrary heap positionsπŸ”—

Names

HAllocLocal, HReallocLocal, HFreeLocal,
HAllocRLLocal, HAllocRLNumLocal, HReallocRLNumLocal, HFreeRLLocal

Synopsis

Temporary data on arbitrary heap positions
#include "Halcon.h"

Herror HAllocLocal(        Hproc_handle proc_handle,
                           size_t       size,
                           void         **pointer)

Herror HReallocLocal(      Hproc_handle proc_handle,
                           void         *pointer
                           size_t       size,
                           void         **new_pointer)

Herror HFreeLocal(         Hproc_handle proc_handle,
                           void         *pointer)

Herror HAllocRLLocal(      Hproc_handle proc_handle,
                           Hrlregion    **region)

Herror HAllocRLNumLocal(   Hproc_handle proc_handle,
                           Hrlregion    **region,
                           size_t       num)

Herror HReallocRLNumLocal( Hproc_handle proc_handle,
                           Hrlregion    *region
                           size_t       num_new,
                           Hrlregion    **new_region)

Herror HFreeRLLocal(       Hproc_handle proc_handle,
                           Hrlregion    *region)

The temporary data management routines described so far use a stack. This is of advantage concerning runtime, but it lacks flexibility if you do not want to deallocate memory in a fixed order again. Therefore, HALCON also provides routines for allocating temporary memory on an arbitrary position of the heap, see Temporary data on arbitrary heap positions. Memory blocks allocated by HAllocLocal can be deallocated by HFreeLocal in an arbitrary order. However, similar to the stack-based temporary data management, all these blocks are automatically deallocated at the end of a HALCON operator. Again this mainly aims on preventing memory leaks in case of errors. As usual, the routine HReallocLocal is used to allocate a new memory block with modified size while preserving the data of the original memory block. The latter is deallocated. So never try to access pointer subsequent to HReallocLocal– use new_pointer exclusively.

The convenience routines HAllocRLLocal , HAllocRLNumLocal HReallocRLNumLocal, and HFreeRLLocal are used for handling temporary region data based on HAllocLocal. Otherwise their behavior is similar to HAllocRLTmp etc., see above. E.g., using HIncrRL (HIncrRL), HAllocRLLocal allocates more memory. However, note that it is possible to change the size of regions (i.e., the number of chords) using this set of routines (HReallocRLNumLocal) since the underlying memory blocks are not allocated within the internal stacks.

Handle dataπŸ”—

Name

HAllocOutputHandle

Synopsis

Memory management for handles
#include "Halcon.h"

Herror HAllocOutputHandle(        Hproc_handle    proc_handle,
                                  int             par,
                                  Hphandle        elem,
                                  H_HANDLE_TYPE   HHandleInfo)

The routine HAllocOutputHandle allocates one handle in the output control parameter par. HHandleInfo holds handle type information. elem is modified to point to where the new tool can be allocated.

The output control variable gains ownership of the pointer in elem. When aborting an operator with an error, the value must not be cleared inside the operator’s code, but will be cleared automatically when cleaning the output control variable.

Global dataπŸ”—

The HALCON Extension Package Interface also provides routines for globally allocating/deallocating memory (see General memory management within HALCON and General memory management for region data). They work similar to the standard C procedures malloc and free, but use a caching mechanism for small data blocks and provide additional debugging information.

Names

HAlloc, HRealloc, HFree, HNewImage, HNewImagePtr,
HAllocXLDCont, HFreeXLDCont

Synopsis

General memory management within HALCON
#include "Halcon.h"

Herror HAlloc(        Hproc_handle proc_handle,
                      size_t       size,
                      void         **pointer)

Herror HRealloc(      Hproc_handle proc_handle,
                      void         *pointer
                      size_t       size,
                      void         **new_pointer)

Herror HFree(         Hproc_handle  proc_handle,
                      void          *pointer)

Herror HNewImage(     Hproc_handle  proc_handle,
                      Himage        *image,
                      int           kind,
                      HIMGDIM       width,
                      HIMGDIM       height)

Herror HNewImagePtr(  Hproc_handle  proc_handle,
                      Himage        *image,
                      int           kind,
                      HIMGDIM       width,
                      HIMGDIM       height,
                      void          *data,
                      bool          initImg)

Herror HAllocXLDCont( Hproc_handle  proc_handle,
                      Hcont         **cont,
                      HITEMCNT      num_points)

Herror HFreeXLDCont(  Hproc_handle  proc_handle,
                      Hcont         *cont)

Note that in contrast to HAllocLocal, memory allocated by HAlloc is not deallocated automatically after the execution of a HALCON operator. Thus, this routine should be used to allocate global data. For example, all the iconic objects stored in the HALCON database of iconic objects are allocated with this routine (see the Reference of the Extension Package Interface).

HNewImage allocates raw image data inside the data structure Himage (see Pixel data (Himage)) based on HAlloc.1 Furthermore, image is initialized and the timestamp is set to the current time. The image matrix itself is initialized with 0 if 'init_new_image' has been set to 'true' using the HALCON operator set_system. This flag can be read inside HALCON using the Extension Package Interface call HReadGV.

HReadGV(proc_handle, HGInitNewImage, &init_new_img);

with init_new_img of type bool and set

HWriteGV(proc_handle, HGInitNewImage, {true,false});

Thus, it is possible to buffer the global setting of this flag, set the flag to false prior to HNewImage, and restore the old value afterward, if you would like to prevent an initialization in any case.

HNewImagePtr does not allocate memory for the image data, but inserts the pointer data in the Himage structure image instead. For this routine, the initialization of the image data is controlled via the parameter initImg.

Note

You will encounter program crashes during deallocation of image objects if you insert a memory block that has not been allocated via HAlloc in the underlying Himage structure (see, for example, HPutImage in Creating objects and writing output object parameters).

For both HNewImage and HNewImagePtr the pixel type of the raw data within image is specified by the parameter kind. See Definitions of pixel types for the supported values.

HAllocXLDCont allocates an XLD contour of type Hcont (see XLDs (Hcont, Hpoly)) including memory for num_points contour points.2 Internally, this routine is based on HAlloc. HFreeXLDCont is used to deallocate a contour again (including all the points and all attributes defined for cont, see XLDs (Hcont, Hpoly)).

Names

HAllocRL, HAllocRLNum, HReallocRLNum, HFreeRL

Synopsis

General memory management for region data
#include "Halcon.h"

Herror HAllocRL(      Hproc_handle proc_handle,
                      Hrlregion    **region)

Herror HAllocRLNum(   Hproc_handle proc_handle,
                      Hrlregion    **region,
                      size_t       len)

Herror HReallocRLNum( Hproc_handle proc_handle,
                      Hrlregion    *region
                      size_t       len,
                      Hrlregion    **new_region)

Herror HFreeRL(       Hproc_handle proc_handle,
                      Hrlregion    *region)

The convenience routines HAllocRL , HAllocRLNum, HReallocRLNum, and HFreeRL (see General memory management for region data) are used for handling global region data based on HAlloc. Otherwise, their behavior is similar to HAllocRLTmp etc. E.g., using HIncrRL (HIncrRL), HAllocRL allocates more memory, see Temporary data. Note that it is possible to change the size of regions (i.e., the number of chords) using HReallocRLNum.

DebuggingπŸ”—

The HALCON memory management provides debugging mechanisms. The debugging is enabled with set_check('memory'), and can be switched off with set_check('~memory').

Every time a memory block is deallocated, a couple of consistency checks are performed automatically. Moreover, the consistency of memory blocks can be checked for debugging reasons at any time using specific Extension Package Interface routines, see below.

Names

HTestMem, HTestPtr, HTestAllTmp, HTestTmp

Synopsis

HALCON memory management: Check of consistency
#include "Halcon.h"

Herror HTestMem(    void)

Herror HTestPtr(    void          *pointer)

Herror HTestAllTmp( Hproc_handle  proc_handle)

Herror HTestTmp(    Hproc_handle  proc_handle,
                    void          *pointer)

HTestMem checks all the memory allocated with HAlloc or HAllocLocal, whereas HTestPtr checks only the specified memory block, which must have been allocated with HAlloc.
Similar to that, HTestAllTmp checks all the memory allocated via HAllocTmp, and HTestTmp checks the specified block.

With any failure of the consistency check, the routines return an error code (H_ERR_ICM – inconsistent memory). Furthermore, if the global variable HDoLowError is set to true, they display a description of the error either on stderr (Linux) or within an alert box (Windows). This variable can be set in an application with the operator set_system('do_low_error','true'/'false') or used directly inside the newly written operator.


  1. HNewImage does not allocate memory for the Himage structure itself. β†©

  2. In contrast to HNewImage and HNewImagePtr, HAllocXLDCont also allocates memory for the structure Hcont itself, not only for the data inside that structure. β†©