PANICKING ANOTHER THREAD

251

CleanupStack::Pop(ptr2); // ...so the code never gets here

}

As a user, if making the chess move you’ve carefully worked out causes your game to panic and close, you’re probably not interested in the category or error code. Such precise details are irrelevant and the ”program closed” dialog is more irritating than helpful.

Don’t use panics except as a means to eliminate programming errors, for example by using them in assertion statements. Panicking cannot be seen as useful functionality for properly debugged software; a panic is more likely to annoy users than inform them.

15.4 Panicking Another Thread

I’ve shown how to call User::Panic() when you want the thread to panic itself. But how, and when, should you use RThread::Panic()? As I described earlier, the RThread::Panic() function can be used to kill another thread and indicate that the thread had a programming error. Typically this is used by a server to panic a client thread when the client passes a badly-formed request. You can think of it as server self-defense; rather than go ahead and attempt to read or write to a bad descriptor, the server handles the client’s programming error gracefully by panicking the client thread. It is left in a good state which it would not have been if it had just attempted to use the bad descriptor. Generally, in a case like this, the malformed client request has occurred because of a bug in the client code, but this strategy also protects against more malicious ”denial of service” attacks in which a client may deliberately pass a badly-formed or unrecognized request to a server to try to crash it. The Symbian OS client–server architecture is discussed in Chapters 11 and 12; the latter chapter includes sample code that illustrates how a server can panic its client.

If you have a handle to a thread which has panicked, you can determine the exit reason and category using ExitReason() and ExitCategory(). This can be useful if you want to write test code to check that the appropriate panics occur, say from assertions in your library code, to defend it against invalid parameters. Since you can’t ”catch” a panic, it’s not as straightforward as running the code in the main thread, passing in the parameters and checking that the code panics with the correct value. The checking code would never run, because the panic would terminate the main thread.

252

PANICS

A solution is to run deliberately badly-behaved client code in a separate test thread, programmatically checking the resulting exit reasons and categories of the panicked thread against those you would expect to have occurred. You should disable just-in-time debugging for the duration of the test, so that only the test thread, rather than the emulator, is terminated. For example:

enum TChilliStrength

{

ESweetPepper,

EJalapeno, EScotchBonnet };

void EatChilli(TChilliStrength aStrength)

{

_LIT(KTooStrong, "Too Strong!"); __ASSERT_ALWAYS(EScotchBonnet!=aStrength,

User::Panic(KTooStrong, KErrAbort);

... // Omitted for clarity

}

// Thread function

TInt TestPanics(TAny* /*aData*/)

{// A panic occurs if code is called incorrectly EatChilli(EScotchBonnet);

return (KErrNone);

}

void TestDefence()

{

//Save current just-in-time status TBool jitEnabled = User::JustInTime();

//Disable just-in-time debugging for this test User::SetJustInTime(EFalse);

_LIT(KPanicThread, "PanicThread");

// Create a separate thread in which to run the panic testing RThread testThread;

TInt r = testThread.Create(KPanicThread, TestPanics,

KDefaultStackSize, NULL, NULL);

ASSERT(KErrNone==r);

// Request notification of testThread’s death (see Chapter 10) TRequestStatus tStatus;

testThread.Logon(tStatus);

testThread.Resume();

User::WaitForRequest(tStatus); // Wait until the thread dies

ASSERT(testThread.ExitType()==EExitPanic); // Test the panic reason is as expected ASSERT(testThread.ExitReason()==KErrAbort);

testThread.Close();

// Set just-in-time back to previous setting User::SetJustInTime(jitEnabled);

}

SUMMARY

253

15.5 Faults, Leaves and Panics

A fault is raised if a critical error occurs such that the operating system cannot continue normal operation. On hardware, this results in a reboot. A fault can only occur in kernel-side code or a thread which is essential to the system, for example the file server, so typically you will not encounter them unless you are writing device drivers or uncover a bug in the OS. In effect, a fault is another name for a serious system panic.

Chapter 2 discusses leaves in more detail, but, in essence, they occur under exceptional conditions such as out of memory or the absence of a communications link. Unlike a panic, a leave should always be caught (”trapped”) by code somewhere in the call stack, because there should always be a top-level TRAP. However, if a leave is not caught, this implies that the top-level TRAP is absent (a programming error) and the thread will be panicked and terminate.

15.6 Summary

This chapter discussed the use of panics to terminate the flow of execution of a thread. Panics cannot be ”caught” like an exception and are severe, resulting in a poor user experience. For that reason, panics are only useful to track down programming errors and, on Symbian OS, are typically combined with an assertion statement, as discussed in the next chapter.

This chapter described the best way to identify panics and illustrated how to test the panics that you’ve added to your own code for defensive programming. It gave a few examples of commonly-encountered system panics and directed you to the Panics section of the system documentation for a detailed listing of Symbian OS system panics.