1 The Table Visualizer
The Table Visualizer is a tool that enables the user to examine ETS and Mnesia tables on any (connected) node in the currently running Erlang system. Once a certain table has been opened in the tool, the content may be viewed in various levels of detail. The content may also be sorted, using any element as key, and it is also possible to search for a specified object or element. The table may be polled anytime, either regularly, at specified intervals, or manually. New and deleted objects, as well as those altered, are marked with characteristic colors.
Information about the table itself (permissions, storage type, and so on) may also be obtained.
1.1 Terminology and Background
To avoid confusion, we have to distinguish between the actual table, i.e., the data stored in ETS or Mnesia, and the image of the table, i.e., the data shown in the Table Visualizer. The image of the table is simply a copy of the actual table, and can be manipulated in a number of ways, for example sorted. It follows that these manipulations in no way affects the actual table!
The expression poll the table is used for the operation of scanning through the content of the actual table (in order to keep the image of the table consistent with the actual table).
The ETS and Mnesia modules provides the user with the ability to store vast quantities of data in an Erlang system, the data organized as dynamic, unordered tables. The ETS facility stores tuples, while Mnesia stores records. Each tuple consists of one or more elements; each record consists of one or more fields. It should be noted that, since records are implemented as tuples, with the record name as the first element, the first field of a record becomes the second element in the corresponding tuple!
In the following, all table objects are mainly referred to as tuples, regardless of the table type.For further information about ETS and Mnesia, please see the manual pages or the reference manual.
1.2 Starting the Table Visualizer
The Table Visualizer tool is started by giving the command
tv:start().The window that appears, is hereafter referred to as the Table Visualizer main window. It consists of:
- a menubar.
- a toolbar with buttons providing shortcuts to the menubar options. If the cursor rests on any button, a so-called toolbar tip, explaining the button, will appear.
(In the picture below, the cursor has lingered on the Open Table button for a while.)
- a content field, showing the content of a specified row or cell (see below for a detailed explanation).
- a grid, i.e., a multicolumnar array, where table data will be shown, when a table has been opened. Each square in the grid is called a cell.
The Table Visualizer Main Window.1.3 How to Open a Table
Whenever a table shall be opened, the Open Table... option in the File menu shall be chosen (or the corresponding button in the toolbar shall be pressed). This makes the Open Table window to appear.
1.3.1 The Open Table Window
The Open Table window presents the tables - both readable and unreadable ones - that currently exists at a chosen node. The table possible to choose are presented to the left in the window, while the corresponding tables are shown to the right. (Once any node in the list has been clicked on, the table list is immediately updated.)
The Open Table Window.The ETS tables are presented with their names and their parents, i.e., the processes that created each of the tables. The Mnesia tables are only presented with thir names, since the concept of a parent isn't meaningful in this case.
Tables having identical names are numbered, thereby making it possible to distinguish between them. However, it shall be noted that the numbering order depends on the creation order of these tables. This means that the numbering is by no means absolute: should one of the numbered tables die, the numbering of the other tables will change. For example: if, in the picture above, the table 'gtk_db #3' should die, the table 'gtk_db #5' will, the next time the Open Table window is opened, be called 'gtk_db #4', and so on.
The table to be opened may be chosen by clicking on a name shown in the (readable) tables list, thereupon pressing the Open button. However, this operation may fail, should the table no longer exist, or if no table has been chosen. In this case an error message will be presented in the window, whereupon the user has to choose a (new) table name, or cancel the Open Table operation.
The Open Table Window when trying to open a non-specified table.On the other hand, if the Open Table operation is successful, an image of the table will be created in the Table Visualizer, and presented in the main window grid.
1.4 How Table Data Is Presented
Each object in the table is presented on a row of its own in the grid. Each element in the object is presented in a cell of its own.
The Table Visualizer Main Window, when a table has been opened.The colors on the vertical buttons to the left of the grid show the status of the object on that very row: a bright red color indicates that the object just has been inserted, while a bright green color indicates that the object has been changed. The color fades away, shade by shade, every time the actual table is polled, until the normal background color is encountered.
When an object has been deleted, the color of the corresponding vertical button turns to black. The next time the table is polled, the object will be removed from the grid.
The Table Visualizer Main Window, with new, changed, and deleted objects.Normally, new objects are placed at the end of the grid, while all other objects maintain their positions between successive polls. However, when sorting mode has been ordered, all objects, even new ones, are placed at the correct position according to the sorting ordered (see also below).
Immediately above the horizontal buttons, one or more keys may appear. These keys indicates which elements that are used as indices in the ETS/Mnesia table, i.e., which fields that are used by ETS/Mnesia as search keys when looking up data.
The grid columns may be resized, by clicking and dragging on the small black resize areas between any two horizontal buttons.
The rows are enumerated, as a help when navigating through the table. Note: it shall not be assumed that these numbers correspond to the placement of the objects in the actual table! The row numbers, as presented in the Table Visualizer, are only temporary, and only valid within the Table Visualizer!
The number on the vertical scrollbar corresponds to the number the uppermost row has (or will have).The number shown on the horizontal scrollbar relates to the leftmost column shown.
1.5 How to Poll the Table
The table is polled whenever the Poll Table option in the Options menu is chosen (or the Poll Table toolbar button is pressed).
The user may also choose to let the Table Visualizer poll the table at regular intervals. This is done via the Set Poll Interval... option in the Options menu, which causes the Set Poll Interval window to appear.In the Set Poll Interval window the user selects whether manual or automatic polling shall be used, and, in the automatic polling case, the poll interval.
The Set Poll Interval Window.It shall be noted that, in the case of a large table (or a slow computer/operating system), a short poll interval may cause the Table Visualizer to be flooded, i.e., the data resulting from one poll hasn't been fully treated and presented when the data from the next poll arrives. The user is therefore kindly requested to use the automatic polling facility with care!
1.6 How to Search For Objects
One may search for an object, by choosing the Search Object option in the Tools menu (or by pressing the Search Object toolbar button). In the Search Object window that appears, any valid Erlang term may be entered, whereupon all objects containing (or consisting of) this term will be shown.
The Search Object Window.In the search result list, by clicking on any object, the Table Visualizer will immediately scroll to the corresponding row in the table shown. This enables the user to in a very powerful way quickly find the objects he's interested in.
The Search Object Window interworking with the Table Visualizer Main Window.1.7 How to Mark Table Data
One may mark a row or a column by clicking on the buttons to the left and above the grid, respectively. A single cell is marked by clicking on it. Even empty rows and columns may be marked; an empty cell cannot be marked - on the contrary, by clicking on an empty cell, all marks are removed.
Marks are indicated by a cyan blue colour.
The Table Visualizer Main Window: a row has been marked.When a row or a cell has been marked, the content will be shown in the content field, together with an indication of the row (and column when applicable) the marked area corresponds to. Should the object be very big, only a fraction of it may be shown in this field; also, strings will be shown as lists consisting of ASCII numbers. By clicking on the down-arrow button to the right of the content field, a pop-up content field will be shown, where the whole marked object may be viewed, with strings having the proper format. The content of this pop-up field may be marked and copied to other windows, e.g., an editor.
The Table Visualizer Main Window: the pop-up content field.A marked column may be subject to sorting, see below. When sorting is ordered, marks are removed at each polling of the table (because of the difficulties to keep track of a certain object, or element, in this case).
1.8 How to Sort Table Data
The image of the table may be sorted in rising or falling order, using any element as sorting key. The element desired is chosen by marking the corresponding column, and then choose (either via the Tools menu, or via the toolbar buttons) any of the sorting options available, i.e., sorting in rising or falling order. The color of the column button will then change to gold, to indicate that this column is the basis for the sorting currently chosen.
The Table Visualizer Main Window, sorting by the first column ordered.Should no column have been marked, when sorting is ordered, the first element in each object (i.e, tuple) will be used as sorting key if the table is an ETS table; the second element (i.e., the first field in the record) will be used if the table is a Mnesia table.
Even columns with no elements in them may be subject to sorting. In this case the whole object is used as the sorting key.
When sorting is ordered, new elements will be inserted according to the current sorting mode. When the sorting is interrupted (via the No Sorting option), the current image of the table keep the current order, but new elements will from now on once again be inserted at the end of the image of the table.
1.9 How to Obtain Table Information
Information about the actual table is obtained via the View menu (or via the Table Info toolbar button). The information is printed in a separate window, with similar pieces of information grouped together on "flap cards" of their own. By clicking on a flap, the information on the corresponding card is made visible.
The Table Information Window, showing information about a Mnesia table.1.10 The Main Window Menus
The Table Visualizer Main Window offers the following menus:
1.10.1 The File Menu
- Open Table...
- Open an ETS or Mnesia table.
- Exit
- Terminate the Table Visualizer tool.
1.10.2 The Tools Menu
- Search Object
- Enables search for objects containing (or consisting of) a specified Erlang term. The search result may be used for quick navigation in the table.
- Sort Rising Order
- Shows the table content sorted in rising order. New objects will be shown with correct placement as long the as the sorting is going on.
Please note that it is only the image of the table that is affected, not the table itself!
- Sort Falling Order
- Shows the table content sorted in falling order. New objects will be shown with correct placement as long the as the sorting is going on.
- No Sorting
- Sorting mode is leaved. New objects will be shown last in the table. However, older objects will remain in the position they had when the sorting mode was leaved, i.e., their placement will not reflect their actual placement in the ETS/Mnesia table.
1.10.3 The Options Menu
- Poll Table
- An explicit order to poll the table, i.e., to scan the content.
- Set Poll Interval...
- Choose between manual and automatic polling. In the case of automatic polling, the user gets the opportunity to choose the polling interval.
1.10.4 The View Menu
- Table Info
- Opens the Table Information window, which shows the available information about the table currently opened. (If no table is opened, the action is ignored.)
1.10.5 The Help Menu
- Help
- Shows the help (about Table Visualizer usage) that is available. (The help will be shown in the Netscape Internet browser, if available.)