TweetFollow Us on Twitter

August 92 - LIVING IN AN EXCEPTIONAL WORLD

LIVING IN AN EXCEPTIONAL WORLD

SEAN PARENT

[IMAGE Parent_final_rev1.GIF]

Handling exceptions is a difficult but important part of developing Macintosh applications. This article provides a methodology as well as a set of C tools for handling exceptions and writing robust code. Techniques and examples are provided for dealing with some of the Toolbox idiosyncrasies, and some interesting features of the C preprocessor, MacsBug, and MPW are explored.


Writing software on the Macintosh can be difficult. Writing robust software on the Macintosh is even more difficult. Every call to the Toolbox is a potential source of a bug and there are too many cases to handle--what if there isn't enough memory, or the disk containing the code has been ejected, or there isn't enough stack space, or the printer is unplugged, or . . . The list goes on, and a well-written application is expected to handle every case--always recovering without loss of information. By looking at how software is developed, this article introduces a methodology and tools for handling the exceptional cases with minimal impact on the code that handles the task at hand.

VERSION 1: NORMAL FLOW OF CONTROL

When writing code, programmers usually begin by writing the normal flow of control--no error handling. The code shown below is a reconstruction of the first version of a printing loop routine that eventually went out as a Macintosh Technical Note, "A Printing Loop That Cares . . ." (#161). Note that comments were removed to make the structure more apparent.

#include <Printing.h>
#include <Resources.h>
#include <Memory.h>

void PrintStuff(void)
{
    GrafPtr         oldPort;
    short           copies, firstPage, lastPage, numCopies,
                    printmgrsResFile, realNumberOfPagesInDoc,
                    pageNumber;
    DialogPtr       printingStatusDialog;
    THPrint         thePrRecHdl;
    TPPrPort        thePrPort;
    TPrStatus       theStatus;

    GetPort(&oldPort);
    UnLoadTheWorld();
    thePrRecHdl = (THPrint)NewHandle(sizeof(TPrint));
    PrOpen();
    printmgrsResFile = CurResFile();
    PrintDefault(thePrRecHdl);
    if (PrStlDialog(thePrRecHdl)) {
        realNumberOfPagesInDoc = DetermineNumberOfPagesInDoc(
            (**thePrRecHdl).prInfo.rPage);
        if (PrJobDialog(thePrRecHdl)) {
            numCopies = (**thePrRecHdl).prJob.iCopies;
            firstPage = (**thePrRecHdl).prJob.iFstPage;
            lastPage = (**thePrRecHdl).prJob.iLstPage;
            (**thePrRecHdl).prJob.iFstPage = 1;
            (**thePrRecHdl).prJob.iLstPage = 9999;
            if (realNumberOfPagesInDoc < lastPage) {
                lastPage = realNumberOfPagesInDoc;
            }
            printingStatusDialog =
                GetNewDialog(257, nil, (WindowPtr) -1);
            for (copies = 1; copies <= numCopies; copies++) {
                (**thePrRecHdl).prJob.pIdleProc =
                    CheckMyPrintDialogButton;
                UseResFile(printmgrsResFile);
                thePrPort = PrOpenDoc(thePrRecHdl, nil, nil);
                pageNumber = firstPage;
                while (pageNumber <= lastPage) {
                    PrOpenPage(thePrPort, nil);
                    DrawStuff((**thePrRecHdl).prInfo.rPage,
                        (GrafPtr)thePrPort, pageNumber);
                    PrClosePage(thePrPort);
                    ++pageNumber;
                }
                PrCloseDoc(thePrPort);
            }
            if ((**thePrRecHdl).prJob.bJDocLoop == bSpoolLoop) {
                PrPicFile(thePrRecHdl, nil, nil, nil, &theStatus);
            }
        }
    }
    PrClose();
    DisposeHandle((Handle)thePrRecHdl);
    DisposeDialog(printingStatusDialog);
    SetPort(oldPort);
} /* PrintStuff */ 

VERSION 2: ERROR HANDLING ADDED

With code in the preliminary stage shown above, the flow of control is easy to follow. After writing it, the programmer probably read through it and added some error-handling code. Adding "if (error == noErr)" logic wasn't difficult, but it took some thought to determine how to handle the cleanup and deal with the two loops. Some more error-handling code may have been added after running the routine under stressful conditions. Perhaps it was reviewed by lots of people before it went out as a Technical Note. Here's the new version of the code (with the added error-handling code shown in bold):

#include <Printing.h>
#include <Resources.h>
#include <Memory.h>

void PrintStuff(void)
{
    GrafPtr         oldPort;
    short           copies, firstPage, lastPage, numCopies,
                    printmgrsResFile, realNumberOfPagesInDoc,
                    pageNumber, printError;
    DialogPtr       printingStatusDialog;
    THPrint         thePrRecHdl;
    TPPrPort        thePrPort;
    TPrStatus       theStatus;

    GetPort(&oldPort);
    UnLoadTheWorld();
    thePrRecHdl = (THPrint)NewHandle(sizeof(TPrint));
    if (MemError() == noErr && thePrRecHdl != nil) {
        PrOpen();
        if (PrError() == noErr) {
            printmgrsResFile = CurResFile();
            PrintDefault(thePrRecHdl);
            if (PrError() == noErr) {
                if (PrStlDialog(thePrRecHdl)) {
                    realNumberOfPagesInDoc =
                        DetermineNumberOfPagesInDoc(
                        (**thePrRecHdl).prInfo.rPage);
                    if (PrJobDialog(thePrRecHdl)) {
                        numCopies = (**thePrRecHdl).prJob.iCopies;
                        firstPage = (**thePrRecHdl).prJob.iFstPage;
                        lastPage = (**thePrRecHdl).prJob.iLstPage;
                        (**thePrRecHdl).prJob.iFstPage = 1;
                        (**thePrRecHdl).prJob.iLstPage = 9999;
                        if (realNumberOfPagesInDoc < lastPage) {
                            lastPage = realNumberOfPagesInDoc;
                        }
                        printingStatusDialog =
                            GetNewDialog(257, nil, (WindowPtr) -1);
                        for (copies = 1; copies <= numCopies;
                             copies++) {
                            (**thePrRecHdl).prJob.pIdleProc =
                                CheckMyPrintDialogButton;
                            UseResFile(printmgrsResFile);
                            thePrPort =
                                PrOpenDoc(thePrRecHdl, nil, nil);
                            if (PrError() == noErr) {
                                pageNumber = firstPage;
                                while (pageNumber <= lastPage &&
                                        PrError() == noErr) {
                                    PrOpenPage(thePrPort, nil);
                                    if (PrError() == noErr) {
                                        DrawStuff(
                                            (**thePrRecHdl).prInfo.
                                                rPage,
                                            (GrafPtr)thePrPort,
                                            pageNumber);
                                    }
                                    PrClosePage(thePrPort);
                                    ++pageNumber;
                                }
                            }
                            PrCloseDoc(thePrPort);
                        }
                    } else PrSetError(iPrAbort);
                } else PrSetError(iPrAbort);
            }
        }
        if (((**thePrRecHdl).prJob.bJDocLoop == bSpoolLoop) &&
                (PrError() == noErr)) {
            PrPicFile(thePrRecHdl, nil, nil, nil, &theStatus);
        }
        printError = PrError();
        PrClose();
        if (printError != noErr)
            PostPrintingErrors(printError);
    }
    if (thePrRecHdl != nil)  DisposeHandle((Handle)thePrRecHdl);
    if (printingStatusDialog != nil)
        DisposeDialog(printingStatusDialog);
    SetPort(oldPort);
} /* PrintStuff */

Can you easily follow the normal flow of control in the second version? What if an error occurs? Could an error ever go unreported? Could this code crash because it didn't handle an error? Does this routine always clean up after itself? These questions are difficult to answer because the normal flow of control of this routine is intertwined with the flow that will occur in the event of an error. If the two could be separated, it would be much easier to tell what the routine does normally and how things are handled when something goes wrong. Besides making the code easier to read, a methodology that allowed such separation would make the code easier to write, debug, and, maintain.

PROGRAMMING BY CONTRACT

Programming by contract is based on the assumption that all correct routines have a contract, either stated or implied, with their caller. The contract states that if a given set of preconditions is met, the routine either succeeds or flags an exception and leaves the machine in a known or determinable state. This contract is flexible enough to be applied to any correct code.

The secret to writing robust code is to understand what the preconditions of a given routine are, when an exception can be flagged, and how to handle the exception. Separating the logic that checks conditions and handles exceptions from the algorithm of the routine allows code to be written in a straightforward way with the flow of control seen as easily as in our first version.

PRECONDITIONS
The preconditions of a routine specify the state the machine must be in for the routine to execute without failure (where failure implies a crash--not flagging an exception). A routine may require in its precondition items such as

  • a previously called initialization routine
  • valid ranges for value parameters
  • available memory
  • initialization of global state
  • a specific software version

For some routines the preconditions may be readily apparent either in the interface or in the documentation. Sometimes it's necessary to experiment to discover the preconditions of a routine. When writing a routine, the "strength" of the precondition can be set according to the use of the routine. For example, a routine named DivideLong is written with a description that states: Given two numbers, numer and denom, DivideLong will divide numer by denom, set numer to the result, and return noErr. If denom is zero, DivideLong will return divideByZeroErr and leave numer unchanged.

With this description, numer and denom can be any numbers of the proper type. This is a weak precondition. Another description might read: Given two numbers, numer and denom, DivideLong will divide numer by denom and return the result. If denom is zero, DivideLong will fail.

With the second description, it would be the caller's responsibility to ensure that denom isn't zero. This is a strong precondition.

In general, it's better to have a strong precondition in a routine that is used within a sequence of related routines or shares conditions with other routines, because it generates more efficient code byeliminating error checking. It's better to have a weak precondition in routines that are called only once or at the start of a sequence of related routines. Routines with weak preconditions free the caller from ensuring the state of the machine before making the call.

A precondition can be strengthened by the caller but must not be weakened. Strengthening is useful when you're making a sequence of related calls where being sure additional conditions are met guarantees that no routine flags an exception. For example, given the first description of DivideLong it would be valid for a caller to do the following:

if (denom != 0) {
(void)DivideLong(&numer_a, denom); /* Ignore return. */
(void)DivideLong(&numer_b, denom); /* Ignore return. */
} else HandleError();

This may be more desirable than checking for a result of divideByZeroErr after each call. An example of weakening a precondition would be to call DivideLong as described in the second description without ensuring that denom isn't zero. This would constitute a bug.

POST-CONDITIONS
Post-conditions specify the state of the machine on the return of a routine. They include side effects and changes to global state as well as function results and variable parameters. The post-conditions of a routine must be determinable for the routine to be correct. They don't vary in strength and, if not met, the routine has a bug. A thorough understanding of the post-conditions of a routine is required to ensure that the routine is being called correctly and that cleanup can occur when the routine flags an exception.

Sometimes it's necessary to rephrase the preconditions and post-conditions of a routine to use it correctly. For example, a common misconception is that the only preconditions for calling TEKey are that it has passed a valid TEHandle and the appropriate Managers have been initialized. Since there's no mechanism for TEKey to flag an exception, the assumption is that it can't fail. But TEKey may need to grow the hText handle if the character isn't replacing others and isn't a backspace. Growing a handle requires memory--something there may not be enough of. Since TEKey can fail without flagging an exception with these preconditions, it appears to be incorrect and contain a bug. However, by strengthening the preconditions to require that hText must be able to grow by the size of a character, the routine is once again correct. Strengthening preconditions is an easy fix often used in system software. (See the section "Preflighting Calls" for tips on how to ensure preconditions.)

HOW TO WRITE CHECKS
The checkmacro is used to ensure that static preconditions and post-conditions are being met during development. It also documents conditions for you, making it a very useful tool that adds to the maintainability of the code. Unfortunately, these conditions cannot be expressed directly in the interface so as to be more apparent to the caller. The syntax forcheckis

check(assertion );

To use thecheck macro, include Exceptions.h (provided on theDeveloper CD Series disc). For MacsBug, use ResEdit to add Exceptions.rsrc to the DebuggerPrefs file in the System Folder.

What checkdoes depends on the setting of the compile-time variable DEBUGLEVEL. DEBUGLEVEL can be set to one of the following values:

  • DEBUGOFF or DEBUGWARN:checkdoes nothing andassertion is not evaluated.
  • DEBUGMIN or DEBUGSYM:assertion is evaluated and, if it's false (zero), a debugger break is executed. (The debugger break is Debugger ( ) for DEBUGMIN and SysBreak ( ) for DEBUGSYM. The first is useful for low-level debuggers like MacsBug or TMON, the second for symbolic debuggers like SourceBug, SADE, or THINK C.)
  • DEBUGON or DEBUGFULL:assertion is evaluated and, if it's false (zero), MacsBug is entered and the dprintf dcmd is invoked to display more information. If DEBUGON,assertion is displayed and if DEBUGFULL, the source code file and line number are also displayed (see "Wonders of MacsBug and dprintf" for more information about dprintf).

Normally,checkis used at the start and end of a routine. At the start it's used to ensure that parameters are within a given range and are not specific values (such as nil). At the end it's used to ensure that allocations succeeded and results are as desired.

REQUIREMENTS FOR BETTER LIVING

Althoughcheckcan ensure that preconditions and post-conditions are being met during development,checkis of limited value in situations where it cannot be determined whether the conditions are being met statically, because
  • it disappears when DEBUGLEVEL is set to DEBUGOFF
  • it doesn't provide sufficient support for handling exceptions to return the machine to a known state

What's needed is a mechanism that does not compile out and provides the ability to invoke a handler whenassertion fails.

WHAT WE REQUIRE
The requiremacro was created to make handling exceptions simpler. The syntax forrequireis

require(assertion , exception );

Ifassertion evaluates to false (zero), execution continues at the handlerexception . (Theexception parameter, by convention, shares the name of the routine that failed, but this isn't mandatory.) Handlers are typically written as shells with control falling from one to the next, cleaning up after prior calls along the way. The extent of the cleanup needed gets deeper as more of the routine succeeds. Figure 1 shows an extended form ofrequirecalled require_action. The extended form executes a statement whenassertion fails before executing the handler. This is most useful for setting an error variable. The syntax forrequire_actionis

require_action(assertion , exception , action );

Like check, requirebreaks into MacsBug and displays pertinent information depending on the settings of DEBUGLEVEL. Unlikecheck, requiredoes not compile out when DEBUGLEVEL is set to DEBUGWARN or DEBUGOFF. It evaluatesassertion and invokes the handler (andaction ), but no break occurs.

The nrequiremacro is equivalent torequire(! assertion , exception ). However, under rare circumstances it generates more efficient code, and when debugging is on, it displays the value ofassertion . It's also easier to read. As a general rule, userequirewith handles and pointers andnrequirewith errors.

VERSION 3: IMPROVED WITH REQUIRE

A close look at the code in version 2 reveals some problems:
  • No error handling is done after PrCloseDoc, though any errors will get caught either after the next PrOpenDoc or on exit.
  • If the NewHandle at the start of the code fails, it won't print and the user is never notified why.
  • If an error occurs in the copies loop, the loop isn't terminated.

If printing is well behaved and does nothing once PrError has been set, none of these problems poses much of a threat to the actual stability of the code (with the exception of GetNewDialog). However, the use ofrequirewhen writing the code could have avoided the problems and the code would be easier to understand and maintain. This is shown in the code below--version 3. The structure of the code in version 3 is almost identical to version 1 with the addition of therequirestatements and the handlers at the end. Writing code like this is straightforward. When a routine is called that can flag an exception, arequirestatement is added with a handler. The statements executed in a handler typically clean up after the routines called before the routine flagging the exception. (See the section "When To Clean Up" for more discussion.) Although PrClose should never cause an error, acheck statement was added during development.

Here's version 3 of the code (with changes from version 1 shown in bold):

#include <Printing.h>
#include <Resources.h>
#include <Memory.h>
#include <Errors.h>
#include "Exceptions.h"

void PrintStuff(void)
{
    GrafPtr     oldPort;
    short       copies, firstPage, lastPage, numCopies,
                printmgrsResFile, realNumberOfPagesInDoc,
                pageNumber;
    DialogPtr   printingStatusDialog;
    OSErr       theError;
    THPrint     thePrRecHdl;
    TPPrPort    thePrPort;
    TPrStatus   theStatus;
    long        contig, total;
    
    enum { dialogSlop = 8192 };

    GetPort(&oldPort);
    UnLoadTheWorld();
    
    thePrRecHdl = (THPrint)NewHandle(sizeof(TPrint));
    require_action(thePrRecHdl, NewHandle,
        theError = MemError(););
    
    PrOpen();
    nrequire(theError = PrError(), PrOpen);
    
    printmgrsResFile = CurResFile();
    PrintDefault(thePrRecHdl);
    nrequire(theError = PrError(), PrintDefault);
    
    if (PrStlDialog(thePrRecHdl)) {
        realNumberOfPagesInDoc = DetermineNumberOfPagesInDoc(
            (**thePrRecHdl).prInfo.rPage);
        if (PrJobDialog(thePrRecHdl)) {
            numCopies = (**thePrRecHdl).prJob.iCopies;
            firstPage = (**thePrRecHdl).prJob.iFstPage;
            lastPage = (**thePrRecHdl).prJob.iLstPage;
            (**thePrRecHdl).prJob.iFstPage = 1;
            (**thePrRecHdl).prJob.iLstPage = 9999;
            if (realNumberOfPagesInDoc < lastPage) {
                lastPage = realNumberOfPagesInDoc;
            }
            
            PurgeSpace(&total, &contig);
            require_action(contig >= dialogSlop, PurgeSpace,
                theError = memFullErr;);
            
            printingStatusDialog =
                GetNewDialog(257, nil, (WindowPtr) -1);
            require_action(printingStatusDialog, GetNewDialog,
                theError = memFullErr;);
            
            for (copies = 1; copies <= numCopies; copies++) {
                (**thePrRecHdl).prJob.pIdleProc =
                    CheckMyPrintDialogButton;
                UseResFile(printmgrsResFile);
                thePrPort = PrOpenDoc(thePrRecHdl, nil, nil);
                nrequire(theError = PrError(), PrOpenDoc);
                
                pageNumber = firstPage;
                while (pageNumber <= lastPage) {
                    PrOpenPage(thePrPort, nil);
                    nrequire(theError = PrError(), PrOpenPage);
                    
                    DrawStuff((**thePrRecHdl).prInfo.rPage,
                        (GrafPtr)thePrPort, pageNumber);
                    PrClosePage(thePrPort);
                    nrequire(theError = PrError(),
                        PrClosePage);
                    
                    ++pageNumber;
                }
                PrCloseDoc(thePrPort);
                nrequire(theError = PrError(), PrCloseDoc);
            }
            if ((**thePrRecHdl).prJob.bJDocLoop == bSpoolLoop) {
                PrPicFile(thePrRecHdl, nil, nil, nil, &theStatus);
                nrequire(theError = PrError(), PrPicFile);
            }
        }
    }

    PrClose();
    ncheck(PrError());
    
    DisposeHandle((Handle)thePrRecHdl);
    DisposeDialog(printingStatusDialog);
    SetPort(oldPort);
    return;

PrOpenPage:
    PrClosePage(thePrPort);
PrClosePage:
PrOpenDoc:
    PrCloseDoc(thePrPort);
PrPicFile:
PrCloseDoc:
    DisposeDialog(printingStatusDialog);
GetNewDialog:
PurgeSpace:
PrintDefault:
PrOpen:
    PrClose();
    DisposeHandle((Handle)thePrRecHdl);
NewHandle:
    SetPort(oldPort);
    PostPrintingErrors(theError);
} /* PrintStuff */

PREFLIGHTING CALLS

Preflighting a call is the process of ensuring that the preconditions are met. Usually this isn't necessary since the preconditions will be satisfied by handling the exceptions of prior calls or will be implicit in the caller's preconditions. For example, there's no need to ensure that the TEHandle being passed to TEKey isn't nil if the exceptional case of the previous TENew returning nil was handled. In case preconditions haven't been satisfied by handling the exceptions of previous calls,requirecan be used to check the precondition and invoke a handler if it's not being met. This is especially useful for routines that have strong preconditions or preconditions that are difficult to determine. Earlier, TEKey was used as an example of a routine with strong preconditions. To ensure the preconditions for TEKey,requirecould be used as follows:

OSErr SafeTEKey(short key, TEHandle hTE) {
    enum { teSlop = 1024 };

    OSErr       error;
    TEPtr       w               = *hTE;
    Handle      hText           = w->hText;
    short       teLength        = w->teLength;
    
    SetHandleSize(hText, teLength + teSlop);
    nrequire(error = MemError(), SetHandleSize);
    SetHandleSize(hText, teLength);
    TEKey(key, hTE);
    return(noErr);
    
SetHandleSize:
    return error;
}

The constant teSlop is used instead of 1 just to be safe. Adding some slop for routines with implied, rather than stated, preconditions is always a good idea.

For some routines the preconditions are too complex or subject to change to accurately state as an assertion. This is the case for GetNewDialog, as shown in version 3. GetNewDialog can fail when there isn't enough memory for one of the numerous QuickDraw elements to be allocated, to load the WDEF, or, if the dialog contains TextEdit items, to create the TEHandle. About all that can be done to guarantee that GetNewDialog succeeds is to ensure that there's a reasonable amount of memory available. It's fairly safe to rely on the Process Manager in System 7 to make sure there's space in the system heap for the WDEF. This is what's done in version 3. The assertion is based on contiguous memory instead of total memory in case the heap is too fragmented to allocate some of the larger blocks required. Sometimes all that can be done is to increase the chances of survival.

WHEN TO CLEAN UP

Just as preconditions can sometimes be tricky to determine, post-conditions can be hazardous as well. It's important to understand the post-conditions of the routines being called, so that the machine can be returned to a known state, ensuring valid post-conditions for the calling routine. Normally, if an exception is being raised, a routine should dispose of everything itsuccessfully allocated, close everything itsuccessfully opened, and release everything itsuccessfully locked. So, if NewHandle is called successfully, DisposeHandle is called in the handler. If OpenFile is called successfully, CloseFile is called in the handler.

But this rule isn't always true. One counterexample is the Printing Manager. Even if PrOpen flags an exception PrClosemust  be called. The same is true for PrOpenDocument and PrOpenPage.

Shared resources present another potential problem. If GetResource is successfully called on a system resource, it's a bad idea to release it, because it may also be in use by another routine. SetResLoad(false) and GetResource can be called to determine whether the resource is already in memory before loading it, and then it can be released only if it was loaded. This, however, is taking things to an extreme. It may be better to document that these resources may be loaded even if the routine flags an exception. Since this is determinable by the caller, it suffices as a valid post- condition.

FUTURE DIRECTIONS

The routines and macros provided in Exceptions.h lay the foundation for writing robust software. There are more sophisticated exception-handling mechanisms, such as the proposedcatch andthrow implementation for C++. Ada has a reasonable exception-handling mechanism, as does CLU and Eiffel. However, these mechanisms don't lend themselves to dealing with exceptions from routines that were not written using the same mechanism and so are difficult to use on the Macintosh when dealing with the OS and Toolbox. Thecheckand requiremacros are flexible enough to be useful in most situations and are implemented in C, so they can be of value for many (if not most) existing projects. They are also C++ friendly and can be of great use to C++ programmers as well.

After you read the code in version 3 that uses these macros it should be fairly simple to answer the questions asked about version 2 at the beginning of the article. This is left as an exercise.

Turn the page if you want even more detail . .

MORE DETAIL THAN MOST FOLKS NEED

The require and check macro implementation is shown in Figure 2. To ensure that there aren't any side effects, any macro that's larger than a single statement is enclosed in do { } while(false). This ensures that the macro behaves as a simple statement and can be used anyplace a simple statement would be (such as after an if). The do { } while(false) does not generate any object code. In some of the macros, if statements appear in the form

if (assertion) ; /* Do nothing. */
else { /* Do something. */ }

Under some conditions, this will generate more efficient code than

if (!assertion) { /* Do something. */ }

(This was especially true back in the days of the MPW 3.1 compiler.) There are variables declared within the scope of the macros when debugging is on. This avoids side effects caused by evaluating assertion  multiple times (once in the condition and once to display it). For example:

nrequire(ReadCharacters(), Fail);

If ReadCharacters returned a value other than nil, MacsBug would be invoked to display the result before executing the handler Fail. Without the local variable, ReadCharacters would be executed a second time to display the value. The second execution may cause side effects like increasing a file pointer as well as reading in a different set of characters.

When assertion  is an error code returned by a function, it can be assigned to a variable to preserve the error. This also keeps the exception-handling code enclosed within the requirestatement. For example:

nrequire(error = GetError(), Fail);

However, with warnings set to full, this invokes a warning because the assignment takes place as part of anif statement. Using

error = GetError();
nrequire(error, Fail);

generates identical code (at least with MPW 3.2) and doesn't cause any warnings.

A macro, resume, is provided for recovering from exceptions. It's used within a handler and takes the form

resume(exception );

where exception  corresponds to exception  used in a require statement. The resume macro simply transfers control to the point immediately following the require statement. Because of the resume feature, multiplerequire statements cannot share the same exception handler. Sometimes sharing a handler is convenient, soresume can be disabled with a statement:

#define resumeLabel(exception)

To reenable resume, use

#define resumeLabel(exception)\ 
    resume_ ## exception:

There's also a check_actionmacro which, like require_action, allows a statement to be executed whenassertion  fails. The check_action macro compiles out like all check macros and should be viewed as a development-time tool only. Being able to execute a statement allows for the exit of a routine if the preconditions aren't met.

#define require(assertion, exception)               \
    do {                                                \
        if (assertion) ;                                \
        else {                                          \
            dprintf(notrace,                            \
                "Assertion \"%s\" Failed\n"     \
                "Exception \"%s\" Raised",          \
                #assertion, #exception);            \
            goto exception;                         \
            resumeLabel(exception);                 \
        }                                               \
    } while (false)

#define check(assertion)                            \
    do {                                                \
        if (assertion) ;                                \
        else {                                          \
            dprintf(notrace,                            \
                "Assertion \"%s\" Failed",          \
                #assertion);                            \
        }                                               \
    } while (false)


Figure 2Implementing require and check

WONDERS OF MACSBUG AND DPRINTF

The MacsBug dcmd, dprintf, is used by the requireand check macros to display useful debugging information. The dprintf command is also a powerful tool that provides all the features of the standard printf but uses MacsBug as the console. The dprintf command assumes MPW parameter-passing conventions. The syntax for dprintf is

dprintf([no]trace, formatString , ...);

where trace and notrace are used to specify whether or not to continue after displaying the information in MacsBug. The variable formatString  is a printf style- format string with some extensions (see the comment in the Exceptions.h file on the Developer CD Series  disc). Following formatString are the parameters to display. This can be a very useful tool for viewing complex structures or difficult-to-read values like floating- or fixed-point numbers.The implementation of the dprintf dcmd is shown in the DPrintf.c file on the CD. It's fairly straightforward and can be extended easily to add any special data types required (for example, a t format character that would take a pointer to text and an integer length and display the text). The dcmd is invoked from C using the inline declaration for dprintf. The inline declaration invokes the DebugStr trap and pushes a long on the stack. The push is required because DebugStr uses Pascal calling conventions and so pops the [ no]trace string from the stack. Since dprintf is a C-based function, the stack is fixed, so the string isn't popped twice. Both traceand notrace are macro Pascal strings containing ";dprintf;doTrace" and ";dprintf". Since the strings begin with a semicolon, MacsBug interprets them as commands and executes them. The dcmd then fetches the parameters from the stack according to formatString and displays them. The MacsBug macro doTraceevaluates to "g" or "". It's used to switch tracing between trace and break by entering either traceGo ortraceBreak in MacsBug.

When developing software, it's useful to insert dprintf statements to display information in sections of code that are executed only in unusual circumstances. If dprintf is bracketed with #if debugon / #endif directives, it compiles out when DEBUGLEVEL is set to DEBUGWARN or DEBUGOFF. With trace the information is displayed without seriously interrupting the execution of the code. The trace macro is also useful for logging timing statistics by displaying Ticks. Since formatString  is interpreted in MacsBug with interrupts disabled, even a complex formatString  has minimal impact on timing results.

MACSBUG POWER USER TIP
If you have more than one monitor, you can use the swap command to make MacsBug always visible and use dprintf with trace to continually log information. You can set which screen MacsBug uses by opening the Monitors control panel, holding down the Option key, and dragging the "Happy Macintosh" to the monitor on which you want to display MacsBug (you have to restart for it to take effect).

MPW POWER USER TIP
At the end of the comment for dprintf in Exceptions.h is a section that uses Echo to pipe code to the assembler.

/*********************************************
Echo "                         ðnð
 PRINT      OFF,NOHDR               ðnð
 INCLUDE    'Traps.a'               ðnð
 PRINT      ON                      ðnð
 PROC                               ðnð
 _DebugStr                          ðnð
 SUBQ       #4,SP   ; Fix the stack ðnð
 ENDPROC                            ðnð
 END                                ðnð
" | Asm -l
*********************************************/

If you select this section and press Enter, it generates a listing with hex output. This is a handy way to generate and document inline functions..

RELATED READING

  • Macintosh Technical Note "A Printing Loop That Cares . . ." (formerly #161).
  • Object-Oriented Software Construction  by Bertrand Meyer (Prentice-Hall, 1988). Contains more information on programming by contract.
  • Debugging Macintosh Software with MacsBug  by Konstantin Othmer and Jim Straus (Addison-Wesley, 1991). Contains additional MacsBug tips.

SEAN PARENT (AppleLink PARENT, Internet parent@apple.com) is  a parent, but Parent is his last name, not his title. He grew up in Renton, Washington, with his parents (you know, the people who produced him), who are also Parents. Sean came to Apple to pursue his lifelong interest in reference manuals. He enjoys a good ANSI standards document duringbreakfast, and likes catchy punch lines such as, "No, no! I said 'ANSI,' not 'ASCII'!" Sean also likes to write a good hack, and consistently comes in next-to-second-best at the annual MacHack MacHax Hack Contest. Unable to hide his prowess, he gave in to the inevitable job at Apple, and now he wants to change the world, one programming paradigm at a time.*

CouldDialog, which was intended as a preflight tool for GetNewDialog, is a no-op in System 7 (it's been broken since the Macintosh II was introduced).*

Seriously insane cycle counters take note that the MPW 3.2 C compiler doesn't reuse a register to store a variable in a local scope when the register was used in a prior scope containing a goto statement (require generates a goto). This can lead to code that isn't as efficient as it should be but can usually be coded around (it's difficult to generate in the first place). Hopefully this will be fixed in a future compiler. *

THANKS TO OUR TECHNICAL REVIEWERS Scott Boyd, Konstantin Othmer, Sam Weiss. Also, special thanks to everyone in the Print Shop (present and former members) for using this stuff and suggesting numerous improvements during the past few years. *

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Apple iBooks Author 2.5 - Create and pub...
Apple iBooks Author helps you create and publish amazing Multi-Touch books for iPad. Now anyone can create stunning iBooks textbooks, cookbooks, history books, picture books, and more for iPad. All... Read more
MYStuff Pro 2.0.26 - $39.99
MYStuff Pro is the most flexible way to create detail-rich inventories for your home or small business. Add items to MYStuff by dragging and dropping existing information, uploading new images, or... Read more
MarsEdit 3.7.8 - Quick and convenient bl...
MarsEdit is a blog editor for OS X that makes editing your blog like writing email, with spell-checking, drafts, multiple windows, and even AppleScript support. It works with with most blog services... Read more
Yasu 3.0.3 - System maintenance app; per...
Yasu was created with System Administrators who service large groups of workstations in mind, Yasu (Yet Another System Utility) was made to do a specific group of maintenance tasks quickly within a... Read more
Yasu 3.0.3 - System maintenance app; per...
Yasu was created with System Administrators who service large groups of workstations in mind, Yasu (Yet Another System Utility) was made to do a specific group of maintenance tasks quickly within a... Read more
MYStuff Pro 2.0.26 - $39.99
MYStuff Pro is the most flexible way to create detail-rich inventories for your home or small business. Add items to MYStuff by dragging and dropping existing information, uploading new images, or... Read more
MarsEdit 3.7.8 - Quick and convenient bl...
MarsEdit is a blog editor for OS X that makes editing your blog like writing email, with spell-checking, drafts, multiple windows, and even AppleScript support. It works with with most blog services... Read more
Apple iBooks Author 2.5 - Create and pub...
Apple iBooks Author helps you create and publish amazing Multi-Touch books for iPad. Now anyone can create stunning iBooks textbooks, cookbooks, history books, picture books, and more for iPad. All... Read more
TunnelBear 3.0.1 - Subscription-based pr...
TunnelBear is a subscription-based virtual private network (VPN) service and companion app, enabling you to browse the internet privately and securely. Features Browse privately - Secure your data... Read more
ExpanDrive 5.4.0 - Access cloud storage...
ExpanDrive builds cloud storage in every application, acts just like a USB drive plugged into your Mac. With ExpanDrive, you can securely access any remote file server directly from the Finder or... Read more

How to build and care for your team in D...
Before you hit the trail and become a dog sledding legend, there’s actually a fair bit of prep work to be done. In Dog Sled Saga, you’re not only racing, you’re also building and caring for a team of furry friends. There’s a lot to consider—... | Read more »
How to win every race in Dog Sled Saga
If I had to guess, I’d say Dog Sled Saga is the most adorable racing game on the App Store right now. It’s a dog sled racing sim full of adorable, loyal puppies. Just look at those fluffy little tails wagging. Behind that cute, pixelated facade is... | Read more »
Let the war games commence in Gunship Ba...
Buzz Lightyear famously said, “This isn’t flying, this is falling – with style!” In the case of Gunship Battle: Second War, though, this really is flying - with style! The flight simulator app from Joycity puts you in control of 20 faithfully... | Read more »
How to get a high score in Fired Up
Fired Up is Noodlecake Games’ high score chasing, firefighting adventure. You take control of a wayward firefighter who propels himself up the side of a highrise with blasts of water. Sound silly? It is. It’s also pretty difficult. You can’t... | Read more »
NBA 2K17 (Games)
NBA 2K17 1.0 Device: iOS iPhone Category: Games Price: $7.99, Version: 1.0 (iTunes) Description: Following the record-breaking launch of NBA 2K16, the NBA 2K franchise continues to stake its claim as the most authentic sports video... | Read more »
Dog Sled Saga (Games)
Dog Sled Saga 1.0.1 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0.1 (iTunes) Description: A game by Dan + Lisa As a rookie musher, foster a dogsledding team whose skills will grow if they're treated right. Week by... | Read more »
60 Seconds! Atomic Adventure (Games)
60 Seconds! Atomic Adventure 1.2 Device: iOS Universal Category: Games Price: $2.99, Version: 1.2 (iTunes) Description: 60 Seconds! is a dark comedy atomic adventure of scavenge and survival. Collect supplies and rescue your family... | Read more »
Tons of Bullets! (Games)
Tons of Bullets! 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Tons of BulletsA retro 2D pixel platformer infused with tons of bullets and tons of features!Fight as Kenji the Ninja and... | Read more »
Sorcery! 4 (Games)
Sorcery! 4 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: *** PLEASE NOTE: Sorcery! 4 requires a minimum of iPad 3 or iPhone 4 *** An epic adventure through a cursed citadel of monsters,... | Read more »
Building the perfect Animation Throwdown...
Animation Throwdown is a casual card game full of plenty of inside jokes from some of your favorite cartoons. It’s accessible as far as card games go, but that’s not to say that it hands your victories to you easily. There’s quite a bit that goes... | Read more »

Price Scanner via MacPrices.net

Duplicate Sweeper Free On Mac App Store For O...
To celebrate the launch of Apple’s latest macOS Sierra, Stafford, United Kingdom based Wide Angle Software has announced that its duplicate file finder software, Duplicate Sweeper, is now available... Read more
13-inch Retina MacBook Pros on sale for up to...
B&H Photo has 13″ Retina Apple MacBook Pros on sale for up to $150 off MSRP. Shipping is free, and B&H charges NY tax only: - 13″ 2.7GHz/128GB Retina MacBook Pro: $1174.99 $125 off MSRP - 13... Read more
Evidence Surfaces Pointing To New A10X Chip F...
Citing a job description for a Project Lead position at Apple’s Austin, Texas engineering labs, Motley Fool’s Ashraf Eassa deduces that development is progressing well on Apple’s next-generation in-... Read more
Check Print’R for macOS Allows Anyone to Easi...
Delaware-based Match Software has announced the release and immediate availability of Check Print’R 3.21, an important update to their easy-to-use check printing application for macOS. Check Print’R... Read more
Apple refurbished 11-inch MacBook Airs availa...
Apple has Certified Refurbished 11″ MacBook Airs (the latest models), available for up to $170 off the cost of new models. An Apple one-year warranty is included with each MacBook, and shipping is... Read more
Apple refurbished 15-inch Retina MacBook Pros...
Apple has Certified Refurbished 2015 15″ Retina MacBook Pros available for up to $380 off the cost of new models. An Apple one-year warranty is included with each model, and shipping is free: - 15″ 2... Read more
Major Version 5 Release Of Free myTuner Radio...
AppGeneration Software has announced the release of myTuner Radio 5.0.1, an important update to their live radio app for iOS and Android platforms. With myTuner Radio, you can listen to more than 30,... Read more
TheAppStore Searches And Filters iOS And macO...
Boston based InchWest has announced the official launch of TheAppStore, a free web based service that lets users search iOS and Mac apps on the web without iTunes or the App store. TheAppStore... Read more
2TB Time Capsule on sale for $199, save $100
Amazon has 2TB Apple Time Capsules on sale for $199 including free shipping. Their price is $100 off MSRP. Choose Amazon as the seller when making your purchase, rather than a third party seller. Read more
12-inch 1.2GHz Rose Gold Retina MacBook on sa...
Amazon.com has the 2016 12″ 1.2GHz Rose Gold Retina MacBook on sale for $1254.02 including free shipping. Their price is $345 off MSRP, and it’s the lowest price available for this model from any... Read more

Jobs Board

*Apple* Retail - Multiple Positions- Manhatt...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Sr. *Apple* Mac Engineer - Net2Source Inc....
…staffing, training and technology. We have following position open with our client. Sr. Apple Mac Engineer6+ Months CTH Start date : 19th Sept Travelling Job If Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Restaurant Manager (Neighborhood Captain) - A...
…in every aspect of daily operation. WHY YOU'LL LIKE IT: You'll be the Big Apple . You'll solve problems. You'll get to show your ability to handle the stress and Read more
US- *Apple* Store Leader Program - Apple (Un...
…Summary Learn and grow as you explore the art of leadership at the Apple Store. You'll master our retail business inside and out through training, hands-on Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.