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
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
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
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
This TCL extension returns in the TCL interp, a count of all bytes on the
free memory pool.
TCL SYNTAX:
memBytesInPool
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
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]
This TCL extension returns in the TCL interp, a count of the number of
blocks on the allocated memory pool.
TCL SYNTAX:
memNumBlocksInUse
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
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
This TCL extension returns in the TCL interp, the serial number of the latest
allocated block.
TCL SYNTAX:
memSerialNumber
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>
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
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
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.
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]
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