| |
|
|
|
6
Adding status and interrupt controls
This chapter describes how to use the status and interrupt facility to display status information to the user and allow the user to interrupt an application.
- Introduction, Section 6.1
- Scheduler object, Section 6.2
- Connecting a user interface to Scheduler, Section 6.3
- Declaring a module's behavior, Section 6.4
- Setting and querying information from a function, Section 6.5
The status and interrupt facilility enables you to monitor and control the execution of your application.
- Module name - The name of the currently executing module
- Percent completion --- The work a module has completed, as a percentage of the total work to be performed
You can 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 method that you write, you must:
- set the status property on the method
- instrument the code of the method to update the percent done variable it is executing
While the method is executing, you can also change the current module field to display a text message to the user about what operation is proceeding.
Interrupt capabilities include
- Disable - Prevents interruptable methods from executing once the current method completes
- Interrupt - Allows an executing, interruptable method to query whether the user has requested an interrupt
Interrupt capabilities apply only to methods that are interruptable. A method is by default interruptable. A method can declare, through an object property, that it is not interruptable.
You control the user interface for interrupt information, whether a module is interruptable, and when and how a module reacts to an interrupt request.
Underpinning the status and interrupt facility is a special object called Scheduler, located immediately under Root in the object hierarchy.
Scheduler contains four external-use subobjects:
An application interacts with Scheduler through user-interface connections to the subobjects. For example, if you want to display the current module to the user, you typically connect a UItext widget to Scheduler.current_mod.
Scheduler.disable, an int object, indicates whether the user has requested a disable. 0 means no; nonzero means yes. You typically connect a UItoggle widget to Schedule.disable.
Scheduler.interrupt, an int object, indicates whether the user has requested an interrupt. 0 means no; nonzero means yes. When interrupt is set, AVS/Express also sets disable. You typically connect a UIdynamic_toggle to Schedule.interrupt.
Scheduler.percent_done, an int object, indicates the module's percent completion. You typically connect a UIfield widget to percent_done.
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 can control the minimum and maximum range displayed with calls to OMpush_status_range and OMpop_status_range.
Scheduler.current_mod, a 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. You typically connect a UItext widget to Schedule.current_mod.
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.
AVS/Express supplies a standard user interface for displaying the information in Scheduler as part of the SingleWindowApp and MultiWindowApp DataViewers. This appears below the Module panel and consists of simple User Interface widgets attached to the percent_done, current_mode, interrupt, and disable fields.
Note that you can also access a control panel interface to Scheduler from the control menu on a ModuleStack.
You can build your own interface to Scheduler.
1. Build the user interface, consisting of appropriate widgets for the Scheduler subobjects you want to display.
2. Connect each widget's value, label, or set subobject to the appropriate subobject in Scheduler. You cannot draw a connection line, as Scheduler does not appear in the Network Editor. Instead, you enter a connection in the widget subobject's value box. For example, to refer to Scheduler.interrrupt, you enter the connection operator (=>) followed by Scheduler.interrrupt.
Generally, a widget has no special execution priority. When the user interacts with a widget, the Object Manager executes the widget's update method only after it has handled other methods already in the queue.
UIdynamic_toggle is like UItoggle, but with the added feature that the Object Manager executes its update method immediately. This is particularly useful for the widget connected to Scheduler.interrupt. When the user selects the interrupt toggle, you want Scheduler.interrupt updated immediately. An executing module's function can then query Scheduler.interrupt (by calling OMstatus_check) and take the appropriate action.
CAUTION: Use UIdynamic_toggle cautiously. It works here because it is connected to Scheduler.interrupt (and possibly Scheduler.disable), and access to these Scheduler subobjects is controlled.
Note: You can customize any widget to achieve the same affect by adding to the widget a subobject of type UImake_dyn_wind, then connecting its handle subobject to the widget's handle subobject. dyn_wind stands for dynamic window. For a model of this, see UIdynamic_toggle. Use this capability cautiously.
A module's update method declares, through object properties, whether the Object Manager should display status information for the module and whether the module is interruptable.
By default, a method does not display status information. To enable status information, set the method's status property to 1. Use the Properties Editor on the method object.
By default, a method can be interrupted and disabled. To allow a method to continue to execute even when the system is disabled, set the interruptable property to 0 on the method object. You might want to do this for User Interface objects so that they continue to provide feedback despite the system being disabled.
A method can make OM calls to set and query scheduler information.
A method can set Scheduler.percent_done, Scheduler.current_mod, and query Scheduler.interrupt by calling OMstatus_check.
A function can normalize percent_done, one of the arguments specified in a call to OMstatus_check, by indicating, in advance, a percent range.
For example, you specify a percent range of 0 to 20. You then call OMstatus_check and specify 25 for percent_done. The Object Manager normalizes percent_done to 5 (that is, 25 percent of 20).
You can push, and subsequently pop, multiple percent ranges onto a stack maintained by the Object Manager. When normalizing, the Object Manager 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 sets the percent ranges for the other functions. See the example, below.
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...
|
| |
|
|
|
Copyright © 2001 Advanced Visual Systems
Inc.
All rights reserved.
