<?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-80F2A7AC-6E86-54F2-96F0-4417A2AEA017" xml:lang="en"><title>Handle-numbers</title><shortdesc>This document describes the use of handle-numbers to identify handles.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>A handle is a way in which a thread or process can identify an object that

is owned or managed by another thread or process. Such objects are Kernel

side objects.</p>

<p>A handle uses a number, the handle-number, to identify the associated Kernel

side object. The handle, an instance of a <codeph>RHandleBase</codeph> derived

class, encapsulates the handle-number.</p>

<p>The objects referred to by handles are always instances of <codeph>CObject</codeph> derived

classes, i.e. they are reference counting objects. The handle-number is created

when the object is created (or opened, if the object already exists) and added

to an object index.</p>

<p>Typically, calling <codeph>Open()</codeph> or <codeph>Create()</codeph> or

a similarly named function on an <codeph>RHandleBase</codeph>  <i>derived</i> class

causes the associated object to be created or opened and added to an object

index, owned either by the thread or the process. Adding the object to the

object index creates a handle-number and this is returned to, and encapsulated

by, the handle.</p>

<p>For example, <codeph>RMutex</codeph> is the handle for a mutex; all user

side interaction with a specific mutex is directed through an instance of <codeph>RMutex</codeph>.

The <codeph>RMutex</codeph> object exists on the user side; the corresponding

mutex (a DMutex object) exists on the Kernel side.</p>

<fig id="GUID-86253ED0-C374-52C5-BF3E-463D09A3ECD3">

<image href="GUID-8E907968-E6F8-5792-9B04-664971762FFF_d0e230483_href.png" placement="inline"/>

</fig>

<p>Here, code running on the user side constructs an <codeph>RMutex</codeph> and

calls its <codeph>Create()</codeph> member function. This causes the Kernel

to:</p>

<ul>

<li id="GUID-69E652C5-BC3E-5C2C-95DE-8F0BC5DF6C13"><p>construct the corresponding

Kernel object, a <codeph>DMutex</codeph> </p> </li>

<li id="GUID-CA86B942-A4CA-5E9E-BA36-2E581C01C646"><p>add the <codeph>DMutex</codeph> to

the current thread's object index (a <codeph>CObjectIx</codeph>)</p> </li>

<li id="GUID-6BD33635-074D-59CB-BB7E-1AF6F0290481"><p>return the handle-number

to the RMutex.</p> </li>

</ul>

<codeblock id="GUID-96432516-6FC7-584C-843D-17D0E07956CB" xml:space="preserve">...

RMutex m;

m.Create();

...</codeblock>

<p>See also:</p>

<ul>

<li id="GUID-B218DFCC-054D-53ED-9C36-9947C1BC2895"><p><xref href="GUID-A95CDFDE-285F-5DE2-AADE-29B2B9663757.dita">The

object index</xref> </p> <p><xref href="GUID-8C4EB8E0-78F0-553D-91AE-EC070A47B0EE.dita">The

handle-number and the object index</xref> </p> <p><xref href="GUID-A52E8853-9A8A-5B66-A2B0-F943B32AA5C6.dita">Reference

counting objects</xref> </p> </li>

</ul>