1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept id="GUID-5FBA9BB1-94A2-470C-9932-C4255E3774C0" xml:lang="en"><title>Shared

    13 Memory between Threads</title><shortdesc>This document describes the shared memory between threads and how

    14 to avoid race conditions.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    15 <p>Shared memory is a method of InterProcess Communication (IPC) where a single

    16 chunk of memory is shared between two or more processes. It is used to communicate

    17 between threads within a process or two unrelated processes, allowing both

    18 to share a given region of memory efficiently. In an SMP system, multiple

    19 cores are running threads at the same time and not just virtually as in unicore.

    20 Extra caution is needed to handle memory that shared between multiple threads.</p>

    21 <p>A thread is the unit of execution within a process. Every time a process

    22 is initialized, a primary thread is created. For many applications the primary

    23 thread is the only one that the application requires, however, processes can

    24 create additional threads. In an SMP system, multiple threads can be executing

    25 the same (shared) functions simultaneously. Therefore functions need to deal

    26 with this situation in order to maintain consistency of the system.</p>

    27 <p>Following are the key concepts to synchronize threads:</p>

    28 <ul>

    29 <li><p><b>Mutexes</b> are used to serialize access to a section of re-entrant

    30 code that cannot be executed concurrently by more than one thread. A mutex

    31 object only allows one thread into a controlled section, forcing other threads

    32 which attempt to gain access to that section to wait until the first thread

    33 has exited from that section. A mutex can be used by threads across any number

    34 of processes. If a resource is only shared between the threads within the

    35 same process, it can be more efficient to use a critical section.</p></li>

    36 </ul>

    37 <ul>

    38 <li><p><b>Semaphores</b> restrict the number of simultaneous users of a shared

    39 resource up to a maximum number. Threads can request access to the resource

    40 (decrementing the semaphore), and can signal that they have finished using

    41 the resource (incrementing the semaphore). A thread that requests access to

    42 a busy resource is put in a waiting state. The semaphore maintains a First

    43 In First Out (FIFO) queue of such waiting threads. When another thread increments

    44 the semaphore, the first thread in this queue is resumed.</p></li>

    45 </ul>

    46 <ul>

    47 <li><p><b>Locks</b> are used to synchronize the data between threads in the

    48 kernel. In SMP, threads are executed in parallel, which means that if locks

    49 are not applied to the code it could result in a race condition. Race conditions

    50 lead to system crashes and data corruptions. For more information about locking,

    51 see <xref href="GUID-16AED228-539F-4BF7-A7FD-9A01FF1A9A84.dita">Locking</xref>.</p></li>

    52 </ul>

    53 <p>Shared memory between threads is provided by the following APIs:<table id="GUID-A35DFE73-AE8C-42A9-A76F-4D47B6BAD6EB">

    54 <tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/>

    55 <thead>

    56 <row>

    57 <entry valign="top"><p>API name</p></entry>

    58 <entry valign="top"><p>Description</p></entry>

    59 </row>

    60 </thead>

    61 <tbody>

    62 <row>

    63 <entry><p><xref href="GUID-29F27759-CC53-36DF-AE92-623F061D6C96.dita"><apiname>TFindThread</apiname></xref></p></entry>

    64 <entry><p>Searches for threads by pattern matching against the names of thread

    65 objects.</p></entry>

    66 </row>

    67 <row>

    68 <entry><p><xref href="GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5.dita"><apiname>RThread</apiname></xref></p></entry>

    69 <entry><p>A handle to a thread. </p></entry>

    70 </row>

    71 <row>

    72 <entry><p><xref href="GUID-C0FEA3A0-7DD3-3B87-A919-CB973BC05766.dita"><apiname>RMutex</apiname></xref></p></entry>

    73 <entry><p>A handle to a mutex.</p></entry>

    74 </row>

    75 <row>

    76 <entry><p><xref href="GUID-A907C7B1-BD90-3E8F-AEA8-5A634BC98D0D.dita"><apiname>TFindMutex</apiname></xref></p></entry>

    77 <entry><p>Finds all global mutexes whose full names match a specified pattern.</p></entry>

    78 </row>

    79 <row>

    80 <entry><p><xref href="GUID-AED27A76-3645-3A04-B80D-10473D9C5A27.dita"><apiname>RSemaphore</apiname></xref></p></entry>

    81 <entry><p>A handle to a semaphore.</p></entry>

    82 </row>

    83 <row>

    84 <entry><p><xref href="GUID-F3ACDC41-31EE-3C32-BE2C-D696B84931CD.dita"><apiname>TFindSemaphore</apiname></xref></p></entry>

    85 <entry><p>Finds all global semaphores whose full names match a specified pattern.</p></entry>

    86 </row>

    87 </tbody>

    88 </tgroup>

    89 </table></p>

    90 </conbody><related-links>

    91 <link href="GUID-547CF71C-6A62-57C0-A9BE-E76B4286C6D6.dita"><linktext>Threads And

    92 Processes Overview</linktext></link>

    93 <link href="GUID-BA89F4DF-E2F6-5E0B-BF20-F8898FC5D5F8.dita"><linktext>Mutexes Overview</linktext>

    94 </link>

    95 <link href="GUID-E865E677-1219-500C-89CF-0A2835B91834.dita"><linktext>Semaphores

    96 Overview</linktext></link>

    97 </related-links></concept>