12 Adding Status and Interrupt Controls

AVS/Express provides a status and interrupt facility that enables you to monitor and control the execution of your application. This chapter describes the status and interrupt facility, including its underlying Scheduler object. It contains the following sections:

12.1 Status and Interrupt Capabilities

The status and interrupt facility enables you to monitor and control how users execute your application. It provides you with the ability to provide selected status information to users, and manage when and how users interrupt the application.

Displaying Status Information

You control how the module name and the percent-completion fields are displayed to the user by customizing the user interface of the control panel.

In order for the system to show status information for a module's method, you must:

While a method executes, you can also change the current module field to display a text message to the user about what operation is proceeding.

Managing User Interrupts

You use the interrupt capabilities to determine how and when users interrupt your application. The following capabilities are available:

You control interrupt information, whether a module is interruptible, and when and how a module reacts to an interrupt request by customizing the user interface of the control panel.

12.2 The Scheduler

This section describes an AVS/Express object called the Scheduler. It, and subsequent sections, frequently refers to C API routines. For information on equivalent C++ API and FORTRAN API routines, see Chapter 9, Object Manager APIs.

Underpinning the status and interrupt facility is a special AVS/Express object called the Scheduler, which is located immediately under Root in the object hierarchy. An application must interact with the Scheduler to utilize the available status and interrupt capabilities. Interaction is through user-interface connections to the Scheduler's four external-user subobjects:

For example, if you want to display the current module to the user, you typically connect a UItext widget to the Scheduler.current_mod subobject.

Table L-1


Name	Type	Description
Scheduler.disable	int	Indicates whether the user has requested a disable. The value 0 means no; a nonzero value means yes. You typically connect a UItoggle widget to Schedule.disable.
Scheduler.interrupt	int	Indicates whether the user has requested an interrupt. The value 0 means no; a nonzero value means yes. When interrupt is set, AVS/Express also sets disable. You typically connect a UIdynamic_toggle widget to Schedule.interrupt.
Scheduler.percent_done	int	Indicates the module's percent completion. You are responsible for maintaining percent_done, which you typically do from a module's method: -- You set percent_done with a call to OMstatus_check. -- You control the minimum and maximum range displayed with calls to OMpush_status_range and OMpop_status_range. You typically connect a UIfield widget to Schedule.percent_done.
Scheduler.current_mod	string	Indicates the current module. If a method has status information enabled, AVS/Express sets current_mod to the method's name when the method is about to be invoked. A function can set current_mod with a call to OMstatus_check. This enables the function to display arbitrary text and to change this text as the method proceeds. You typically connect a UIlabel widget to Schedule.current_mod.

12.3 Connecting a User Interface to the Scheduler

You can connect your application to the Scheduler either from the standard user interface or from a custom interface that you build.

Using the Standard Interface

AVS/Express supplies a standard user interface for displaying the information in the Scheduler as part of the SingleWindowApp and MultiWindowApp DataViewers. This interface, which appears below the Module panel, consists of simple User Interface widgets attached to Scheduler.percent_done, Scheduler.current_mod, Scheduler.interrupt, and Scheduler.disable subobjects.

Note that you can also access a control panel interface to the Scheduler from the control menu on a ModuleStack.

Building and Using a Custom Interface

You can display Scheduler information in a user interface customized for your application. Simply build the user interface as you would build any user interface, inserting appropriate widgets for the Scheduler subobjects that you want to display.

Table L-1


Subobject	Widget	Comments
Scheduler.disable	UItoggle or UIdynamic_toggle	See the next section, Widget Execution Priority, for information about UIdynamic_toggle.
Scheduler.interrupt	UIdynamic_toggle	See the next section, Widget Execution Priority, for information about UIdynamic_toggle.
Scheduler.percent_done	UIfield or UIslider	(None)
Scheduler.current_mod	UIlabel or UItext	Use UItext (read-write) only if you intend to modify the contents of Scheduler.current_mod.

To use your custom interface, connect each widget's value, label, or set subobject to the appropriate subobject in the Scheduler. Note that the Scheduler does not appear in the Network Object, hence you cannot draw a connection line to the appropriate subobject. Instead, you must enter a connection in the widget subobject's value box. For example, to refer to Scheduler.interrupt, enter the connection operator followed by Scheduler.interrupt:

Widget Execution Priority

