<?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-000ACB11-EDD0-5160-BC5E-4593F1BAF293" xml:lang="en"><title>Message
Queue Overview</title><shortdesc>This topic describes the message queue overview.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>A message queue is a mechanism for passing data: </p>
<ul>
<li id="GUID-B4740898-D06D-5B19-A3AD-E8FE3B72C397"><p>between threads within
a process </p> </li>
<li id="GUID-F9F8E8FF-02F7-5E11-BC57-61FFE1122DB1"><p>between threads that
run in separate processes. </p> </li>
</ul>
<p>The mechanism provides a way to send data (messages) to an interested party
without needing to know whether anyone is listening nor needing to know the
identity of a recipient. </p>
<p>A message is an object, usually an instance of a class, that is placed
into a queue for delivery to recipients. A queue is normally created to deal
with messages of a given type. This means that a queue is created to deal
with messages of a defined (fixed) length. The size of a queue, i.e. the maximum
number of messages, or slots, it can contain is defined and fixed when the
queue is created. The size of message for which a queue is created, and the
size of the queue is arbitrary, being limited only by system resources. </p>
<p>A single queue can be shared by many readers and writers. Several threads
may be reading from and writing to the same message queue, but only one thread
can access the queue at a time. If multiple clients attempt to read from the
message queue a panic will be raised. </p>
<p>A message queue is represented by a <codeph>DMsgQueue</codeph> kernel side
object, to which the reader and the writer can open a handle, a <xref href="GUID-5195B8D1-851E-3BEE-A72D-1841C0937300.dita"><apiname>RMsgQueue</apiname></xref> object.
A message queue is a reference counted object, being derived from <codeph>CObject</codeph>,
which means that it is not persistent; it is deleted when the last handle
to it is closed. The queue itself is simply a block of memory divided into
slots, managed by the <codeph>DMsgQueue</codeph> object. </p>
<fig id="GUID-BDA4A786-57B2-529D-BDFB-72D2B2B30670">
<image href="GUID-7C061090-83A8-5E0F-B42B-2D722BE054EE_d0e243007_href.png" placement="inline"/>
</fig>
<section id="GUID-1D2EF848-8068-56B9-850B-56AE88E192DE"><title>Handle to a
message queue</title> <p>A message queue is created, opened, written to and
read from through a message queue handle, an <xref href="GUID-5195B8D1-851E-3BEE-A72D-1841C0937300.dita"><apiname>RMsgQueue</apiname></xref> object.
This is a templated class, where the template parameter defines the message
type. </p> <p> <xref href="GUID-5195B8D1-851E-3BEE-A72D-1841C0937300.dita"><apiname>RMsgQueue</apiname></xref> is derived from <xref href="GUID-2DCEE7F5-9EA3-3546-8779-7299318176E2.dita"><apiname>RMsgQueueBase</apiname></xref>,
which together form a thin template class/base class pair. <codeph>RMsgQueueBase</codeph> provides
the implementation, while <codeph>RMsgQueue</codeph> provides type safety.
An <codeph>RMsgQueueBase</codeph> object is a valid message queue handle,
but does not offer the type safety that <codeph>RMsgQueue</codeph> does. </p> <fig id="GUID-B9685695-0E07-5CC1-AFED-0ABF4DC93ACB">
<image href="GUID-2F6EF388-CA87-5AAD-A4C5-37FC3CE15331_d0e243046_href.png" placement="inline"/>
</fig> <p>Message queues are used for one-way, one to one communications only.
The message queue is therefore unicast. If there are multiple readers of the
message queue only one will receive the message. </p> </section>
<section id="GUID-910216A9-EE2D-5C45-8AB3-E1CBEF3B7514"><title>Visibility
of a message queue</title> <p>A message queue can be: </p> <ul>
<li id="GUID-A773AF82-EACC-57DB-9A6F-31F74A9EDF94"><p>named and be visible
to all processes - a global queue </p> </li>
<li id="GUID-9EFB0165-798F-5B5F-8537-199C9C16CE33"><p>local to the current
process, i.e. not visible to any other process - a local queue </p> </li>
</ul> </section>
</conbody></concept>