<?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-16AB388A-ED3E-4901-857D-834072437D25" xml:lang="en"><title>Spin
Locks</title><shortdesc>Spin locks allow resource execution control through fast lock context
switching. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-9AE2107C-CEA2-453E-9E89-5F1075370F86"><title>Introduction</title><p>Spin
locks are a type of lock mechanism. In a spin lock, the thread will simply
wait in a loop checking for the resource to become available. It is the execution
of the thread waiting in a loop ("spins"), that gives this lock mechanism
its name. The thread will only come out of the loop once the resource is available.</p><p>When
using a spin lock, the following should be noted :</p><ul>
<li><p>Spin locks should only be used in environments where the waiting period
will be short</p></li>
<li><p>Spin locks are very wasteful, since the thread in question is always
in the active state</p></li>
<li><p>Spin locks can lock/unlock very quickly, since the thread never changes
state</p></li>
<li><p>For spin locks to work on the Symbian platform, the interrupts have
to be disabled before use. This is due to the fact that spin locks do not
protect against interrupts from occurring on the same CPU.</p></li>
</ul><p>Because of these properties, spin locks are used in environments where
the operation has to be fast and where the waiting times have to be short.
For this reason, on the Symbian platform they are only used in kernel code.
If a more efficient use of thread processing time is required, then a mutex
should be used.</p><p>There are two types of spin lock:</p><ul>
<li><p>spin locks and</p></li>
<li><p>read write spin locks.</p></li>
</ul><p>The difference between the two types of spin locks is that the read
write spin locks have been optimised to allow multiple reading threads to
acquire the lock simultaneously.</p>     </section>
<section id="GUID-B99EB4FC-3845-4B04-928F-914EFCB879F5"><title>Required interrupt
behaviour</title><p>When using spin locks, the following steps have to be
carried out:</p><ol>
<li id="GUID-B1271135-AC0F-4E19-9077-915B71E8618E"><p>disable the interrupts</p></li>
<li id="GUID-0422F03D-D250-47C9-9255-49BEA54B9D54"><p>acquire the lock</p></li>
<li id="GUID-593FDE3C-8509-4329-B258-009139095785"><p>enable the interrupts
after the lock is released.</p></li>
</ol><p>If the above steps have not been carried out, then a dead lock condition
could occur.</p></section>
<section id="GUID-5DBAD802-F902-4B5E-A190-40BC05313FEA"><title>The types of
spin locks available</title><p>There are two types of spin locks on the Symbian
platform. These are spin locks and read write spin locks. Read write spin
locks are described in the next section.</p><p>There are two ways of implementing
spin locks on the Symbian platform:</p><ul>
<li><p>A Spin lock API and</p></li>
<li><p>the use of spin lock macros.</p></li>
</ul><p>The spin lock API should never be used directly, instead the macros
should be used. This is due to:</p><ul>
<li><p>The spin lock macros carry out the required interrupt enable/disable
operations</p></li>
<li><p>The spin lock macros provide compatibility between SMP and non-SMP
builds.</p></li>
</ul><p>The spin lock API is only for internal use and should never be used.
For spin locks it is provided by the <xref href="GUID-FB1605A8-9946-364C-A649-DEF60E1F761B.dita"><apiname>TSpinLock</apiname></xref> class and
is defined in <filepath>nkern.h</filepath>. It will not be discussed any further.</p><p>The
spin lock macros available are :</p><table id="GUID-CF9670A1-AB07-4451-AB4F-20F44D8FC5F9">
<tgroup cols="5"><colspec colname="col1" colwidth="0.96*"/><colspec colname="col2" colwidth="0.96*"/><colspec colname="col3" colwidth="0.97*"/><colspec colname="COLSPEC0" colwidth="0.97*"/><colspec colname="col4" colwidth="1.15*"/>
<tbody>
<row>
<entry><p><b>Macro</b></p></entry>
<entry><p><b>Parameter 1</b></p><p><b>Purpose and Data Type</b></p></entry>
<entry><p><b>Parameter 2</b></p><p><b>Purpose and Data Type</b></p></entry>
<entry><p><b>Return Value</b></p><p><b>Purpose and Data Type</b></p></entry>
<entry><p><b>Operation</b></p></entry>
</row>
<row>
<entry><p>__SPIN_LOCK_IRQSAVE(lock)</p></entry>
<entry><p>The spin lock order.</p><xref href="GUID-FB1605A8-9946-364C-A649-DEF60E1F761B.dita"><apiname>TSpinLock</apiname></xref></entry>
<entry><p>N/A</p></entry>
<entry><p>The original interrupt state.</p><xref href="GUID-7A2A43EC-6125-3BFE-834B-23C37F7B40D5.dita"><apiname>TInt</apiname></xref></entry>
<entry><p>Disable interrupts and acquire the lock.</p></entry>
</row>
<row>
<entry><p>__SPIN_UNLOCK_IRQRESTORE(lock,irq)</p></entry>
<entry><p>The spin lock order.</p><xref href="GUID-FB1605A8-9946-364C-A649-DEF60E1F761B.dita"><apiname>TSpinLock</apiname></xref></entry>
<entry><p>The interrupt state</p><xref href="GUID-7A2A43EC-6125-3BFE-834B-23C37F7B40D5.dita"><apiname>TInt</apiname></xref></entry>
<entry><p>N/A</p></entry>
<entry><p>Release the lock, then restore the interrupt state.</p></entry>
</row>
<row>
<entry><p>__SPIN_FLASH_IRQRESTORE(lock,irq)</p></entry>
<entry><p>The spin lock order.</p><xref href="GUID-FB1605A8-9946-364C-A649-DEF60E1F761B.dita"><apiname>TSpinLock</apiname></xref></entry>
<entry><p>The interrupt state.</p><xref href="GUID-7A2A43EC-6125-3BFE-834B-23C37F7B40D5.dita"><apiname>TInt</apiname></xref></entry>
<entry><p>ETrue if the lock/unlock operation has occurred, otherwise EFalse.</p><xref href="GUID-4B942C06-1BAC-3A21-B3B1-89FB5C51ADA0.dita"><apiname>TBool</apiname></xref></entry>
<entry><p>If another thread is waiting for the spin lock or there is an interrupt
pending, then execute the __SPIN_UNLOCK_IRQRESTORE macro and then execute
the __SPIN_LOCK_IRQ macro.</p></entry>
</row>
<row>
<entry><p>__SPIN_LOCK(lock)</p></entry>
<entry><p>The spin lock order.</p><xref href="GUID-FB1605A8-9946-364C-A649-DEF60E1F761B.dita"><apiname>TSpinLock</apiname></xref></entry>
<entry><p>N/A</p></entry>
<entry><p>N/A</p></entry>
<entry><p>Acquire the lock, assuming the interrupts and preemption have been
disabled.</p></entry>
</row>
<row>
<entry><p>__SPIN_UNLOCK(lock)</p></entry>
<entry><p>The spin lock order.</p><xref href="GUID-FB1605A8-9946-364C-A649-DEF60E1F761B.dita"><apiname>TSpinLock</apiname></xref></entry>
<entry><p>N/A</p></entry>
<entry><p>N/A</p></entry>
<entry><p>Release the lock without changing the interrupt and preemption states.</p></entry>
</row>
<row>
<entry><p>__SPIN_FLASH_PREEMPT(lock)</p></entry>
<entry><p>The spin lock order.</p><xref href="GUID-FB1605A8-9946-364C-A649-DEF60E1F761B.dita"><apiname>TSpinLock</apiname></xref></entry>
<entry><p>N/A</p></entry>
<entry><p>ETrue if the lock/unlock operation has occurred, otherwise EFalse.</p><xref href="GUID-4B942C06-1BAC-3A21-B3B1-89FB5C51ADA0.dita"><apiname>TBool</apiname></xref></entry>
<entry><p>If another thread is waiting for the lock, then execute (after the
unlock <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-C9314237-B43B-34E0-9108-E8861196022E"><apiname>NKern::PreemptionPoint</apiname></xref> has been called) the __SPIN_UNLOCK
macro and then the __SPIN_LOCK macro.</p></entry>
</row>
<row>
<entry><p>__SPIN_LOCK_IRQ(lock)</p></entry>
<entry><p>The spin lock order.</p><xref href="GUID-FB1605A8-9946-364C-A649-DEF60E1F761B.dita"><apiname>TSpinLock</apiname></xref></entry>
<entry><p>N/A</p></entry>
<entry><p>N/A</p></entry>
<entry><p>Disable interrupts and acquire the lock.</p></entry>
</row>
<row>
<entry><p>__SPIN_UNLOCK_IRQ(lock)</p></entry>
<entry><p>The spin lock order.</p><xref href="GUID-FB1605A8-9946-364C-A649-DEF60E1F761B.dita"><apiname>TSpinLock</apiname></xref></entry>
<entry><p>N/A</p></entry>
<entry><p>N/A</p></entry>
<entry><p>Release the lock, then enable the interrupts.</p></entry>
</row>
<row>
<entry><p>__SPIN_FLASH_IRQ(lock)</p></entry>
<entry><p>The spin lock order.</p><xref href="GUID-FB1605A8-9946-364C-A649-DEF60E1F761B.dita"><apiname>TSpinLock</apiname></xref></entry>
<entry><p>N/A</p></entry>
<entry><p>ETrue if the lock/unlock operation has occurred, otherwise EFalse.</p><xref href="GUID-4B942C06-1BAC-3A21-B3B1-89FB5C51ADA0.dita"><apiname>TBool</apiname></xref></entry>
<entry><p>If another thread is waiting for the spin lock or if there is an
interrupt pending, then execute the __SPIN_UNLOCK_IRQ macro and then execute
the __SPIN_LOCK_IRQ macro.</p></entry>
</row>
</tbody>
</tgroup>
</table><p>The spin lock order parameter is used to provide a priority of
the spin lock. The spin lock order parameter allows spin locks to be nested
and to guard against deadlocks.</p><p>The list of acceptable spin lock order
values are defined in <filepath>nkern.h</filepath>.</p><p>Which spin lock
macro should be used is shown in the following table :</p><table id="GUID-FD737DFA-85A9-4C8F-BE02-2CCB08096E65">
<tgroup cols="4"><colspec colname="col1" colwidth="0.58*"/><colspec colname="col2" colwidth="0.84*"/><colspec colname="col3" colwidth="1.29*"/><colspec colname="col4" colwidth="1.29*"/>
<tbody>
<row>
<entry><p><b>Is the spin lock to be used within an ISR ?</b></p></entry>
<entry><p><b>The ISR State</b></p></entry>
<entry><p><b>Other Circumstances to Consider</b></p></entry>
<entry><p><b>The Spin Lock Macros to Use</b></p></entry>
</row>
<row>
<entry><p>Yes</p></entry>
<entry><p>Unknown</p></entry>
<entry><p>None</p></entry>
<entry><p>__SPIN_LOCK_IRQSAVE(lock)</p></entry>
</row>
<row>
<entry/>
<entry/>
<entry/>
<entry><p>__SPIN_UNLOCK_IRQRESTORE(lock,irq)</p></entry>
</row>
<row>
<entry/>
<entry/>
<entry/>
<entry><p>__SPIN_FLASH_IRQRESTORE(lock,irq)</p></entry>
</row>
<row>
<entry><p>N/A</p></entry>
<entry><p>The interrupts have already been disabled.</p></entry>
<entry><p>None</p></entry>
<entry><p>__SPIN_LOCK(lock)</p></entry>
</row>
<row>
<entry/>
<entry/>
<entry/>
<entry><p>__SPIN_UNLOCK(lock)</p></entry>
</row>
<row>
<entry/>
<entry/>
<entry/>
<entry><p>__SPIN_FLASH_IRQRESTORE(lock,irq)</p></entry>
</row>
<row>
<entry><p>No</p></entry>
<entry><p>N/A</p></entry>
<entry><p>Code is within a pair of <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-61C8A02A-B7F9-3BF9-B677-6BF83C6972B0"><apiname>NKern::Lock</apiname></xref>/<xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-A1DA547A-B5C2-3951-9613-DC1D6A313C70"><apiname>NKern::Unlock</apiname></xref> statements.</p></entry>
<entry><p>__SPIN_LOCK(lock)</p></entry>
</row>
<row>
<entry/>
<entry/>
<entry/>
<entry><p>__SPIN_UNLOCK(lock)</p></entry>
</row>
<row>
<entry/>
<entry/>
<entry/>
<entry><p>__SPIN_FLASH_PREEMPT(lock)</p></entry>
</row>
<row>
<entry><p>Yes</p></entry>
<entry><p>Known</p></entry>
<entry><p>The interrupts must already be disabled.</p></entry>
<entry><p>__SPIN_LOCK_IRQ(lock)</p></entry>
</row>
<row>
<entry/>
<entry/>
<entry/>
<entry><p>__SPIN_UNLOCK_IRQ(lock)</p></entry>
</row>
<row>
<entry/>
<entry/>
<entry/>
<entry><p>__SPIN_FLASH_IRQ(lock)</p></entry>
</row>
</tbody>
</tgroup>
</table><note/><p>Only the above combinations of interrupt states and
spin lock macros are allowed.</p><p>The spin lock macros __SPIN_LOCK_IRQSAVE
and __SPIN_UNLOCK_IRQRESTORE would be used in almost all cases.</p></section>
<section id="GUID-85F32921-FE0C-48EE-9B88-C45A76DC8481"><title>How to Use
Spin Locks</title><p>An example of how to use the spin lock macros is :</p><codeblock xml:space="preserve">TInt irq = __SPIN_LOCK_IRQSAVE(EOrderThread);
// some code...
__SPIN_UNLOCK_IRQSTORE(EOrderThread,irq);</codeblock><p>The first line calls
the macro to disable the interrupts and acquire the spin lock. This line returns
the original interrupt state (stored in the variable irq).</p><p>The last
line calls the macro to release the spin lock and then restore the IRQ to
its original state.</p></section>
<section id="GUID-66A13635-5DDD-40D3-B113-234D811ACBF2"><title>Read Write
Spin Locks</title><p>This sub set of spin locks allows for the multiple reading
threads to acquire the lock simultaneously. The operation of read write spin
locks is :</p><table id="GUID-FB47DAFD-955C-4E3B-93B3-293CC54910FD">
<tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/>
<tbody>
<row>
<entry><p><b>Behaviour</b></p></entry>
<entry><p><b>Required Conditions</b></p></entry>
</row>
<row>
<entry><p>Acquire the lock for a read operation</p></entry>
<entry><p>The lock is either free or is being held for reading</p></entry>
</row>
<row>
<entry><p>Blocked for a read operation</p></entry>
<entry><p>The lock is held for a write operation</p></entry>
</row>
<row>
<entry><p>Acquire the lock for a write operation</p></entry>
<entry><p>The lock is free</p></entry>
</row>
<row>
<entry><p>Blocked for a write operation</p></entry>
<entry><p>The lock is held for a read or a write operation</p></entry>
</row>
</tbody>
</tgroup>
</table><p>The macros are the same name as for the spin locks, except :</p><table id="GUID-7FB86C27-DDC5-4AC3-982F-2736FBA9BAA8">
<tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/>
<tbody>
<row>
<entry><p><b>Operation</b></p></entry>
<entry><p><b>Postfix</b></p></entry>
</row>
<row>
<entry><p>read access</p></entry>
<entry><p>_R</p></entry>
</row>
<row>
<entry><p>write access</p></entry>
<entry><p>_W</p></entry>
</row>
</tbody>
</tgroup>
</table><p>An example of the use of read write spin lock macros are __SPIN_LOCK_IRQ_R(lock)
and __SPIN_UNLOCK_IRQ_W(lock).</p><p>Read write spin locks are implemented
by the <xref href="GUID-F8145088-041C-35E3-9AB2-AF151832ECC8.dita"><apiname>TRWSpinLock</apiname></xref> class. As with the <xref href="GUID-FB1605A8-9946-364C-A649-DEF60E1F761B.dita"><apiname>TSpinLock</apiname></xref> class,
this class is for internal use only and will not be discussed any further.</p><p>An
example of the use of read write spin locks is :</p><codeblock xml:space="preserve">
__SPIN_LOCK_IRQ_R(EOrderThread);
// some code...
__SPIN_UNLOCK_IRQ_R(EOrderThread);</codeblock></section>
</conbody><related-links>
<link href="GUID-CE72E71B-6ED3-4961-B4C5-C43D823ACA9D.dita"><linktext>SMP Overview</linktext>
</link>
</related-links></concept>