Most widgets have no special execution priority. When the user interacts with a widget, the Object Manager executes the widget's update method after it handles any other methods already in the queue. However, when the user selects the interrupt toggle, it is desirable for the Scheduler.interrupt subobject to be updated immediately. An executing module's function can then query Scheduler.interrupt (by calling OMstatus_check) and take the appropriate action.

To enable an immediate update, connect a UIdynamic_toggle widget rather than a UItoggle widget to the Schedule.interrupt subobject. UIdynamic_toggle is similar to UItoggle, except that the Object Manager executes its update method immediately.

AVS/Express can use UIdynamic_toggle for immediate updates because it contains a subobject of type UImake_dyn_wind (dyn_wind stands for dynamic window), whose handle subobject is connected to UIdynamic_toggle's handle subobject. You can customize any widget in the same way to achieve the same affect.

CAUTION: Be extremely cautious about where and when you use UIdynamic_toggle and/or implement immediate updating. The UIdynamic_toggle widget works correctly in the context of the Scheduler because it is connected to Scheduler.interrupt (and possibly Scheduler.disable), and access to these Scheduler subobjects is controlled.

12.4 Declaring a Module's Behavior

A module's update method uses object properties to declare whether the Object Manager should display status information for the module and whether the module is interruptible.

Enabling and Disabling Status Information

By default, a method does not display status information. You enable and disable its display by setting the method object's status property in the Properties Editor. The following values are allowed:

Enabling and Disabling Interruptibility

By default, a method can be interrupted and disabled. You enable and disable interruptibility by setting the method object's interruptible property in the Properties Editor. The following values are allowed:

Disabling interruptibility allows a method to continue to execute even when the system is disabled. You might want to do this in order to allow user interface objects to continue to provide feedback in those circumstances.

12.5 Setting and Querying Information from an Update Function

The update function associated with a method can call Object Manager API routines to set and query Scheduler information. This section describes the C API routines; for information on equivalent C++ API and FORTRAN API routines, see Chapter 9, Object Manager APIs.

Accessing Scheduler Information

A function can also normalize Scheduler.percent_done; see the next section for details.

Setting a Range for the Scheduler.percent_done Subobject

A function sets Scheduler.percent_done by calling the OMstatus_check routine. By indicating in advance a percent range, it can also normalize this subobject. For example, suppose that it does the following:

The Object Manager then normalizes Scheduler.percent_done to 5; that is, 25 percent of 20.

To specify a percent range, a function calls the OMpush_status_range routine and pushes the range onto a stack that the Object Manager maintains. Note that you are not restricted to pushing a single range onto the stack: you can push and pop multiple percent ranges onto and off the Object Manager's stack. (To pop a range off the stack, the function calls OMpop_status_range.) When the Object Manager normalizes, it uses the top range in the stack. This feature is useful when the work of an update function is split among several other functions that the update function calls: the update function uses the push and pop functionality to set percent ranges for the other functions.

For descriptions of OMpush_status_range and OMpop_status_range, see the AVS/Express online help system.

The following example module code illustrates pushing and popping ranges onto and off the Object Manager's stack.

int
get_random_values(int arr[], int size)
{
int i, stop;
for (i = 0; i < size; i++) {
if (!(i & 0xff)) { /* do only every so often... */
(void) OMstatus_check(i * 100 / size, NULL, &stop);
if (stop) return(0); /* user interrupted us */
}
arr[i] = random();
}
return(1);
}
int
update_me(OMobj_id obj_id, OMevent_mask mask, int seq_num)
{
int arr1[1000], arr2[500];
int stat;

OMpush_status_range(0,75);
stat = get_random_values(arr1,1000);
OMpop_status_range();
if (stat != 1) return(0); /* interrupted */

OMpush_status_range(75,100);
stat = get_random_values(arr2,500);
OMpop_status_range();
if (stat != 1) return(0);

... set the values in arr1 and arr2 into objects ...

Additional Trapping for Memory Allocation Errors

The ~express/include/avs/util.h file was updated in AVS/Express 3.1 to include changes that will safeguard against memory allocation errors. The util.h file contains the following three macros for memory allocation:

These macros will execute if the pointer returned from malloc or alloc is NULL; when this happens, a dialog box titled "Memory Allocation FAILED" is displayed with a "Save State and Exit, or Retry Allocation?" message.

If you respond by selecting YES, the current system state is saved before exiting. If you respond by selecting NO, you can perform any memory cleanup on your own and then retry the allocation.

Using AVS/Express