<?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-5FBA9BB1-94A2-470C-9932-C4255E3774C0" xml:lang="en"><title>Shared
Memory between Threads</title><shortdesc>This document describes the shared memory between threads and how
to avoid race conditions.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>Shared memory is a method of InterProcess Communication (IPC) where a single
chunk of memory is shared between two or more processes. It is used to communicate
between threads within a process or two unrelated processes, allowing both
to share a given region of memory efficiently. In an SMP system, multiple
cores are running threads at the same time and not just virtually as in unicore.
Extra caution is needed to handle memory that shared between multiple threads.</p>
<p>A thread is the unit of execution within a process. Every time a process
is initialized, a primary thread is created. For many applications the primary
thread is the only one that the application requires, however, processes can
create additional threads. In an SMP system, multiple threads can be executing
the same (shared) functions simultaneously. Therefore functions need to deal
with this situation in order to maintain consistency of the system.</p>
<p>Following are the key concepts to synchronize threads:</p>
<ul>
<li><p><b>Mutexes</b> are used to serialize access to a section of re-entrant
code that cannot be executed concurrently by more than one thread. A mutex
object only allows one thread into a controlled section, forcing other threads
which attempt to gain access to that section to wait until the first thread
has exited from that section. A mutex can be used by threads across any number
of processes. If a resource is only shared between the threads within the
same process, it can be more efficient to use a critical section.</p></li>
</ul>
<ul>
<li><p><b>Semaphores</b> restrict the number of simultaneous users of a shared
resource up to a maximum number. Threads can request access to the resource
(decrementing the semaphore), and can signal that they have finished using
the resource (incrementing the semaphore). A thread that requests access to
a busy resource is put in a waiting state. The semaphore maintains a First
In First Out (FIFO) queue of such waiting threads. When another thread increments
the semaphore, the first thread in this queue is resumed.</p></li>
</ul>
<ul>
<li><p><b>Locks</b> are used to synchronize the data between threads in the
kernel. In SMP, threads are executed in parallel, which means that if locks
are not applied to the code it could result in a race condition. Race conditions
lead to system crashes and data corruptions. For more information about locking,
see <xref href="GUID-16AED228-539F-4BF7-A7FD-9A01FF1A9A84.dita">Locking</xref>.</p></li>
</ul>
<p>Shared memory between threads is provided by the following APIs:<table id="GUID-A35DFE73-AE8C-42A9-A76F-4D47B6BAD6EB">
<tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/>
<thead>
<row>
<entry valign="top"><p>API name</p></entry>
<entry valign="top"><p>Description</p></entry>
</row>
</thead>
<tbody>
<row>
<entry><p><xref href="GUID-29F27759-CC53-36DF-AE92-623F061D6C96.dita"><apiname>TFindThread</apiname></xref></p></entry>
<entry><p>Searches for threads by pattern matching against the names of thread
objects.</p></entry>
</row>
<row>
<entry><p><xref href="GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5.dita"><apiname>RThread</apiname></xref></p></entry>
<entry><p>A handle to a thread. </p></entry>
</row>
<row>
<entry><p><xref href="GUID-C0FEA3A0-7DD3-3B87-A919-CB973BC05766.dita"><apiname>RMutex</apiname></xref></p></entry>
<entry><p>A handle to a mutex.</p></entry>
</row>
<row>
<entry><p><xref href="GUID-A907C7B1-BD90-3E8F-AEA8-5A634BC98D0D.dita"><apiname>TFindMutex</apiname></xref></p></entry>
<entry><p>Finds all global mutexes whose full names match a specified pattern.</p></entry>
</row>
<row>
<entry><p><xref href="GUID-AED27A76-3645-3A04-B80D-10473D9C5A27.dita"><apiname>RSemaphore</apiname></xref></p></entry>
<entry><p>A handle to a semaphore.</p></entry>
</row>
<row>
<entry><p><xref href="GUID-F3ACDC41-31EE-3C32-BE2C-D696B84931CD.dita"><apiname>TFindSemaphore</apiname></xref></p></entry>
<entry><p>Finds all global semaphores whose full names match a specified pattern.</p></entry>
</row>
</tbody>
</tgroup>
</table></p>
</conbody><related-links>
<link href="GUID-547CF71C-6A62-57C0-A9BE-E76B4286C6D6.dita"><linktext>Threads And
Processes Overview</linktext></link>
<link href="GUID-BA89F4DF-E2F6-5E0B-BF20-F8898FC5D5F8.dita"><linktext>Mutexes Overview</linktext>
</link>
<link href="GUID-E865E677-1219-500C-89CF-0A2835B91834.dita"><linktext>Semaphores
Overview</linktext></link>
</related-links></concept>