Using the Event Table

The Event Table provides a unified method for controlling the execution of a program. Creating an event in any of the ways discussed later in this chapter adds an event to the list in this table. You can also display the Event Table and use it to:

• Add new events

• Delete existing events

• Edit existing events

You display the Event Table by choosing the Event Table selection from the Events menu.

This section describes the general process of using the Event Table.

Description of the Event Table

Figure 4-1 shows the Event Table.

Figure 4-1 Event Table

The top area of the Event Table is the event list--a scrollable region in which events are listed. When you execute the program, Prism uses the events in this list to control execution. Each event is listed in a format in which you could type it as a command in the command window. It is prefaced by an ID number assigned by Prism. For example, in Figure 4-1, the events have been assigned the IDs 1 and 2.

The middle area of the Event Table is a series of fields that you fill in when editing or adding an event; only a subset of the fields is relevant to any one event. The fields are:

• ID - This is an identification number associated with the event. You cannot edit this field.

• Location - Use this field to specify the location in the program at which the event is to take place. Use the syntax "filename":line-number to identify the source file and the line within this file. If you just specify the line number, Prism uses the current file. There are also three keywords you can use in this field:

  • Use eachline to specify that the event is to take place at each line of the program; this is the default.

  • Use eachinst to specify that the event is to take place at each assembly-language instruction.

  • Use stopped to specify that the event is to take place whenever the program stops execution.

• Watch - Use this field to specify a variable or expression whose value(s) are to be watched; the event takes place if the value of the variable or expression changes. (If the variable is an array or a parallel variable, the event takes place if the value of any element changes.) This slows execution considerably.

