Mercurial Mercurial > oss > FCL > sftools > depl > docscontent / annotate
summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | file | latest | revisions | annotate | diff | comparison | raw | help
Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Adaptation/GUID-12EFB295-C527-5F96-81F1-6021D335D865.dita
author Graeme Price <GRAEME.PRICE@NOKIA.COM>
Fri, 15 Oct 2010 14:32:18 +0100
changeset 15 307f4279f433
permissions -rw-r--r--
Initial contribution of the Adaptation Documentation.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
15
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
     1
 
<?xml version="1.0" encoding="utf-8"?>
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
     2
 
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
     3
 
<!-- This component and the accompanying materials are made available under the terms of the License
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
     4
 
"Eclipse Public License v1.0" which accompanies this distribution,
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
     5
 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
     6
 
<!-- Initial Contributors:
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
     7
 
    Nokia Corporation - initial contribution.
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
     8
 
Contributors:
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
     9
 
-->
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    10
 
<!DOCTYPE concept
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    11
 
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    12
 
<concept id="GUID-12EFB295-C527-5F96-81F1-6021D335D865" xml:lang="en"><title>Thread
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    13
 
Termination</title><shortdesc>This topic describes how and in what conditions to kill a kernel
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    14
 
side thread. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    15
 
<p>The only way to kill a kernel side thread is for code running in that thread
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    16
 
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>
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    17
 
<p>A kernel side thread can kill itself, but cannot kill any other kernel
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    18
 
side thread. This avoids the overhead of critical sections. Remember that
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    19
 
a kernel side thread <i>can</i> kill a user side thread. </p>
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    20
 
<p>In practice, device drivers will create threads that can run queued DFCs
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    21
 
(Deferred Function Calls) only if they choose not to use the two supplied
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    22
 
DFC threads, known as DFC thread 0 and DFC thread 1. </p>
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    23
 
<section id="GUID-A5B308C7-21CE-437E-A033-A373E1E2FE78"><title>How to kill a thread running queued DFCs</title> <p>In principle
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    24
 
the only way to kill a thread that runs queued DFCs is to schedule a DFC that
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    25
 
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
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    26
 
0 (the lowest). We refer to this as a 'kill' DFC. </p> <p>In practice you
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    27
 
create a 'kill' DFC by creating a <xref href="GUID-A14562A5-3E91-3113-AB3C-71DBEA9D58EB.dita"><apiname>TDfc</apiname></xref> object, and then
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    28
 
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>.
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    29
 
You then queue the DFC onto the DFC queue, a <xref href="GUID-24B2FEDB-9273-351F-A1C6-6F5F91BF83B7.dita"><apiname>TDfcQue</apiname></xref> object,
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    30
 
from the destructor of the logical device driver's factory class, i.e. the
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    31
 
destructor of the class derived from <xref href="GUID-7616AA05-83E6-3989-AB9D-11AE01245BEB.dita"><apiname>DLogicalDevice</apiname></xref>. </p> </section>
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    32
 
<section id="GUID-3DB34648-94EC-4AF4-9550-EF7753FC18BE"><title>Issues to be aware of</title> <ol id="GUID-6335774D-CEDB-52AE-BBED-AFA7CB55DFF5">
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    33
 
<li id="GUID-0573932A-B43C-50B0-9458-B213A6C4346F"><p>You need to make sure
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    34
 
that no other DFCs are on that DFC queue at the time that the 'kill' DFC runs
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    35
 
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>)
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    36
 
on all queued DFCs. </p> </li>
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    37
 
<li id="GUID-F9D0239F-9174-54B5-B39B-5D1E54FF6EF5"><p>You need to make sure
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    38
 
that the DFC queue object, i.e. the <xref href="GUID-24B2FEDB-9273-351F-A1C6-6F5F91BF83B7.dita"><apiname>TDfcQue</apiname></xref> object, and
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    39
 
the 'kill' DFC object, i.e. the <xref href="GUID-A14562A5-3E91-3113-AB3C-71DBEA9D58EB.dita"><apiname>TDfc</apiname></xref> object, are not destroyed
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    40
 
before the 'kill' DFC has a chance to run. </p> <p>You can do this by making
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    41
 
both the DFC queue object and the 'kill' DFC object static objects within
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    42
 
the driver. The device driver will only be unloaded from RAM by the null thread.
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    43
 
By queuing the 'kill' DFC on the DFC thread, you mark it ready-to-run, which
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    44
 
means that your 'kill' DFC will run before the driver is unloaded and before
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    45
 
the DFC queue object and the 'kill' DFC object vanish. </p> </li>
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    46
 
<li id="GUID-29195090-756E-5FB7-BF78-0F6C6C5A7983"><p>You need to make sure
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    47
 
that any code queued to run on your DFC thread never hangs. </p> <p>The important
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    48
 
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
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    49
 
itself, but if the thread hangs, then it can execute nothing. This means that
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    50
 
kernel side threads must be written very carefully so they cannot hang. Any
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    51
 
defect in kernel side code is likely to be fatal. </p> <p>It may be that you
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    52
 
have to consider writing defensive style code; for example, if your thread
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    53
 
is waiting for an event, you could consider using a timer to wake it up in
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    54
 
case the expected event never happens. Alternatively, you could consider moving
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    55
 
some processing to the user side. </p> </li>
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    56
 
</ol> </section>
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    57
 
</conbody></concept>
FCL/sftools/depl/docscontent