TCL Expressions for Dervish Memory Management and Garbage Collection


Dervish provides a rich set of TCL extensions for memory management and garbage collection. Each of the TCL extension is documented below, and wherever appropriate, examples are provided.

The TCL level help facility is memory

For an overview of DERVISH Memory Management and Garbage Collection, and the definition of some commonly used terms, press here.

The following TCL extensions are provided. All of these extensions return a TCL_OK on a successful completion. If an error occurred, they return TCL_ERROR, and the Interp result will contain a string detailing the reason for the error.

  • memAMPSize
  • memBlocksGet
  • memBlocksPrint
  • memBytesInPool
  • memBytesInUse
  • memFreeBlocks
  • memNumBlocksInUse
  • memNumFrees
  • memNumMallocs
  • memSerialNumber
  • memStatsPrint
  • memTotalBytes
  • memActualBytes
  • memCheck
  • memBlocksizeSet
  • memDefragment

  • memAMPSize

    Get, as a TCL return, the number of allocation requests that are current. In other words, no request for freeing the memory has been made. This value is equivalent to the number of allocation requests minus the number of free requests. TCL SYNTAX: memAMPSize

    memBlocksGet

    Get, as a TCL list of lists, all the memory blocks allocated. Each list will have the following form:
                 {serial-number address size [handle type]} { ... }
    
    where serial-number is the serial number of the memory block, address is the starting address of the memory block, size is the size (in bytes) of the memory block, handle is a handle (if any) bound to the memory block, and type identifies the memory block as being a REGION, MASK, CHAIN, etc. The last two elements of the list are optional. TCL SYNTAX: memBlocksGet

    memBlocksPrint

    This extension is analogous to memBlocksGet except that instead of displaying the allocated memory pool as a TCL list, it formats it in a pretty fashion and displays it on the standard output. TCL_SYNTAX: memBlocksPrint

    memBytesInPool

    This TCL extension returns in the TCL interp, a count of all bytes on the free memory pool. TCL SYNTAX: memBytesInPool

    memBytesInUse

    This TCL extension returns in the TCL interp, a count of all bytes on the allocated memory pool; i.e the total in bytes of all memory blocks being used at that instant in time. Note that that result of this extension and the result of memBytesInPool yields the total number of bytes being managed by Dervish. TCL SYNTAX: memBytesInPool

    memFreeBlocks

    This TCL extension performs the unenvious task of garbage collection in Dervish Memory management TCL extensions. Unlike other operating environments (LISP, SmallTalk, emacs), where garbage collection is an automatic procedure, Dervish garbage collection is user driven.

    Central to the theme of garbage collection in Dervish is the idea that each memory block allocated has a unique serial number associated with it. Garbage collection then simply becomes an issue of deallocating all memory blocks bounded (inclusively) by two serial number.

    To deallocate a single memory block, set HIGH_BOUND to be the same as LOW_BOUND.

    TCL SYNTAX: memFreeBlocks <LOW_BOUND> <HIGH_BOUND> <LOW_BOUND> : deallocate blocks starting with this serial number <HIGH_BOUND> : stop deallocating blocks whose serial number is greater then HIGH_BOUND EXAMPLE: dervish> set lower [memSerialNumber] 3 dervish> regNew 100 100 h1 dervish> maskNew 50 50 h2 ... dervish> memFreeBlocks [expr $lower+1] [memSerialNumber]

    memNumBlocksInUse

    This TCL extension returns in the TCL interp, a count of the number of blocks on the allocated memory pool. TCL SYNTAX: memNumBlocksInUse

    memNumFrees

    This TCL extension returns in the TCL interp, a count of the number of a number of times shFree(), the Dervish memory deallocation routine was called. TCL SYNTAX: memNumFrees

    memNumMallocs

    This TCL extension returns in the TCL interp, a count of the number of a number of times shMalloc(), the Dervish memory allocation routine was called. TCL SYNTAX: memNumMallocs

    memSerialNumber

    This TCL extension returns in the TCL interp, the serial number of the latest allocated block. TCL SYNTAX: memSerialNumber

    memStatsPrint

    This TCL extension prints on the standard output, some interesting memory allocation and usage statistics. TCL SYNTAX: memStatsPrint EXAMPLE: dervish> memStatsPrint Number of memory allocation requests: 16 Number of memory de-allocation requests: 15 Total bytes currently in use: 20 Total bytes in Free Memory Pool: 33692 Percentage of memory allocation requests satisfied from Free Memory Pool: 50.00 % Percentage of memory allocation requests satisfied from the Operating System: 50.00 % dervish>

    memTotalBytes

    This TCL extension returns in the TCL interp, a count of the number of total bytes allocated so far from the operating system, including memory not yet used to satisfy any shMalloc request as well as book-keeping headers. TCL SYNTAX: memTotalBytes

    memActualBytes

    This TCL extension returns in the TCL interp, a count of the number of total bytes given to shMalloc. Note that this count will be bigger then you would expect (if you were keeping tabs) since it also includes all the bytes for internal bookkeeping as well. TCL SYNTAX: memActualBytes

    memCheck

    Check the heap administered by shMalloc for corruption. TCL SYNTAX: memCheck [-abort] If any corrupt blocks are detected, memCheck returns an error. If -abort is provided, shFatal() is called instead.

    Note that if the heap is corrupted, calling memCheck may generate a segmentation violation --- but of course this is merely a symptom of an already existing bug.


    memBlocksizeSet

    Set the minimum size in bytes for a malloc() request, the balance of any memory requested goes onto the internal free list g_mallocList

    Returns the old value; as a special case is [size] is omitted only return it; it's not changed.

    The initial value of the memory block size is 0; the significance of the call is explained under memDefragment.

    SYNOPSIS: memBlocksizeSet [size]

    memDefragment

    Defragment the free memory list.

    You have two options; if you specify -free, simply go through the free lists freeing all allocated blocks back to the O/S, so as to give it a chance to defragment for us. To use this option you must not have called memBlocksizeSet or chaos will ensue, as some of the freed blocks will not have been allocated directly by malloc.

    Otherwise, go through the FMP looking for adjacent blocks which are then merged together, and if possible returned to g_mallocList (the MMP in the language of the introduction). This will only work if large blocks have been allocated from the O/S; i.e. if you called memBlocksizeSet with a largish argument (a few Mby?).

    SYNOPSIS: memDefragment [Options] Options: -free Call free() on any unused blocks