/****************************************************************************

**

** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (qt-info@nokia.com)

**

** This file is part of the documentation of the Qt Toolkit.

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

** This file contains pre-release code and may not be distributed.

** You may use this file in accordance with the terms and conditions

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** GNU Lesser General Public License Usage

** Alternatively, this file may be used under the terms of the GNU Lesser

** General Public License version 2.1 as published by the Free Software

** Foundation and appearing in the file LICENSE.LGPL included in the

** packaging of this file.  Please review the following information to

** ensure the GNU Lesser General Public License version 2.1 requirements

** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

**

** In addition, as a special exception, Nokia gives you certain additional

** rights.  These rights are described in the Nokia Qt LGPL Exception

** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@nokia.com.

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

/*!

  \example ipc/sharedmemory

  \title Shared Memory Example

  The Shared Memory example shows how to use the QSharedMemory class

  to implement inter-process communication using shared memory. To

  build the example, run make. To run the example, start two instances

  of the executable. The main() function creates an \l {QApplication}

  {application} and an instance of our example's Dialog class. The

  dialog is displayed and then control is passed to the application in

  the standard way.

  \snippet examples/ipc/sharedmemory/main.cpp 0

  Two instances of class Dialog appear.

  \image sharedmemory-example_1.png Screenshot of the Shared Memory example

  Class Dialog inherits QDialog. It encapsulates the user interface

  and an instance of QSharedMemory. It also has two public slots,

  loadFromFile() and loadFromMemory() that correspond to the two

  buttons on the dialog.

  \snippet examples/ipc/sharedmemory/dialog.h 0

  The constructor builds the user interface widgets and connects the

  clicked() signal of each button to the corresponding slot function.

  \snippet examples/ipc/sharedmemory/dialog.cpp 0

  Note that "QSharedMemoryExample" is passed to the \l {QSharedMemory}

  {QSharedMemory()} constructor to be used as the key. This will be

  used by the system as the identifier of the underlying shared memory

  segment.

  Click the \tt {Load Image From File...} button on one of the

  dialogs. The loadFromFile() slot is invoked. First, it tests whether

  a shared memory segment is already attached to the process. If so,

  that segment is detached from the process, so we can be assured of

  starting off the example correctly.

  \snippet examples/ipc/sharedmemory/dialog.cpp 1

  The user is then asked to select an image file using

  QFileDialog::getOpenFileName(). The selected file is loaded into a

  QImage. Using a QImage lets us ensure that the selected file is a

  valid image, and it also allows us to immediately display the image

  in the dialog using setPixmap().

  Next the image is streamed into a QBuffer using a QDataStream. This

  gives us the size, which we then use to \l {QSharedMemory::}

  {create()} our shared memory segment. Creating a shared memory

  segment automatically \l {QSharedMemory::attach()} {attaches} the

  segment to the process. Using a QBuffer here lets us get a pointer

  to the image data, which we then use to do a memcopy() from the

  QBuffer into the shared memory segment.

  \snippet examples/ipc/sharedmemory/dialog.cpp 2

  Note that we \l {QSharedMemory::} {lock()} the shared memory segment

  before we copy into it, and we \l {QSharedMemory::} {unlock()} it

  again immediately after the copy. This ensures we have exclusive

  access to the shared memory segment to do our memcopy(). If some

  other process has the segment lock, then our process will block

  until the lock becomes available.

  Note also that the function does not \l {QSharedMemory::} {detach()}

  from the shared memory segment after the memcopy() and

  unlock(). Recall that when the last process detaches from a shared

  memory segment, the segment is released by the operating

  system. Since this process only one that is attached to the shared

  memory segment at the moment, if loadFromFile() detached from the

  shared memory segment, the segment would be destroyed before we get

  to the next step.

  When the function returns, if the file you selected was qt.png, your

  first dialog looks like this.

  \image sharedmemory-example_2.png Screenshot of the Shared Memory example

  In the second dialog, click the \tt {Display Image From Shared

  Memory} button. The loadFromMemory() slot is invoked. It first \l

  {QSharedMemory::attach()} {attaches} the process to the same shared

  memory segment created by the first process. Then it \l

  {QSharedMemory::lock()} {locks} the segment for exclusive access and

  links a QBuffer to the image data in the shared memory segment. It

  then streams the data into a QImage and \l {QSharedMemory::unlock()}

  {unlocks} the segment.

  \snippet examples/ipc/sharedmemory/dialog.cpp 3

  In this case, the function does \l {QSharedMemory::} {detach()} from

  the segment, because now we are effectively finished using

  it. Finally, the QImage is displayed. At this point, both dialogs

  should be showing the same image. When you close the first dialog,

  the Dialog destructor calls the QSharedMemory destructor, which

  detaches from the shared memory segment. Since this is the last

  process to be detached from the segment, the operating system will

  now release the shared memory.

 */