• Actions - Use this field to specify the action(s) associated with the event. The actions can be most Prism commands; separate multiple commands with semicolons. (The commands that you can't include in the Actions field are attach, core, detach, load, return, run, and step.)

• Condition - Use this field to specify a logical condition that must be met if the event is to take place. The logical condition can be any language expression that evaluates to true or false. See " Writing Expressions in Prism" for more information about writing expressions in Prism. Specifying a condition slows execution considerably, unless you also specify a location at which the condition is to be checked.

• After - Use this field to specify how many times a triggering condition is to be met (for example, how often a program location is reached) before the event is to take place. The Event Table updates during execution to show the current count (that is, how many times are left for the triggering condition to be met before the event is to take place). Once the event takes place, the count is reset to the original value. The default setting is 1, and the event takes place each time the condition is met. See " Overview of Events" for a discussion of triggering conditions.

• Stop - Use this field to specify whether or not the event is to halt execution of the program. Putting a y in this field creates a breakpoint event; putting an n in this field creates a trace event.

• Inst - Use this field to specify whether to display a disassembled assembly-language instruction when the event occurs.

• Silent - Use this field to specify whether or not the event is to cause a message to appear in the command window when it occurs.

• Enabled - Use this field to specify whether the event is enabled. Putting an n in this field disables the event; it still exists, but it does not affect program execution.

The buttons beneath these fields are for use in creating and deleting events, and are described below.

The area headed Common Events contains buttons that provide shortcuts for creating certain standard events.

Click on Close or press the Esc key to cancel the Event Table window.

Adding an Event

You can either add an event, editing field by field, or you can use the Common Events buttons to fill in some of the fields for you. You would add an event from the beginning if it weren't similar to any of the categories covered by the Common Events buttons.

To add an event, editing field by field:

1. Click on the New button.

   All values currently in the fields are cleared.

2. Fill in the relevant fields to create the event.

3. Click on the Save button to save the new event.

   It appears in the event list.

To use the Common Events buttons to add an event:

1. Click on the button for the event you want to add--for example, Print.

   This fills in certain fields (for example, it puts print on dedicated in the Actions field) and highlights the field or fields that you need to fill in (for example, it highlights the Location field when you click on Print, because you have to specify a program location).

2. Fill in the highlighted field(s). You can also edit other fields, if you like.

3. Click on Save to add the event to the event list.

Most of these Common Events buttons are also available as separate selections in the Events menu. This lets you add one of these events without having to display the entire Event Table. The menu selections, however, prompt you only for the field(s) you must fill in. You cannot edit other fields.

Individual Common Events buttons are discussed throughout the remainder of this guide.

You can also create a new event by editing an existing event; see " Editing an Existing Event".

Deleting an Existing Event

You can delete events using the Event Table or the Delete selection from the Events menu.

To delete an existing event, using the Event Table:

1. Click on the line representing the event in the event list, or move to it with the up and down arrow keys.

   This causes the components of the event to be displayed in the appropriate fields beneath the list.

2. Click on the Delete button.

   You can also choose the Delete selection from the Events menu to display the Event Table. You can then follow the procedure described above.

   Deleting a breakpoint at a program location also deletes the B in the line-number region at that location.

Editing an Existing Event

You can edit an existing event to change it, or to create a new event similar to it.

To edit an existing event:

1. Click on the line representing the event in the event list, or move to it with the up and down arrow keys.

   This causes the components of the event to be displayed in the appropriate fields beneath the list.

2. Edit these fields.

   For example, you can change the Location field to specify a different location in the program.

3. Click on Replace to save the newly edited event in place of the original version of the event.

   Click on the Save button to save the new event in addition to the original version of the event; it is given a new ID and is added to the end of the event list. Clicking on Save is a quick way of creating a new event similar to an event you have already created.

Enabling and Disabling Events

You can disable and enable events. When you disable an event, Prism keeps it in the event list, but it no longer affects execution. You can subsequently enable it when you once again want it to affect execution. This can be more convenient than deleting events and then redefining them.

• From the Event Table - The Event Table has an Enabled field. By default, there is a y in this field, meaning that the event being defined or edited is enabled. Click on the field and change the y to an n to disable the event. The event remains in the event list, but is labeled (disabled). You can then edit the event as described in " Editing an Existing Event" and change the field back to a y to enable the event once again.

• From the command line - Issue the disable command to disable an event. Use the event's ID as the argument. You can obtain this ID from the event list in the Event Table, or by issuing the show events command.

For example, this sequence of commands displays the event list, then disables an event, then re-displays the event list:

(prism) show events(1) trace
(2) when stopped { print board }
(prism) disable 1
event 1 disabled
(prism) show events
(1) trace (disabled)
(2) when stopped { print board }

Issue the enable command to enable an event that has been disabled. Specify the ID of the disabled event as the argument.

Saving Events

Events that you create for a program are automatically maintained when you reload the same program during a Prism session. This saves you the effort of redefining these events each time you reload a program.

Note these points:

• Prism prints a warning message if it can't maintain an event--for example, because the event is supposed to occur at a source line that no longer exists. Obviously, changing the program can also change the meaning of events; a breakpoint set at line 32, for example, may still be a valid event, but it may not be the event you want if you have deleted lines earlier in the program.

• Disabled events become enabled when a program is reloaded.

• Events are deleted when you leave Prism.

To use Prism commands to save your events to a file, and then execute them from the file rather than individually:

1. Issue the show events command, which displays the event list.

   Redirect the output to a file. For example,

show events @ primes.events

(See " Redirecting Output" for information on redirecting output.)

1. Edit this file to remove the ID number at the beginning of each event.

   This leaves you with a list of Prism commands.

2. Issue the source command when you want to read in and execute the commands from the file.

   For example,

source primes.events

Events Taking Pset Qualifiers (MP Prism Only)

Events in MP Prism can take a pset qualifier. You can specify this in an event field in MP Prism's Event Table, as shown in Figure 4-2.

Figure 4-2 Pset Field in MP Prism's Event Table

If you don't supply a pset qualifier, the event applies to the current pset. If you create the event before changing the current set, the event applies to the default set, which is all.

Thus,

stop in receive pset notx

sets a breakpoint in the receive routine for the processes in the set notx. Each process in the set stops when it reaches this routine. It is possible, of course, that some processes may never reach this routine. This becomes an issue when you include actions in an event; see below.

If all the processes in the pset have stopped, you can continue them by issuing a command like

cont pset notx

Here is another example:

stop if x > 10

This command stops execution for any process in the current pset if the process's value for the variable x is greater than 10.

Prism evaluates the expression in the condition locally--that is, separately for each process. Similarly, if a and b are arrays,

stop if sum(a) > sum(b)

stops execution for a process in the current set if the sum of the values of a in that process is greater than the sum of the values of b.

All processes that are stopped at breakpoints are members of the predefined pset break.

Events and Dynamic Psets

If you use a dynamic pset as a qualifier for an event, its membership is evaluated when you issue the command defining the event. Thus, the command

stop at 10 pset interrupted

creates a breakpoint only in the processes that are interrupted at the time the command is issued. If no processes are currently interrupted, you receive an error message.

One result of this is that you cannot define events that involve dynamic psets before the program starts execution.

Events and Variable Psets

If you use a user-defined variable pset as a qualifier, its membership is determined by the most recent eval pset command you issued for that pset.

As is the case with dynamic psets, you cannot define events that involve variable psets before the program starts execution.

Actions in Events

Events in both MP Prism and scalar Prism can take action clauses. For example, in MP Prism the following action clause prints x for the pset foo when the members of foo are stopped at line 10:

stop at 10 {print x} pset foo

---

Note -

Associating an action with an event forces a global synchronization at the breakpoint or tracepoint. In the example above, every process in pset foo must stop at line 10 before x can be printed. If a member does not stop at line 10, the action never takes place. In a trace event, all processes in the pset must stop at the specified place and synchronize; the action then takes place, and the processes automatically continue execution.

---

You can include an eval pset command as an event action. For example,

stop in send {eval pset sending}

evaluates the pset sending when all the members of the current pset are stopped in send. You receive error messages if it is impossible to evaluate membership in a pset (for example, because a variable in the set definition is not active).

Note these limitations in using event actions: i:

• In MP Prism, you cannot include the following commands that manipulate psets:

  • define pset

  • delete pset

  • process

  • pset

• I n MP Prism, you cannot include a pset qualifier in the action. The command in the action clause takes its pset from the pset of the event.

• In both MP Prism and scalar Prism, you cannot include commands that affect program execution, specifically:

  • cont and contw

  • run

  • step and stepi

  • next and nexti

  • wait

• In both MP Prism and scalar Prism, you cannot include the load, reload, return, and core commands.

Displaying Events by Process

Issue the show events command with a process number as an argument to display all events associated with that process. For example,

(prism) show events
(1) trace
(2) when stopped { print board }
(prism) disable 1
event 1 disabled
(prism) show events
(1) trace (disabled)
(2) when stopped { print board }

Issuing show events with no arguments has its standard behavior; that is, it prints out all events.

Events and Deleted Psets

If you create an event that applies to a particular pset, and subsequently delete the pset, the event continues to exist. Its printed representation, however, is changed so that it shows the processes that were members of the pset at the time you deleted the set.