Blender V5.3
BLI_mmap.cc
Go to the documentation of this file.
1/* SPDX-FileCopyrightText: 2020 Blender Authors
2 *
3 * SPDX-License-Identifier: GPL-2.0-or-later */
4
8
9#include "BLI_mmap.hh"
10#include "BLI_assert.hh"
11#include "BLI_fileops.hh"
12#include "BLI_mutex.hh"
13#include "BLI_string_utils.hh"
14#include "BLI_vector.hh"
15#include "MEM_guardedalloc.h"
16
17#include <atomic>
18#include <cstring>
19
20#ifndef WIN32
21# include <csignal>
22# include <cstdlib>
23# include <sys/mman.h> /* For `mmap`. */
24# include <unistd.h> /* For `write`. */
25#else
26# include "BLI_winstuff.hh"
27# include <io.h> /* For `_get_osfhandle`. */
28#endif
29
30namespace blender {
31
33 /* The address to which the file was mapped. */
34 char *memory;
35
36 /* The length of the file (and therefore the mapped region). */
37 size_t length;
38
39 /* Platform-specific handle for the mapping. */
40 void *volatile handle;
41
42 /* Flag to indicate IO errors. Needs to be volatile since it's being set from
43 * within the signal handler, which is not part of the normal execution flow. */
44 volatile bool io_error;
45
46 /* Used to break out of infinite loops when an error keeps occurring.
47 * See the comments in #try_handle_error_for_address for details. */
48 size_t id;
49};
50
51/* General mutex used to protect access to the list of open mapped files, ensure the handler is
52 * initialized only once and to prevent multiple threads from trying to remap the same
53 * memory-mapped region in parallel. */
55
56/* When using memory-mapped files, any IO errors will result in an EXCEPTION_IN_PAGE_ERROR on
57 * Windows and a SIGBUS signal on other platforms. Therefore, we need to catch that signal and
58 * stop reading the file in question. To do so, we keep a list of all currently opened
59 * memory-mapped files, and if a error is caught, we check if the failed address is inside one of
60 * the mapped regions. If it is, we set a flag to indicate a failed read and remap the memory in
61 * question to a zero-backed region in order to avoid additional signals. The code that actually
62 * reads the memory area has to check whether the flag was set after it's done reading. If the
63 * error occurred outside of a memory-mapped region or the remapping failed, we call the previous
64 * handler if one was initialized and abort the process otherwise on Linux and on Windows let the
65 * exception crash the program. */
67{
68 static Vector<BLI_mmap_file *> open_mmaps;
69 return open_mmaps;
70}
71
72/* Print a message to the STDERR without using the standard library routines.
73 * If a MMAP error occurs while reading a pointer inside one of the standard library's IO routines,
74 * any global locks it was holding won't be unlocked when entering the handler.
75 * Using the normal printing routines could then cause a deadlock. */
76static void print_error(const char *message);
77
78/* Tries to replace the mapping with zeroes.
79 * Returns true on success. */
80static bool try_map_zeros(BLI_mmap_file *file);
81
82/* Find the file mapping containing the address and call #try_map_zeroes for it.
83 * Returns true when execution can continue. */
84static bool try_handle_error_for_address(const void *address)
85{
86 static thread_local size_t last_handled_file_id = -1;
87
88 std::unique_lock lock(mmap_mutex);
89
90 BLI_mmap_file *file = nullptr;
91 for (BLI_mmap_file *link_file : open_mmaps_vector()) {
92 /* Is the address where the error occurred in this file's mapped range? */
93 if (address >= link_file->memory && address < link_file->memory + link_file->length) {
94 file = link_file;
95 break;
96 }
97 }
98
99 if (file == nullptr) {
100 /* Not our error. */
101 return false;
102 }
103
104 /* Check if we already handled this error. */
105 if (file->io_error) {
106 /* If `file->io_error` is true, either a different thread has
107 * already replaced the mapping after this thread raised the
108 * exception, but before we got the lock, and execution can
109 * continue, or replacing the mapping did not avoid the current
110 * exception. We need to check if continuing execution fails to
111 * avoid an infinite loop in the second case. To detect such a
112 * situation, the last handled mapping's ID is stored per thread and
113 * compared against it to see if continuing execution was already
114 * tried for this mapping in this thread. If that is the case,
115 * forward the exception instead of continuing execution again. As
116 * multiple threads could encounter an exception for the same
117 * mapping at the same time, a boolean stored in `BLI_mmap_file`
118 * would not work for this detection, as the condition we need to
119 * detect is thread dependent. */
120 if (file->id == last_handled_file_id) {
121 /* Some possible causes of the error below are:
122 * - Thread safety issues in the error handling code.
123 * - Faulty remapping without having signaled an error in `try_map_zeros`.
124 * - Invalid usage of an address in the mapped range, such as
125 * unaligned access on some platforms.
126 */
128 "Error: Unexpected exception in mapped file which was already remapped with zeros.");
129 return false;
130 }
131 /* Another thread has already remapped the range, we can continue execution. */
132 last_handled_file_id = file->id;
133 return true;
134 }
135
136 last_handled_file_id = file->id;
137 file->io_error = true;
138
139 if (!try_map_zeros(file)) {
140 print_error("Error: Could not replace mapped file with zeros.");
141 return false;
142 }
143
144 return true;
145}
146
147#ifdef WIN32
148using MapViewOfFile3Fn = PVOID(WINAPI *)(HANDLE FileMapping,
149 HANDLE Process,
150 PVOID BaseAddress,
151 ULONG64 Offset,
152 SIZE_T ViewSize,
153 ULONG AllocationType,
154 ULONG PageProtection,
155 MEM_EXTENDED_PARAMETER *ExtendedParameters,
156 ULONG ParameterCount);
157
158using VirtualAlloc2Fn = PVOID(WINAPI *)(HANDLE Process,
159 PVOID BaseAddress,
160 SIZE_T Size,
161 ULONG AllocationType,
162 ULONG PageProtection,
163 MEM_EXTENDED_PARAMETER *ExtendedParameters,
164 ULONG ParameterCount);
165
166/* Pointers to `MapViewOfFile3` and `VirtualAlloc2`, as they need to be dynamically linked
167 * at run-time because they are only available on Windows 10 (1803) or newer.
168 * If they are not available, error handling is not used. */
169static MapViewOfFile3Fn mmap_MapViewOfFile3 = nullptr;
170
171static VirtualAlloc2Fn mmap_VirtualAlloc2 = nullptr;
172
173static void print_error(const char *message)
174{
175 char buffer[256];
176 size_t length = BLI_string_join(buffer, sizeof(buffer), "BLI_mmap: ", message, "\r\n");
177 HANDLE stderr_handle = GetStdHandle(STD_ERROR_HANDLE);
178 WriteFile(stderr_handle, buffer, length, nullptr, nullptr);
179}
180
181static bool try_map_zeros(BLI_mmap_file *file)
182{
183 if (!UnmapViewOfFileEx(file->memory, MEM_PRESERVE_PLACEHOLDER)) {
184 return false;
185 }
186
187 if (!CloseHandle(file->handle)) {
188 return false;
189 }
190
191 ULARGE_INTEGER length_ularge_int;
192 length_ularge_int.QuadPart = file->length;
193 file->handle = CreateFileMapping(INVALID_HANDLE_VALUE,
194 nullptr,
195 PAGE_READONLY,
196 length_ularge_int.HighPart,
197 length_ularge_int.LowPart,
198 nullptr);
199 if (file->handle == nullptr) {
200 return false;
201 }
202
203 void *memory = mmap_MapViewOfFile3(file->handle,
204 nullptr,
205 file->memory,
206 0,
207 file->length,
208 MEM_REPLACE_PLACEHOLDER,
209 PAGE_READONLY,
210 nullptr,
211 0);
212 if (memory == nullptr) {
213 return false;
214 }
215
216 BLI_assert(memory == file->memory);
217
218 return true;
219}
220
221static LONG page_exception_handler(EXCEPTION_POINTERS *ExceptionInfo) noexcept
222{
223 /* On Windows, if an IO error occurs trying to read from a mapped file, an
224 * EXCEPTION_IN_PAGE_ERROR error will be raised. Also check for
225 * EXCEPTION_ACCESS_VIOLATION, which can be raised when a thread tries to read from the mapping
226 * while it is being replaced by another. */
227 if (ExceptionInfo->ExceptionRecord->ExceptionCode == EXCEPTION_IN_PAGE_ERROR ||
228 ExceptionInfo->ExceptionRecord->ExceptionCode == EXCEPTION_ACCESS_VIOLATION)
229 {
230 if (ExceptionInfo->ExceptionRecord->NumberParameters >= 2) {
231 /* Currently, MMAP'd files are read only, so don't replace the mapping when a write is
232 * attempted. */
233 if (ExceptionInfo->ExceptionRecord->ExceptionInformation[0] == 1) {
234 return EXCEPTION_CONTINUE_SEARCH;
235 }
236 const void *address = reinterpret_cast<const void *>(
237 ExceptionInfo->ExceptionRecord->ExceptionInformation[1]);
238 if (try_handle_error_for_address(address)) {
239 return EXCEPTION_CONTINUE_EXECUTION;
240 }
241 }
242 }
243 return EXCEPTION_CONTINUE_SEARCH;
244}
245
246/* Ensures that the error handler is set up and ready. */
247static bool ensure_mmap_initialized()
248{
249 static std::atomic_bool initialized = false;
250 if (initialized) {
251 return true;
252 }
253
254 std::unique_lock lock(mmap_mutex);
255
256 if (!initialized) {
257 HMODULE kernelbase = ::LoadLibraryA("kernelbase.dll");
258 if (kernelbase) {
259 mmap_MapViewOfFile3 = reinterpret_cast<MapViewOfFile3Fn>(
260 ::GetProcAddress(kernelbase, "MapViewOfFile3"));
261 mmap_VirtualAlloc2 = reinterpret_cast<VirtualAlloc2Fn>(
262 ::GetProcAddress(kernelbase, "VirtualAlloc2"));
263 }
264 if (mmap_MapViewOfFile3 && mmap_VirtualAlloc2) {
265 /* First has to be FALSE to avoid our handler being called before ASAN's handler. */
266 AddVectoredExceptionHandler(FALSE, page_exception_handler);
267 }
268 else {
269 print_error("Could not load necessary functions for MMAP error handling.");
270 }
271 initialized = true;
272 }
273 return true;
274}
275#else /* !WIN32 */
276static void print_error(const char *message)
277{
278 char buffer[256];
279 size_t length = BLI_string_join(buffer, sizeof(buffer), "BLI_mmap: ", message, "\n");
280 if (write(STDERR_FILENO, buffer, length) < 0) {
281 /* If writing to stderr fails, there is nowhere to write an error about that. */
282 }
283}
284
285static bool try_map_zeros(BLI_mmap_file *file)
286{
287 /* Replace the mapped memory with zeroes. */
288 const void *mapped_memory = mmap(
289 file->memory, file->length, PROT_READ, MAP_PRIVATE | MAP_ANONYMOUS | MAP_FIXED, -1, 0);
290 if (mapped_memory == MAP_FAILED) {
291 return false;
292 }
293
294 return true;
295}
296
297static struct sigaction next_handler = {};
298
299static void sigbus_handler(int sig, siginfo_t *siginfo, void *ptr) noexcept
300{
301 /* We only handle SIGBUS here for now. */
302 BLI_assert(sig == SIGBUS);
303
304 if (try_handle_error_for_address(siginfo->si_addr)) {
305 return;
306 }
307
308 /* Fall back to the other handler if there was one.
309 *
310 * No lock is needed here, as #try_handle_error_for_address
311 * unconditionally locks `mmap_mutex`, and as such
312 * #ensure_mmap_initialized must have finished and #next_handler
313 * will be set up. */
314 if (next_handler.sa_sigaction && (next_handler.sa_flags & SA_SIGINFO)) {
315 next_handler.sa_sigaction(sig, siginfo, ptr);
316 }
317 else if (!ELEM(next_handler.sa_handler, nullptr, SIG_DFL, SIG_IGN)) {
318 next_handler.sa_handler(sig);
319 }
320 else {
321 print_error("Unhandled SIGBUS caught");
322 abort();
323 }
324}
325
326/* Ensures that the error handler is set up and ready. */
328{
329 static std::atomic_bool initialized = false;
330 if (initialized) {
331 return true;
332 }
333
334 std::unique_lock lock(mmap_mutex);
335 if (!initialized) {
336 struct sigaction newact = {{nullptr}}, oldact = {{nullptr}};
337
338 newact.sa_sigaction = sigbus_handler;
339 newact.sa_flags = SA_SIGINFO;
340
341 if (sigaction(SIGBUS, &newact, &oldact)) {
342 return false;
343 }
344
345 /* Remember the previous handler to fall back to it if the error
346 * does not belong to any of the mapped files. */
347 next_handler = oldact;
348 initialized = true;
349 }
350
351 return true;
352}
353#endif /* !WIN32 */
354
355/* Adds a file to the list that the error handler checks. */
357{
358 std::unique_lock lock(mmap_mutex);
359 open_mmaps_vector().append(file);
360}
361
362/* Removes a file from the list that the error handler checks. */
364{
365 std::unique_lock lock(mmap_mutex);
366 open_mmaps_vector().remove_first_occurrence_and_reorder(file);
367}
368
370{
371 static std::atomic_size_t id_counter = 0;
372
373 void *memory, *handle = nullptr;
374 /* It's important not to use `BLI_lseek` here because in case we fail to use MMAP and returning
375 * nullptr, the calling function is not closing the file using the file descriptor means next
376 * time the file is read the file-pointer is still pointing to the end. This is not an issue for
377 * blender but it throws off the virtual file-system when blender is running on the
378 * render-network. See PR !155823 for details. */
379 const size_t length = BLI_file_descriptor_size(fd);
380 if (length == size_t(-1)) [[unlikely]] {
381 return nullptr;
382 }
383
384 /* Ensures that the error handler is set up and ready. */
386 return nullptr;
387 }
388
389#ifndef WIN32
390 /* Map the given file to memory. */
391 memory = mmap(nullptr, length, PROT_READ, MAP_PRIVATE, fd, 0);
392 if (memory == MAP_FAILED) {
393 return nullptr;
394 }
395#else /* WIN32 */
396 /* Convert the POSIX-style file descriptor to a Windows handle. */
397 void *file_handle = (void *)_get_osfhandle(fd);
398
399 /* Memory mapping on Windows is a multi-step process - first we create a placeholder
400 * allocation. Then we create a mapping, and after that we create a view into that mapping
401 * on top of the placeholder. In our case, one view that spans the entire file is enough.
402 * NOTE: Changes to protection flags should also be reflected in #try_map_zeros. If write
403 * support is added, the write check in #page_exception_handler should be updated. */
404 if (mmap_MapViewOfFile3 && mmap_VirtualAlloc2) {
405 memory = mmap_VirtualAlloc2(nullptr,
406 nullptr,
407 length,
408 MEM_RESERVE | MEM_RESERVE_PLACEHOLDER,
409 PAGE_NOACCESS,
410 nullptr,
411 0);
412 if (memory == nullptr) {
413 return nullptr;
414 }
415
416 handle = CreateFileMapping(file_handle, nullptr, PAGE_READONLY, 0, 0, nullptr);
417 if (handle == nullptr) {
418 VirtualFree(memory, 0, MEM_RELEASE);
419 return nullptr;
420 }
421
422 if (mmap_MapViewOfFile3(handle,
423 nullptr,
424 memory,
425 0,
426 length,
427 MEM_REPLACE_PLACEHOLDER,
428 PAGE_READONLY,
429 nullptr,
430 0) == nullptr)
431 {
432 VirtualFree(memory, 0, MEM_RELEASE);
433 CloseHandle(handle);
434 return nullptr;
435 }
436 }
437 else {
438 /* Fallback without error handling in case `MapViewOfFile3` or `VirtualAlloc2` is not
439 * available. */
440 handle = CreateFileMapping(file_handle, nullptr, PAGE_READONLY, 0, 0, nullptr);
441 if (handle == nullptr) {
442 return nullptr;
443 }
444
445 memory = MapViewOfFile(handle, FILE_MAP_READ, 0, 0, 0);
446 if (memory == nullptr) {
447 CloseHandle(handle);
448 return nullptr;
449 }
450 }
451#endif /* WIN32 */
452
453 /* Now that the mapping was successful, allocate memory and set up the #BLI_mmap_file. */
455 file->memory = static_cast<char *>(memory);
456 file->handle = handle;
457 file->length = length;
458 file->id = id_counter++;
459
460 /* Register the file with the error handler. */
461 error_handler_add(file);
462
463 return file;
464}
465
466bool BLI_mmap_read(BLI_mmap_file *file, void *dest, size_t offset, size_t length)
467{
468 /* If a previous read has already failed or we try to read past the end,
469 * don't even attempt to read any further. */
470 if (file->io_error || (offset + length > file->length)) {
471 return false;
472 }
473
474 memcpy(dest, file->memory + offset, length);
475
476 return !file->io_error;
477}
478
480{
481 return file->memory;
482}
483
485{
486 return file->length;
487}
488
490{
491 return file->io_error;
492}
493
495{
497#ifndef WIN32
498 munmap(static_cast<void *>(file->memory), file->length);
499#else
500 UnmapViewOfFile(file->memory);
501 CloseHandle(file->handle);
502#endif
503
504 MEM_delete(file);
505}
506
507} // namespace blender
File and directory operations.
#define BLI_string_join(...)
Compatibility-like things for windows.
Read Blender memory allocation and freeing.
volatile int lock
#define ELEM(...)
float length(VecOp< float, D >) RET
BMesh Iterators.
BLI_assert(slot->slot_subtype.map==BMO_OP_SLOT_SUBTYPE_MAP_FLT)
static bool try_map_zeros(BLI_mmap_file *file)
Definition BLI_mmap.cc:285
static bool ensure_mmap_initialized()
Definition BLI_mmap.cc:327
static void sigbus_handler(int sig, siginfo_t *siginfo, void *ptr) noexcept
Definition BLI_mmap.cc:299
size_t BLI_mmap_get_length(const BLI_mmap_file *file) ATTR_WARN_UNUSED_RESULT
Definition BLI_mmap.cc:484
BLI_mmap_file * BLI_mmap_open(int fd) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT
Definition BLI_mmap.cc:369
static Vector< BLI_mmap_file * > & open_mmaps_vector()
Definition BLI_mmap.cc:66
static bool try_handle_error_for_address(const void *address)
Definition BLI_mmap.cc:84
void BLI_mmap_free(BLI_mmap_file *file) ATTR_NONNULL(1)
Definition BLI_mmap.cc:494
static Mutex mmap_mutex
Definition BLI_mmap.cc:54
void * MEM_new_zeroed(size_t len, const char *str) ATTR_WARN_UNUSED_RESULT ATTR_ALLOC_SIZE(1) ATTR_NONNULL(2)
static struct sigaction next_handler
Definition BLI_mmap.cc:297
bool BLI_mmap_any_io_error(const BLI_mmap_file *file) ATTR_WARN_UNUSED_RESULT
Definition BLI_mmap.cc:489
bool BLI_mmap_read(BLI_mmap_file *file, void *dest, size_t offset, size_t length) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1)
Definition BLI_mmap.cc:466
static void print_error(const char *message)
Definition BLI_mmap.cc:276
std::mutex Mutex
Definition BLI_mutex.hh:51
void * BLI_mmap_get_pointer(BLI_mmap_file *file) ATTR_WARN_UNUSED_RESULT
Definition BLI_mmap.cc:479
size_t BLI_file_descriptor_size(int file) ATTR_WARN_UNUSED_RESULT
Definition storage.cc:219
static void error_handler_add(BLI_mmap_file *file)
Definition BLI_mmap.cc:356
static void error_handler_remove(BLI_mmap_file *file)
Definition BLI_mmap.cc:363
volatile bool io_error
Definition BLI_mmap.cc:44
void *volatile handle
Definition BLI_mmap.cc:40