Line data Source code
1 :
2 : /* Copyright (c) 2009-2017, Stefan Eilemann <eile@equalizergraphics.com>
3 : *
4 : * This library is free software; you can redistribute it and/or modify it under
5 : * the terms of the GNU Lesser General Public License version 2.1 as published
6 : * by the Free Software Foundation.
7 : *
8 : * This library is distributed in the hope that it will be useful, but WITHOUT
9 : * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
10 : * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
11 : * details.
12 : *
13 : * You should have received a copy of the GNU Lesser General Public License
14 : * along with this library; if not, write to the Free Software Foundation, Inc.,
15 : * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
16 : */
17 :
18 : #ifndef LUNCHBOX_MEMORYMAP_H
19 : #define LUNCHBOX_MEMORYMAP_H
20 :
21 : #include <boost/noncopyable.hpp>
22 : #include <iostream>
23 : #include <lunchbox/api.h>
24 : #include <string>
25 :
26 : namespace lunchbox
27 : {
28 : namespace detail
29 : {
30 : class MemoryMap;
31 : }
32 :
33 : /**
34 : * Helper to map a file to a memory address (mmap).
35 : * @deprecated Use boost::iostreams::mapped_file_source
36 : *
37 : * Example: @include tests/memoryMap.cpp
38 : */
39 : class MemoryMap : public boost::noncopyable
40 : {
41 : public:
42 : /** Construct a new memory map. @version 1.0 */
43 : LUNCHBOX_API MemoryMap();
44 :
45 : /**
46 : * Construct and initialize a new, readonly memory map.
47 : *
48 : * @throw std::runtime_error if file can't be mapped.
49 : * @version 1.7.1 */
50 : LUNCHBOX_API explicit MemoryMap(const std::string& filename);
51 :
52 : /**
53 : * Construct and initialize a new, read-write memory map.
54 : *
55 : * @throw std::runtime_error if file can't be created.
56 : * @version 1.9.1
57 : */
58 : LUNCHBOX_API MemoryMap(const std::string& filename, const size_t size);
59 :
60 : /**
61 : * Destruct the memory map.
62 : *
63 : * Unmaps the file, if it is still mapped.
64 : * @sa unmap()
65 : * @version 1.0
66 : */
67 : LUNCHBOX_API ~MemoryMap();
68 :
69 : /**
70 : * Map a file to a memory address.
71 : *
72 : * The file is only mapped read-only. The file is automatically unmapped
73 : * when the memory map is deleted.
74 : *
75 : * @param filename The filename of the file to map.
76 : * @return the pointer to the mapped file, or 0 upon error.
77 : * @version 1.0
78 : */
79 : LUNCHBOX_API const void* map(const std::string& filename);
80 :
81 : /**
82 : * Remap a different file for this memory map.
83 : *
84 : * The file is only mapped read-only. An existing map is unmapped.
85 : *
86 : * @param filename The filename of the file to map.
87 : * @return the pointer to the mapped file, or 0 upon error.
88 : * @version 1.9.1
89 : */
90 : LUNCHBOX_API const void* remap(const std::string& filename);
91 :
92 : /**
93 : * Create a writable file to a memory address.
94 : *
95 : * The file is mapped read-write. An existing file will be overwritten. The
96 : * file is automatically unmapped when the memory map is deleted.
97 : *
98 : * @param filename The filename of the file to map.
99 : * @param size this size of the file.
100 : * @return the pointer to the mapped file, or 0 upon error.
101 : * @version 1.9.1
102 : */
103 : LUNCHBOX_API void* create(const std::string& filename, const size_t size);
104 :
105 : /**
106 : * Recreate a different writable file for this memory map.
107 : *
108 : * The file is only mapped read-write. An existing map is unmapped.
109 : *
110 : * @param filename The filename of the file to map.
111 : * @param size this size of the file.
112 : * @return the pointer to the mapped file, or nullptr upon error.
113 : * @version 1.0
114 : */
115 : LUNCHBOX_API void* recreate(const std::string& filename, size_t size);
116 :
117 : /**
118 : * Resize a writeable memory map.
119 : *
120 : * The mapping address may change. An existing read-only map will result in
121 : * an error. On error, the existing map is unmapped.
122 : *
123 : * @param size the new size.
124 : * @return the new mapping address, or nullptr on error.
125 : * @version 1.16
126 : */
127 : LUNCHBOX_API void* resize(size_t size);
128 :
129 : /** Unmap the file. @version 1.0 */
130 : LUNCHBOX_API void unmap();
131 :
132 : /** @return the pointer to the memory map. @version 1.0 */
133 : LUNCHBOX_API const void* getAddress() const;
134 :
135 : /** @return the pointer to the memory map. @version 1.9.1 */
136 : LUNCHBOX_API void* getAddress();
137 :
138 : /** @return the pointer to the memory map. @version 1.9.1 */
139 : template <class T>
140 0 : const T* getAddress() const
141 : {
142 0 : return static_cast<const T*>(getAddress());
143 : }
144 :
145 : /** @return the pointer to the memory map. @version 1.9.1 */
146 : template <class T>
147 3 : T* getAddress()
148 : {
149 3 : return static_cast<T*>(getAddress());
150 : }
151 :
152 : /** Access the given element in the map. @version 1.16 */
153 : template <class T>
154 : T& get(const size_t i)
155 : {
156 : return getAddress<T>()[i];
157 : }
158 :
159 : /** Access the given element in the map. @version 1.16 */
160 : template <class T>
161 : const T& get(const size_t i) const
162 : {
163 : return getAddress<T>()[i];
164 : }
165 :
166 : /** @return the size of the memory map. @version 1.0 */
167 : LUNCHBOX_API size_t getSize() const;
168 :
169 : private:
170 : detail::MemoryMap* const impl_;
171 : };
172 :
173 : inline std::ostream& operator<<(std::ostream& os, const MemoryMap& m)
174 : {
175 : return os << "MemoryMap at " << m.getAddress() << " size " << m.getSize();
176 : }
177 : }
178 :
179 : #endif // LUNCHBOX_MEMORYMAP_H
|
