1. 7-1 JMH Associates © 2003, All rights reserved Designing and Developing Reliable, Scaleable Multithreaded Windows Applications Chapter 10 Supplement Advanced Features

2. 7-2 JMH Associates © 2003, All rights reserved OBJECTIVESOBJECTIVES Upon completion of this chapter, you will be able to:  Utilize asynchronous procedure calls  Cancel threads asynchronously  Send signals to specific threads  Put threads in an alertable wait state  Create and use waitable timers

3. 7-3 JMH Associates © 2003, All rights reserved ContentsContents 1.Asynchronous Procedure Calls 2.Alertable Wait Functions 3.APCs and the Baton Example 4.Waitable Timers 5.Asynchronous I/O Quick Overview 6.Lab Exercise 10-Advanced Features

4. 7-4 JMH Associates © 2003, All rights reserved 1. Asynchronous Procedure Calls Similar to completion routine I/O (not covered)  Also specify the thread where the function is to execute  Caution: One thread directly affects another  >= NT 4.0 DWORD QueueUserAPC ( PAPCFUNC pfnAPC, // APC function // void WINAPI, DWORD arg HANDLE hThread, // thread handle ULONG_PTR dwData // APC param); Non-zero is success – GetLastError does not work here

5. 7-5 JMH Associates © 2003, All rights reserved APC Semantics Queues the APC to the specified thread When the target thread enters an alertable state:  A procedure is removed from its queue  The procedure is executed  It receives the specified parameter A thread enters the alertable state with an “alertable wait”  Indicating that it is safe to execute the APC  Example: SignalOjbectAndWait – Fourth parameter is bAleratble (set to TRUE )  Alertable wait function return WAIT_IO_COMPLETION if an APC was executed (and handle not signaled)

6. 7-6 JMH Associates © 2003, All rights reserved 2. Alertable Wait Functions Options to several wait functions – Usually “Ex” versions DWORD SleepEx( DWORD dwMilliseconds, BOOL bAlertable ); Returns as soon as either:  Timeout expires  If bAlerable is set, and an APC is executed WaitForSingleObjectEx ( …, BOOL bAlertable); WaitForMultipleObjectsEx (…, BOOL bAlertable);

7. 7-7 JMH Associates © 2003, All rights reserved Using APCs A boss thread can force a worker to shutdown orderly  TerminateThread() is not orderly  The APC is executed as soon as it is safe to do so  That is, the thread is in an altertable wait state  The APC:  Cleans up and frees resources  Terminates with _endthreadex (ExitCode) This is “synchronous thread cancellation”  Demonstrated in the lab exercise Orderly asynchronous cancellation not directly supported

8. 7-8 JMH Associates © 2003, All rights reserved 3. APCs and the Baton Example Outline - A different solution than in Chapter 10 - compound  Event limitation: Can’t specify which waiting thread is released  So, all threads are released and test if it is their turn  Only one proceeds  Each waiting thread has its own unique event  Event / thread sequence stored in searchable structure  Such as an STL map  Queue an APC to the correct target thread  Target threads wait with altertable waits

9. 7-9 JMH Associates © 2003, All rights reserved 4. Waitable Timers A type of waitable kernel object >= Win2K Perform tasks periodically or at specified times Create your own timing signal:  Create a timing thread  Thread sets an event after waking from a Sleep Two types:  Synchronization timer: Uses a callback – must be in an alertable wait state  Manual reset notification timer: wait on the timer handle

10. 7-10 JMH Associates © 2003, All rights reserved Waitable Timers HANDLE CreateWaitableTimer( LPSECURITY_ATTRIBUTES lpTimerAttributes, BOOL bManualReset, // Manual reset state LPCTSTR lpTimerName // *timer object name ); The timer is initially inactive but is later activated Named, so they is an OpenWaitableTimer function

11. 7-11 JMH Associates © 2003, All rights reserved Setting the Waitable timer BOOL SetWaitableTimer( HANDLE hTimer, const LARGE_INTEGER *pDueTime, LONG lPeriod, // periodic timer interval PTIMERAPCROUTINE pfnCompletionRoutine, LPVOID lpArgToCompletionRoutine, BOOL fResume // flag for resume state );

12. 7-12 JMH Associates © 2003, All rights reserved Canceling the Waitable Timer CancelWaitableTimer cancels the last effect of a previous SetWaitableTimer  It will not change the signaled state of the timer  Use another SetWaitableTimer to do that BOOL CancelWaitableTimer( HANDLE hTimer );

13. 7-13 JMH Associates © 2003, All rights reserved 5. Asynchronous I/O Quick Overview Issue I/O (read, write) asynchronously  Supported internally with threads  Opinion: Complex to use  Demos if we have time Two types:  Overlapped I/O – Wait on an event or file handle for I/O completion  Extended I/O – Callback function invoked upon I/O completion  Must be in alertable wait state before the callback is invoked Also: I/O completion ports – Overlapped I/O  Small thread pool, multiple I/Os. Thread assigned on I/O completion

14. 7-14 JMH Associates © 2003, All rights reserved Lab Exercise 10-Advanced Features Modify ThreeStage.c to eliminate the TerminateThread calls, using an APC You will also need to add alertable waits to QueueObj.c ThreeStageCancel.c, QueueObcCancel.c provide a solution

15. 7-15 JMH Associates © 2003, All rights reserved NotesNotes

16. 7-16 JMH Associates © 2003, All rights reserved NotesNotes