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