Update copyright headers
[qt:qt.git] / doc / src / examples / sharedmemory.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29   \example ipc/sharedmemory
30   \title Shared Memory Example
31
32   \brief The Shared Memory example shows how to use the QSharedMemory class
33   to implement inter-process communication using shared memory.
34   
35   To build the example, run make. To run the example, start two instances
36   of the executable. The main() function creates an \l {QApplication}
37   {application} and an instance of our example's Dialog class. The
38   dialog is displayed and then control is passed to the application in
39   the standard way.
40
41   \snippet examples/ipc/sharedmemory/main.cpp 0
42
43   Two instances of class Dialog appear.
44
45   \image sharedmemory-example_1.png Screenshot of the Shared Memory example
46
47   Class Dialog inherits QDialog. It encapsulates the user interface
48   and an instance of QSharedMemory. It also has two public slots,
49   loadFromFile() and loadFromMemory() that correspond to the two
50   buttons on the dialog.
51
52   \snippet examples/ipc/sharedmemory/dialog.h 0
53
54   The constructor builds the user interface widgets and connects the
55   clicked() signal of each button to the corresponding slot function.
56
57   \snippet examples/ipc/sharedmemory/dialog.cpp 0
58
59   Note that "QSharedMemoryExample" is passed to the \l {QSharedMemory}
60   {QSharedMemory()} constructor to be used as the key. This will be
61   used by the system as the identifier of the underlying shared memory
62   segment.
63
64   Click the \tt {Load Image From File...} button on one of the
65   dialogs. The loadFromFile() slot is invoked. First, it tests whether
66   a shared memory segment is already attached to the process. If so,
67   that segment is detached from the process, so we can be assured of
68   starting off the example correctly.
69
70   \snippet examples/ipc/sharedmemory/dialog.cpp 1
71
72   The user is then asked to select an image file using
73   QFileDialog::getOpenFileName(). The selected file is loaded into a
74   QImage. Using a QImage lets us ensure that the selected file is a
75   valid image, and it also allows us to immediately display the image
76   in the dialog using setPixmap().
77
78   Next the image is streamed into a QBuffer using a QDataStream. This
79   gives us the size, which we then use to \l {QSharedMemory::}
80   {create()} our shared memory segment. Creating a shared memory
81   segment automatically \l {QSharedMemory::attach()} {attaches} the
82   segment to the process. Using a QBuffer here lets us get a pointer
83   to the image data, which we then use to do a memcopy() from the
84   QBuffer into the shared memory segment.
85
86   \snippet examples/ipc/sharedmemory/dialog.cpp 2
87
88   Note that we \l {QSharedMemory::} {lock()} the shared memory segment
89   before we copy into it, and we \l {QSharedMemory::} {unlock()} it
90   again immediately after the copy. This ensures we have exclusive
91   access to the shared memory segment to do our memcopy(). If some
92   other process has the segment lock, then our process will block
93   until the lock becomes available.
94
95   Note also that the function does not \l {QSharedMemory::} {detach()}
96   from the shared memory segment after the memcopy() and
97   unlock(). Recall that when the last process detaches from a shared
98   memory segment, the segment is released by the operating
99   system. Since this process only one that is attached to the shared
100   memory segment at the moment, if loadFromFile() detached from the
101   shared memory segment, the segment would be destroyed before we get
102   to the next step.
103
104   When the function returns, if the file you selected was qt.png, your
105   first dialog looks like this.
106
107   \image sharedmemory-example_2.png Screenshot of the Shared Memory example
108
109   In the second dialog, click the \tt {Display Image From Shared
110   Memory} button. The loadFromMemory() slot is invoked. It first \l
111   {QSharedMemory::attach()} {attaches} the process to the same shared
112   memory segment created by the first process. Then it \l
113   {QSharedMemory::lock()} {locks} the segment for exclusive access and
114   links a QBuffer to the image data in the shared memory segment. It
115   then streams the data into a QImage and \l {QSharedMemory::unlock()}
116   {unlocks} the segment.
117
118   \snippet examples/ipc/sharedmemory/dialog.cpp 3
119
120   In this case, the function does \l {QSharedMemory::} {detach()} from
121   the segment, because now we are effectively finished using
122   it. Finally, the QImage is displayed. At this point, both dialogs
123   should be showing the same image. When you close the first dialog,
124   the Dialog destructor calls the QSharedMemory destructor, which
125   detaches from the shared memory segment. Since this is the last
126   process to be detached from the segment, the operating system will
127   now release the shared memory.
128
129  */