Функция CreateFileMappingNumaW (memoryapi.h)
Создает или открывает объект сопоставления именованных или неименованных файлов для указанного файла и задает узел NUMA для физической памяти.
Синтаксис
HANDLE CreateFileMappingNumaW(
[in] HANDLE hFile,
[in, optional] LPSECURITY_ATTRIBUTES lpFileMappingAttributes,
[in] DWORD flProtect,
[in] DWORD dwMaximumSizeHigh,
[in] DWORD dwMaximumSizeLow,
[in, optional] LPCWSTR lpName,
[in] DWORD nndPreferred
);
Параметры
[in] hFile
Дескриптор файла, из которого создается объект сопоставления файлов.
Файл должен быть открыт с правами доступа, совместимыми с флагами защиты , указанными параметром flProtect. Это не обязательно, но рекомендуется, чтобы файлы, которые планируется сопоставить для эксклюзивного доступа. Дополнительные сведения см. в права доступа и безопасности файлов.
Если hFile INVALID_HANDLE_VALUE, вызов должен также указать размер объекта сопоставления файлов в dwMaximumSizeHigh и параметры dwMaximumSizeLow dwMaximumSizeLow. В этом сценарии CreateFileMappingNuma создает объект сопоставления файлов указанного размера, который поддерживается системным файлом на страницы вместо файла в файловой системе.
[in, optional] lpFileMappingAttributes
Указатель на структуру SECURITY_ATTRIBUTES, которая определяет, может ли возвращаемый дескриптор наследоваться дочерними процессами. Элемент
SECURITY_ATTRIBUTES структура задает дескриптор безопасности для нового объекта сопоставления файлов.
Если lpFileMappingAttributesNULL, дескриптор не может наследоваться, а объект сопоставления файлов получает дескриптор безопасности по умолчанию. Списки управления доступом (ACL) в дескрипторе безопасности по умолчанию для объекта сопоставления файлов получены из первичного или олицетворения маркера создателя. Дополнительные сведения см. в "Безопасность и доступ к файлам".
[in] flProtect
Указывает защиту страницы объекта сопоставления файлов. Все сопоставленные представления объекта должны быть совместимы с этой защитой.
Этот параметр может быть одним из следующих значений.
Приложение может указать один или несколько следующих атрибутов для объекта сопоставления файлов, объединив их с одним из предыдущих значений защиты страниц.
| Ценность | Значение |
|---|---|
|
Выделяет физическое хранилище в памяти или файл разбиения на страницы для всех страниц.
Это параметр по умолчанию. |
|
Задает файл, указанный как исполняемый файл образа.
Атрибут SEC_IMAGE должен сочетаться со значением защиты страницы, например PAGE_READONLY. Однако это значение защиты страницы не влияет на представления исполняемого файла образа. Защита страниц для представлений исполняемого файла образа определяется самим исполняемым файлом. Никакие другие атрибуты не являются допустимыми с SEC_IMAGE. |
|
Указывает, что файл, который указывает параметр hFile является исполняемым файлом образа, который не будет выполняться, а загруженный файл образа не будет иметь принудительной проверки целостности.
Кроме того, сопоставление представления объекта сопоставления файлов, созданного с помощью атрибута SEC_IMAGE_NO_EXECUTE, не будет вызывать обратные вызовы драйвера, зарегистрированные с помощью API ядра psSetLoadImageNotifyRoutine.
Атрибут SEC_IMAGE_NO_EXECUTE должен сочетаться со значением защиты страницы PAGE_READONLY. Никакие другие атрибуты не являются допустимыми с SEC_IMAGE_NO_EXECUTE. Windows Server 2008 R2, Windows 7, Windows Server 2008 и Windows Vista: Это значение не поддерживается до Windows Server 2012 и Windows 8. |
|
Позволяет использовать большие страницы при сопоставлении изображений или резервной копии из файла страниц, но не при сопоставлении данных для обычных файлов. Не забудьте указать максимальный размер объекта сопоставления файлов в качестве минимального размера большой страницы, |
|
Задает для всех страниц значение noncachable.
Приложения не должны использовать этот флаг, за исключением случаев, когда явно требуется для устройства. Использование заблокированных функций с памятью, сопоставленной с SEC_NOCACHE, может привести к EXCEPTION_ILLEGAL_INSTRUCTION исключению. SEC_NOCACHE требует установки SEC_RESERVE или SEC_COMMIT. |
|
Резервирует все страницы без выделения физического хранилища.
Зарезервированный диапазон страниц не может использоваться другими операциями выделения, пока не будет освобожден диапазон страниц. Зарезервированные страницы можно определить в последующих вызовах функции VirtualAllocExNuma. Этот атрибут действителен только в том случае, если параметр hFileINVALID_HANDLE_VALUE (т. е. объект сопоставления файлов, поддерживаемый системным файлом разбиения по страницам). |
|
Задает все страницы для объединения записей.
Приложения не должны использовать этот атрибут, за исключением случаев, когда явно требуется для устройства. Использование заблокированных функций с памятью, сопоставленной с SEC_WRITECOMBINE, может привести к исключению EXCEPTION_ILLEGAL_INSTRUCTION. SEC_WRITECOMBINE требует установки атрибута SEC_RESERVE или SEC_COMMIT. |
[in] dwMaximumSizeHigh
Высокий порядок DWORD максимального размера объекта сопоставления файлов.
[in] dwMaximumSizeLow
Низкий порядок DWORD максимального размера объекта сопоставления файлов.
Если этот параметр и параметр dwMaximumSizeSizeHigh равны 0 (ноль), максимальный размер объекта сопоставления файлов равен текущему размеру файла, который определяет параметр hFile.
Попытка сопоставить файл с длиной 0 (ноль) завершается ошибкой с кодом ошибки ERROR_FILE_INVALID. Приложения должны тестировать файлы с длиной 0 (ноль) и отклонять эти файлы.
[in, optional] lpName
Имя объекта сопоставления файлов.
Если этот параметр соответствует имени существующего объекта сопоставления файлов, функция запрашивает доступ к объекту с защитой, указанной параметром flProtect.
Если этот параметр null, объект сопоставления файлов создается без имени.
Если параметр lpName соответствует имени существующего события, семафора, мьютекса, таймера ожидания или объекта задания, функция завершается ошибкой, а функция getLastError возвращает ERROR_INVALID_HANDLE. Это происходит, так как эти объекты используют одно и то же пространство имен.
Имя может иметь префикс "Глобальный" или "Локальный", чтобы явно создать объект в глобальном или пространстве имен сеанса. Оставшаяся часть имени может содержать любой символ, кроме символа обратной косой черты (\). Для создания объекта сопоставления файлов в глобальном пространстве имен требуется привилегии SeCreateGlobalPrivilege. Дополнительные сведения см. в разделе пространства имен объектов ядра.
Быстрое переключение пользователей реализуется с помощью сеансов служб терминалов. Первый пользователь для входа использует сеанс 0 (ноль), следующий пользователь для входа использует сеанс 1 (один) и т. д. Имена объектов ядра должны соответствовать рекомендациям, чтобы приложения могли поддерживать несколько пользователей.
[in] nndPreferred
Узел NUMA, в котором должна находиться физическая память.
| Ценность | Значение |
|---|---|
|
Не рекомендуется использовать узел NUMA. Это то же самое, что вызов функции createFileMapping |
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение является дескриптором объекта сопоставления файлов.
Если объект существует перед вызовом функции, функция возвращает дескриптор существующему объекту (с текущим размером, а не указанным размером), а функция GetLastError возвращает ERROR_ALREADY_EXISTS.
Если функция завершается ошибкой, возвращаемое значение равно NULL. Чтобы получить расширенные сведения об ошибке, вызовите функцию getLastError
Замечания
После создания объекта сопоставления файлов размер файла не должен превышать размер объекта сопоставления файлов; Если это так, для общего доступа доступны не все содержимое файла.
Объект сопоставления файлов можно совместно использовать путем дублирования, наследования или по имени. Начальное содержимое страниц в объекте сопоставления файлов, поддерживаемом файлом страницы, равно 0 (ноль).
Если приложение задает размер объекта сопоставления файлов, превышающего размер фактического именованного файла на диске, и если защита страницы разрешает доступ на запись (то есть параметр flProtect указывает PAGE_READWRITE или PAGE_EXECUTE_READWRITE), файл на диске увеличивается, чтобы соответствовать указанному размеру объекта сопоставления файлов. Если файл расширен, содержимое файла между старым концем файла и новым концем файла не гарантируется нулевой. Поведение определяется файловой системой.
Если файл не может быть увеличен, результатом является сбой создания объекта сопоставления файлов, а функция GetLastError возвращает ERROR_DISK_FULL.
Дескриптор, возвращаемый функцией CreateFileMappingNuma, имеет полный доступ к новому объекту сопоставления файлов и может использоваться с любой функцией, требующей дескриптора объекта сопоставления файлов. Объект сопоставления файлов можно совместно использовать с помощью процесса создания, обработки дублирования или по имени. Дополнительные сведения см. в функциях DuplicateHandle и Функции OpenFileMa pping.
Создание объекта сопоставления файлов создает потенциал для сопоставления представления файла, но не сопоставляет представление.
Функция
При одном важном исключении представления файлов, производные от одного объекта сопоставления файлов, являются последовательными или идентичными в определенное время. Если несколько процессов имеют дескриптор одного объекта сопоставления файлов, они видят последовательное представление данных при сопоставлении представления файла.
Исключение связано с удаленными файлами. Хотя функция createFileMappingNuma
Сопоставленный файл и файл, к которому осуществляется доступ с помощью функций ввода-вывода (ReadFile и WriteFile) не обязательно согласованы.
Чтобы полностью закрыть объект сопоставления файлов, приложение должно отменить сопоставление всех сопоставленных представлений объекта сопоставления файлов путем вызова функции UnmapViewOfFile, а затем закрыть дескриптор объекта сопоставления файлов, вызвав функцию CloseHandle.
Эти функции можно вызывать в любом порядке. Вызов функции UnmapViewOfFile необходим, так как сопоставленные представления объекта сопоставления файлов поддерживают внутренние открытые дескрипторы с объектом, а объект сопоставления файлов не закрывается, пока все открытые дескриптора не закрываются.
При изменении файла с помощью сопоставленного представления метка времени последнего изменения может не обновляться автоматически. При необходимости вызывающий объект должен использовать SetFileTime, чтобы задать метку времени.
Для создания объекта сопоставления файлов из сеанса, отличного от нуля сеанса, требуется привилегия SeCreateGlobalPrivilege. Обратите внимание, что эта проверка привилегий ограничена созданием объектов сопоставления файлов и не применяется к открытию существующих. Например, если служба или система создает объект сопоставления файлов, любой процесс, выполняемый в любом сеансе, может получить доступ к объекту сопоставления файлов, если вызывающий объект имеет необходимые права доступа.
Используйте структурированную обработку исключений, чтобы защитить любой код, записываемый в или считывающий данные из сопоставленного с памятью представления. Дополнительные сведения см. в чтения и записи изпредставления файлов.
Чтобы иметь сопоставление с разрешениями исполняемого файла, приложение должно вызвать функцию
В Windows Server 2012 эта функция поддерживается следующими технологиями.
| Технологии | Поддержанный |
|---|---|
| Протокол SMB 3.0 | Да |
| Отработка отказа SMB 3.0 (TFO) | Да |
| SMB 3.0 с масштабируемыми общими папками (SO) | Да |
| Файловая система общего тома кластера (CSVFS) | Да |
| Отказоустойчивая файловая система (ReFS) | Да |
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | Windows Vista [только классические приложения] |
| минимальный поддерживаемый сервер | Windows Server 2008 [только классические приложения] |
| целевая платформа | Виндоус |
| заголовка | memoryapi.h (включая Windows.h, Memoryapi.h) |
| библиотеки |
onecore.lib |
| DLL | Kernel32.dll |
См. также
функций сопоставления файлов
поддержки NUMA