![[Compaq]](../../images/compaq.gif)
![[Go to the documentation home page]](../../images/buttons/bn_site_home.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs.gif)
![[Help on this site]](../../images/buttons/bn_site_help.gif)
![[How to contact us]](../../images/buttons/bn_comments.gif)
![[OpenVMS documentation]](../../images/ovmsdoc_sec_head.gif)
| Document revision date: 19 July 1999 | |
|
|
|
|
|
|
| Previous | Contents | Index |
This chapter describes the use of asynchronous system traps (ASTs). It contains the following sections:
Section 5.1 provides an overview of AST routines.
Section 5.2 provides information about declaring and queuing ASTs.
Section 5.3 describes common asynchronous programming mistakes.
Section 5.4 provides information about using system services for AST event and time delivery.
Section 5.5 describes access modes for ASTs.
Section 5.6 provides information about calling ASTs.
Section 5.7 provides information about delivering ASTs.
Section 5.8 describes ASTs and process wait states.
Section 5.9 presents code examples of how to use AST services.
5.1 Overview of AST Routines
Asynchronous system traps (ASTs) are interrupts that occur asynchronously (out of sequence) with respect to the process's execution. ASTs are activated asynchronously to the mainline code in response to an event, usually either as a timer expiration or an I/O completion. An AST provides a transfer of control to a user-specified procedure that handles the event. For example, you can use ASTs to signal a program to execute a routine whenever a certain condition occurs.
The routine executed upon delivery of an AST is called an AST routine. AST routines are coded and referenced like any other routine; they are compiled and linked in the normal fashion. An AST routine's code must be reentrant. When the AST routine is finished, the routine that was interrupted resumes execution from the point of interruption.
ASTs provide a powerful programming technique. By using ASTs, you allow other processing to continue pending the occurrence of one or more events. Polling and blocking techniques, on the other hand, can use resoures inefficiently. A polling technique employs a looping that polls for an event, which has to wait for an indication that an event has occured. Therefore, depending on the frequency of the polling, polling techniques waste resources. If you use less frequent intervals, polling can then be slow to react to the occurrence of the event.
Blocking techniques forces all processing to wait for the completion of a particular event. Blocking techniques can also be wasteful, for there could well be other activities the process could be performing while waiting for the occurrence of a specific event.
To deliver an AST, you use system services that specify the address of the AST routine. Then the system delivers the AST (that is, transfers control to your AST routine) at a particular time or in response to a particular event.
Some system services allow a process to request that it be interrupted when a particular event occurs. Table 5-1 shows the system services that are AST services.
| System Service | Task Performed |
|---|---|
| SYS$SETAST | Enable or disable reception of AST requests |
| SYS$DCLAST | Declare AST |
The system services that use the AST mechanism accept as an argument the address of an AST service routine, that is, a routine to be given control when the event occurs.
Table 5-2 shows some of the services that use ASTs.
| System Service | Task Performed |
|---|---|
| SYS$DCLAST | Declare AST |
| SYS$ENQ | Enqueue Lock Request |
| SYS$GETDVI | Get Device/Volume Information |
| SYS$GETJPI | Get Job/Process Information |
| SYS$GETSYI | Get Systemwide Information |
| SYS$QIO | Queue I/O Request |
| SYS$SETIMR | Set Timer |
| SYS$SETPRA | Set Power Recovery AST |
| SYS$UPDSEC | Update Section File on Disk |
The following sections describe in more detail how ASTs work and how to
use them.
5.2 Declaring and Queuing ASTs
Most ASTs occur as the result of the completion of an asynchronous event that is initiated by a system service (for example, a SYS$QIO or SYS$SETIMR request) when the process requests notification by means of an AST.
The Declare AST (SYS$DCLAST) system service can be called to invoke a subroutine as an AST. With this service, a process can declare an AST only for the same or for a less privileged access mode.
You may find occasional use for the SYS$DCLAST system service in your programming applications; you may also find the SYS$DCLAST service useful when you want to test an AST service routine.
The following sections present programming information about declaring
and using ASTs.
5.2.1 Reentrant Code and ASTs
Compiled code that is generated by Compaq compilers is reentrant. Furthermore, Compaq compilers normally generate AST routine local data that is reentrant. Data that is shared static, shared external data, Fortran COMMON, and group or system global section data are not inherently reentrant, and usually require explicit synchronization.
Because the queuing mechanism for an AST does not provide for returning a function value or passing more than one argument, you should write an AST routine as a subroutine. This subroutine should use nonvolatile storage that is valid over the life of the AST. To establish nonvolatile storage, you can use the LIB$GET_VM run-time routine. You can also use a high-level language's storage keywords to create permanent nonvolatile storage. For instance, you can use the C language's keywords as follows:
extern
static
routine malloc().
|
In some cases, a system service that queues an AST (for example,
SYS$GETJPI) allows you to specify an argument for the AST routine . If
you choose to pass the argument, the AST routine must be written to
accept the argument.
5.2.1.1 The Call Frame
When a routine is active under OpenVMS, it has available to it temporary storage on a stack, in a construct known as a stack frame, or call frame. Each time a subroutine call is made, another call frame is pushed onto the stack and storage is made available to that subroutine. Each time a subroutine returns to its caller, the subroutine's call frame is pulled off the stack, and the storage is made available for reuse by other subroutines. Call frames therefore are nested. Outer call frames remain active longer, and the outermost call frame, the call frame associated with the main routine, is normally always available.
A primary exception to this call frame condition is when an exit handler runs. With an exit handler running, only static data is available. The exit handler effectively has its own call frame. Exit handlers are declared with the SYS$DCLEXH system service.
The use of call frames for storage means that all routine-local data is reentrant; that is, each subroutine has its own storage for the routine-local data.
The allocation of storage that is known to the AST must be in memory
that is not volatile over the possible interval the AST might be
pending. This means you must be familiar with how the compilers
allocate routine-local storage using the stack pointer and the frame
pointer. This storage is valid only while the stack frame is active.
Should the routine that is associated with the stack frame return, the
AST cannot write to this storage without having the potential for some
severe application data corruptions.
5.2.2 Shared Data Access with Readers and Writers
The following are two types of shared data access:
If there is shared data access with multiple readers, your application must be able to tolerate having a stale counter that allows frequent looping back and picking up a new value from the code.
With multiple writers, often the AST is the writer, and the mainline code is the reader or updater. That is, the mainline processes all available work until it cannot dequeue any more requests, releasing each work request to the free queue as appropriate, and then hibernates when no more work is available. The AST then activates, pulls free blocks off the free queue, fills entries into the pending work queue, and then wakes the mainline code. In this situation, you should use a scheduled wakeup call for the mainline code in case work gets into the queue and no wakeup is pending.
Having multiple writers is possibly the most difficult to code, because
you cannot always be sure where the mainline code is in its processing
when the AST is activated. A suggestion is to use a work queue and a
free queue at a known shared location, and to use entries in the queue
to pass the work or data between the AST and the mainline code.
Interlocked queue routines, such as LIB$INSQHI and LIB$REMQTI, are
available in the Run-Time Library.
5.2.3 Shared Data Access and AST Synchronization
An AST routine might invoke subroutines that are also invoked by another routine. To prevent conflicts, a program unit can use the SYS$SETAST system service to disable AST interrupts before calling a routine that might be invoked by an AST. You use the SYS$SETAST service typically only if there is noninterlocked (nonreentrant) variables, or if the code itself is nonreentrant. Once the shared routine has executed, the program unit can use the same service to reenable AST interrupts. In general you should avoid using the SYS$SETAST call because of implications for application performance.
Implicit synchronization can be achieved for data that is shared for write by using only AST routines to write the data, since only one AST can be running at any one time. You can also use the SYS$DCLAST system service to call a subroutine in AST mode.
Explicit synchronization can be achieved through a lack of read-modify cells, cases of where there is one writer with one or more readers. However, if there are multiple writers, you must consider explicit synchronization of access to the data cells. This can be achieved using bitlocks (LIB$BBCCI), hardware interlocked queues (LIB$INSQHI), interlocked add and subtract (LIB$ADAWI) routines, or by other techniques. These routines are available directly in assember by language keywords in C and other languages, and by OpenVMS RTL routines from all languages. On Alpha systems, you can use PALcode calls such as load-locked (LDx_L) and store-conditional (STx_C) instructions to manage synchronization.
For details of synchronization, see the Chapter 16 chapter. Also see
processor architecture manuals about the necessary synchronization
techniques and for common synchronization considerations.
5.2.4 User ASTs and Asynchronous Completions
OpenVMS asynchronous completions usually activate an inner-mode, a
privileged mode, AST to copy any results read into a user buffer, if
this is a read operation, and to update the IO status block (IOSB) and
set the event flag. If a use-mode AST has been specified, it is
activated once all data is available and the event flag and IOSB, if
requested, has been updated.
5.3 Common Mistakes in Asynchronous Programming
The following lists common asynchronous programming mistakes and suggests how to avoid them:
The following list presents system services and routines that are used to queue the AST routine that determines whether an AST is delivered after a specified event or time. Note that the system service (W) calls are synchronous. Synchronous system services can have ASTs, but the code blocks pending completion, when the AST is activated.
If a program queues an AST and then exits before the AST is delivered, the AST is deleted before execution. If a process is hibernating when an AST is delivered, the AST executes, and the process then resumes hibernating.
If a suspended process receives an AST, the execution of the AST depends on the AST mode and the mode at which the process was suspended, as follows:
Generally, AST routines are used with the SYS$QIO or SYS$QIOW system
service for handling Ctrl/C, Ctrl/Y, and unsolicited input.
5.5 Access Modes for AST Execution
Each request for an AST is associated with the access mode from which the AST is requested. Thus, if an image executing in user mode requests notification of an event by means of an AST, the AST service routine executes in user mode.
Because the ASTs you use almost always execute in user mode, you do not
need to be concerned with access modes. However, you should be aware of
some system considerations for AST delivery. These considerations are
described in Section 5.7.
5.6 Calling an AST
This section shows the use of the Set Time (SYS$SETIMER) system service as an example of calling an AST. When you call the Set Timer (SYS$SETIMR) system service, you can specify the address of a routine to be executed when a time interval expires or at a particular time of day. The service schedules the execution of the routine and returns; the program image continues executing. When the requested timer event occurs, the system "delivers" an AST by interrupting the process and calling the specified routine.
Example 5-1 shows a typical program that calls the SYS$SETIMR system service with a request for an AST when a timer event occurs.
| Example 5-1 Calling the SYS$SETIMR System Service | |||
|---|---|---|---|
#include <stdio.h>
#include <stdlib.h>
#include <ssdef.h>
#include <descrip.h>
#include <starlet.h>
#include <lib$routines.h>
struct {
unsigned int lower, upper;
}daytim;
/* AST routine */
void time_ast(void);
main() {
unsigned int status;
$DESCRIPTOR(timbuf,"0 ::10.00"); /* 10-second delta */
/* Convert ASCII format time to binary format */
status = SYS$BINTIM(&timbuf, /* buffer containing ASCII time */
&daytim); /* timadr (buffer to receive */
/* binary time) */
if ((status & 1) != 1)
LIB$SIGNAL(status);
else
printf("Converting time to binary format...\n");
/* Set the timer */
status = SYS$SETIMR(0, /* efn (event flag) */ (1)
&daytim, /* expiration time */
&time_ast, /* astadr (AST routine) */
0, /* reqidt (timer request id) */
0); /* flags */
if ((status & 1) != 1)
LIB$SIGNAL(status);
else
printf("Setting the timer to expire in 10 secs...\n"); (2)
/* Hibernate the process until the timer expires */
status = SYS$HIBER();
if ((status & 1) != 1)
LIB$SIGNAL(status);
}
void time_ast (void) {
unsigned int status;
status = SYS$WAKE(0, /* process id */
0); /* process name */
if ((status & 1) != 1)
LIB$SIGNAL(status);
printf("Executing AST routine to perform wake up...\n"); (3)
return;
}
|
This section describes the AST service routine, some conditions
affecting AST delivery, and the affect of kernel threads on AST
delivery. The order of an AST delivery is not deterministic. The order
the ASTs are entered into the AST queue for delivery to the process is
not related to the order the particular operations that included AST
notification requests were queued.
5.7.1 The AST Service Routine
An AST service routine must be a separate procedure. The AST must use the standard call procedure, and the routine must return using a RET instruction. If the service routine modifies any registers other than the standard scratch registers, it must set the appropriate bits in the entry mask so that the contents of those registers are saved.
Because you cannot know when the AST service routine will begin executing, you must take care when you write the AST service routine that it does not modify any data or instructions used by the main procedure (unless, of course, that is its function).
On entry to the AST service routine, the arguments shown in Table 5-3 are passed.
| VAX System Arguments | Alpha System Arguments |
|---|---|
| AST parameter | AST parameter |
| R0 | R0 |
| R1 | R1 |
| PC | PC |
| PSL | PS |
Registers R0 and R1, the program counter (PC), and the processor status longword (PSL) on VAX systems, or processor status (PS) on Alpha systems were saved when the process was interrupted by delivery of the AST.
The AST parameter is an argument passed to the AST service routine so that it can identify the event that caused the AST. When you call a system service requesting an AST, or when you call the SYS$DCLAST system service, you can supply a value for the AST parameter. If you do not specify a value, the parameter defaults to 0.
The following example illustrates an AST service routine. In this example, the ASTs are queued by the SYS$DCLAST system service; the ASTs are delivered to the process immediately so that the service routine is called following each SYS$DCLAST system service call.
#include <stdio.h>
#include <ssdef.h>
#include <starlet.h>
#include <lib$routines.h>
/* Declare the AST routine */
void astrtn ( int );
main()
{
unsigned int status, value1=1, value2=2;
status = SYS$DCLAST(&astrtn, /* astadr - AST routine */ (1)
value1, /* astprm - AST parameter */
0); /* acmode */
if((status & 1) != 1)
LIB$SIGNAL( status );
.
.
.
status = SYS$DCLAST(&astrtn, value2, 0);
if((status & 1) != 1)
LIB$SIGNAL( status );
}
void astrtn (int value) { (2)
/* Evaluate AST parameter */
switch (value)
{
case 1: printf("Executing AST routine with value 1...\n");
goto handler_1;
break;
case 2: printf("Executing AST routine with value 2...\n");
goto handler_2;
break;
default: printf("Error\n");
};
/* Handle first AST */
handler_1:
.
.
.
return;
/* Handle second AST */
handler_2:
.
.
.
return;
}
|
| Previous | Next | Contents | Index |
|
|
| privacy and legal statement | ||
| 5841PRO_013.HTML | ||