DMDMEMORY(1)

NAME
dmdmemory - 630 MTG memory profiler

SYNOPSIS
dmdmemory [ -c ]

DESCRIPTION
Memory in the 630 MTG terminal is divided into two types of memory which can be requested by user level function calls:

.   non-compactible alloc memory [alloc(3R)],

.   garbage-collectible gcalloc memory [gcalloc(3R)].

The alloc memory pool starts from the low addressed end of the user memory pool and grows upward. The gcalloc memory pool begins at the other end of the user memory pool (i.e. at the highest address) and grows downward. The mobile boundaries of the alloc and gcalloc pools are named respectively alloclevel and gclevel.

To contain fragmentation due to the non-compactibility of the alloc memory, there is an alloclimit which restricts the expansion of the alloc pool.

In order to make better use of alloc fragments, the 630 MTG memory allocation scheme converts a gcalloc request that cannot fit into the gcalloc pool to an alloc request. If there is a fragment big enough to satisfy the request, it becomes a gcastray block. Gcastray memory is of the same type as gcalloc but resides inside the alloc pool. Note that this type of memory is only known by the terminal memory allocation system and cannot be requested directly by a user level function call.

The dmdmemory utility presents a graphical representation of the memory usage in the 630 MTG terminal. A user is able to monitor all three types of memory with a scope (or zoom) facility, modify the alloclimit, and look at the memory or stack usage of a particular process.

The -c option causes dmdmemory to be cached in the 630 MTG application cache.

The window size used by dmdmemory is fixed. If the window size is not correct, a Core icon and a "menu on button 2" string are displayed. The window must be reshaped if this appears by selecting either the reshape option from the mouse button 2 menu or the reshape function from the mouse button 3 menu. If reshape is selected from the button 2 menu, the window is automatically reshaped to the proper size. If the reshape function from the button 3 menu is selected, the default window size presented is the correct window for dmdmemory.
 If a different window size is swept, the core icon and message string are again displayed. Similarly, if at any time the window is reshaped back to an incorrect size, the core icon and string are again displayed. When the window size is incorrect, dmdmemory is largely inactive, so at times it may be desirable to place dmdmemory in this state to free cpu resources for other processes. Reshaping the window back to the correct size reactivates dmdmemory.

In the working mode, the dmdmemory window contains the following, from top to bottom:

    — Three numerical upper fields which are, from left to right:

    the scoped number of alloc blocks.
    the scoped number of gcastray blocks,
    the scoped number of gcalloc blocks.

    The number of scoped blocks is the number of those bolcks that fall within the range of memory represented by the dmdmemory window.

    —A bar graph which represents the user memory pool in
    the viewing scope. Alloc blocks are reverse-videoed, gcastray blocks are background textured, and gcalloc blocks are grey shaded. To help the visualization, the bar graph is marked by 100 tick marks, 8 pixels apart. The alloclimit is represented by a longer vertical bar.

    — Five numerical lower fields which are, from left to right:

    the starting address of the viewing scope,
    the alloclevel address,
    the alloclimit address,
    the gclevel address,
    the ending address of the viewing scope.

    In full view the viewing scope addresses are the same as the boundary addresses of the total user memory pool. In a scoped view, the alloclevel, alloclimit or gclevel addresses may not be displayed if they are out of the viewing scope.

    —An alphanumeric field which displays information or
    help messages. Information includes the scope setting (full view or scoped view) and the number of bytes per pixel. Help messages depend on the command selected.

The dmdmemory facility supports six commands, all accessed from mouse button 2. Note that when a command is being executed, the dmdmemory window cannot be reshaped. The six commands are described below.

  Base
This command toggles between decimal and hexadecimal bases. Hexadecimal numbers are preceded by a "0x" prefix.

  Process
This command changes the mouse cursor to a "target" cursor and asks the user to pick a window by clicking button 1 over it. Picking nothing (i.e., the screen background) or clicking other buttons will cancel the command.

Clicking button 1 over a window will cause the three numerical upper fields to blink. They now represent scoped amounts of alloc, gcastray and gcalloc memory used by the process running inside the selected window. The display inside the bar graph also blinks to mark the corresponding positions of these memory blocks. The alphanumeric field displays the address of the process.

Clicking or holding any button stops the blinking, exits this command mode, and returns dmdmemory to the normal viewing mode.

If a cached process is selected, dmdmemory displays only that memory used by the process that was allocated via an alloc ro gcalloc procedure call. The memory actually occupied by the process code and data is not displayed by the process command.

  Stack
This command is similar to the process command, except that the information now deals with the stack assigned to the specified process.

Since the process stack is alloc'ed, only the alloc field can have a non-zero value (assuming the stack is inside the viewing scope). The alphanumeric field shows how many bytes of its stack a process has used.

The stack command displays the amount of assigned stack space whether the process is cached or not.

  Scope
This command allows the user to zoom in (or out) in order to have a closer look at a particular region of the user memory pool.

When this command is selected, a full-length vertical bar blinks at the left side of the bar graph. The user drags the vertical bar by holding down button 1. Note that the starting address of the viewing scope (left-most lower numerical field) also blinks, and changes with new values corresponding to the dragged bar positions. Releasing button 1 will select the new starting address of the viewing scope.

The ending address of the viewing scope is modified in the same manner with a blinking bar appearing at the right end of the bar graph. If this bar is positioned to the left of the previous one, dmdmemory takes it as a zoom-out, back to full view setting. Otherwise, the action results in a zoomed-in (or scoped) view of the memory pool, and the numerical fields are updated accordingly. Note that some addresses in the lower fields are now out of scope and therefore are not displayed.

During this process, if any button other than button 1 is pressed and held, the command is aborted and the current viewing scope is retained.

The smallest scope is one byte per pixel. Attempts to zoom in further will automatically re-expand the viewing scope to this minimum setting.

  Limit
This command allows the user to modify the value of alloclimit.

When this command is selected, the vertical bar which represents the position of alloclimit in the graphical bar starts to blink. The same thing happens to the alloclimit numerical field (middle lower field). To modify its value, the user holds down button 1 and drags the vertical bar to new positions. The numerical field changes accordingly. Note that alloclimit cannot go lower than alloclevel; otherwise, some alloc blocks would be out of the alloc pool.

This command does nothing if the alloclimit is not within the scope.

Caution: a value for alloclimit that is too low restricts the expansion of the alloc pool, causing alloc requests to fail.

FILES
$DMD/lib/dmdmemory.m    downloadable file

SEE ALSO
ucache(1), alloc(3R), gcalloc(3R).