Legacy Document

Inside Macintosh: Files /

Chapter 2 - File Manager / File Manager Reference

Application-Defined Routines / Completion Routines

MyCompletionProc

A File Manager completion routine has the following syntax:

PROCEDURE MyCompletionProc;

DESCRIPTION

When you execute a File Manager routine asynchronously (by setting its async parameter to TRUE), you can specify a completion routine by passing the routine's address in the ioCompletion field of the parameter block passed to the routine. Because you requested asynchronous execution, the File Manager places an I/O request in the file I/O queue and returns control to your application--possibly even before the actual I/O operation is completed. The File Manager takes requests from the queue one at a time and processes them; meanwhile, your application is free to do other processing.

A routine executed asynchronously returns control to your application with the result code noErr as soon as the call is placed in the file I/O queue. This result code does not indicate that the call has successfully completed, but simply indicates that the call was successfully placed in the queue. To determine when the call is actually completed, you can inspect the ioResult field of the parameter block. This field is set to a positive number when the call is made and set to the actual result code when the call is completed. If you specify a completion routine, it is executed after the result code is placed in ioResult.

ASSEMBLY-LANGUAGE INFORMATION

When your completion routine is called, register A0 contains a pointer to the parameter block of the asynchronous call, and register D0 contains the result code. The value in register D0 is always identical to the value in the ioResult field of the parameter block.

A completion routine must preserve all registers other than A0, A1, and D0-D2.

SPECIAL CONSIDERATIONS

Because a completion routine is executed at interrupt time, it should not allocate, move, or purge memory (either directly or indirectly) and should not depend on the validity of handles to unlocked blocks.

If your completion routine uses application global variables, it must also ensure that register A5 contains the address of the boundary between your application global variables and your application parameters. For details, see the discussion of the functions SetCurrentA5 and SetA5 in the chapter "Memory Management Utilities"
in Inside Macintosh: Memory.

SEE ALSO

For a more complete discussion of interrupt-level processing and its limitations, see the chapter "Introduction to Processes and Tasks" in Inside Macintosh: Processes.