--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Adaptation/GUID-12EFB295-C527-5F96-81F1-6021D335D865.dita	Fri Oct 15 14:32:18 2010 +0100
@@ -0,0 +1,57 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
+<!-- This component and the accompanying materials are made available under the terms of the License 
+"Eclipse Public License v1.0" which accompanies this distribution, 
+and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
+<!-- Initial Contributors:
+    Nokia Corporation - initial contribution.
+Contributors: 
+-->
+<!DOCTYPE concept
+  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="GUID-12EFB295-C527-5F96-81F1-6021D335D865" xml:lang="en"><title>Thread
+Termination</title><shortdesc>This topic describes how and in what conditions to kill a kernel
+side thread. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>The only way to kill a kernel side thread is for code running in that thread
+to call <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-808B3622-BDC4-376D-96E9-16281BA28AF8"><apiname>Kern::Exit()</apiname></xref>. </p>
+<p>A kernel side thread can kill itself, but cannot kill any other kernel
+side thread. This avoids the overhead of critical sections. Remember that
+a kernel side thread <i>can</i> kill a user side thread. </p>
+<p>In practice, device drivers will create threads that can run queued DFCs
+(Deferred Function Calls) only if they choose not to use the two supplied
+DFC threads, known as DFC thread 0 and DFC thread 1. </p>
+<section id="GUID-A5B308C7-21CE-437E-A033-A373E1E2FE78"><title>How to kill a thread running queued DFCs</title> <p>In principle
+the only way to kill a thread that runs queued DFCs is to schedule a DFC that
+simply calls <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-808B3622-BDC4-376D-96E9-16281BA28AF8"><apiname>Kern::Exit()</apiname></xref>. The DFC should have priority
+0 (the lowest). We refer to this as a 'kill' DFC. </p> <p>In practice you
+create a 'kill' DFC by creating a <xref href="GUID-A14562A5-3E91-3113-AB3C-71DBEA9D58EB.dita"><apiname>TDfc</apiname></xref> object, and then
+make the DFC's callback function include a call to <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-808B3622-BDC4-376D-96E9-16281BA28AF8"><apiname>Kern::Exit()</apiname></xref>.
+You then queue the DFC onto the DFC queue, a <xref href="GUID-24B2FEDB-9273-351F-A1C6-6F5F91BF83B7.dita"><apiname>TDfcQue</apiname></xref> object,
+from the destructor of the logical device driver's factory class, i.e. the
+destructor of the class derived from <xref href="GUID-7616AA05-83E6-3989-AB9D-11AE01245BEB.dita"><apiname>DLogicalDevice</apiname></xref>. </p> </section>
+<section id="GUID-3DB34648-94EC-4AF4-9550-EF7753FC18BE"><title>Issues to be aware of</title> <ol id="GUID-6335774D-CEDB-52AE-BBED-AFA7CB55DFF5">
+<li id="GUID-0573932A-B43C-50B0-9458-B213A6C4346F"><p>You need to make sure
+that no other DFCs are on that DFC queue at the time that the 'kill' DFC runs
+as there is no automatic cleanup. </p> <p>Perform cleanup by calling <codeph>Cancel()</codeph> (i.e. <xref href="GUID-A14562A5-3E91-3113-AB3C-71DBEA9D58EB.dita#GUID-A14562A5-3E91-3113-AB3C-71DBEA9D58EB/GUID-9851B90B-8D05-3C86-B083-44C4564AC140"><apiname>TDfc::Cancel()</apiname></xref>)
+on all queued DFCs. </p> </li>
+<li id="GUID-F9D0239F-9174-54B5-B39B-5D1E54FF6EF5"><p>You need to make sure
+that the DFC queue object, i.e. the <xref href="GUID-24B2FEDB-9273-351F-A1C6-6F5F91BF83B7.dita"><apiname>TDfcQue</apiname></xref> object, and
+the 'kill' DFC object, i.e. the <xref href="GUID-A14562A5-3E91-3113-AB3C-71DBEA9D58EB.dita"><apiname>TDfc</apiname></xref> object, are not destroyed
+before the 'kill' DFC has a chance to run. </p> <p>You can do this by making
+both the DFC queue object and the 'kill' DFC object static objects within
+the driver. The device driver will only be unloaded from RAM by the null thread.
+By queuing the 'kill' DFC on the DFC thread, you mark it ready-to-run, which
+means that your 'kill' DFC will run before the driver is unloaded and before
+the DFC queue object and the 'kill' DFC object vanish. </p> </li>
+<li id="GUID-29195090-756E-5FB7-BF78-0F6C6C5A7983"><p>You need to make sure
+that any code queued to run on your DFC thread never hangs. </p> <p>The important
+point is that <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-808B3622-BDC4-376D-96E9-16281BA28AF8"><apiname>Kern::Exit()</apiname></xref> can only be used by the thread
+itself, but if the thread hangs, then it can execute nothing. This means that
+kernel side threads must be written very carefully so they cannot hang. Any
+defect in kernel side code is likely to be fatal. </p> <p>It may be that you
+have to consider writing defensive style code; for example, if your thread
+is waiting for an event, you could consider using a timer to wake it up in
+case the expected event never happens. Alternatively, you could consider moving
+some processing to the user side. </p> </li>
+</ol> </section>
+</conbody></concept>
\ No newline at end of file