<?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>