Función MapViewOfFileExNuma (winbase.h)

Artículo
03/08/2023

Asigna una vista de una asignación de archivos en el espacio de direcciones de un proceso de llamada y especifica el nodo NUMA para la memoria física.

Sintaxis

LPVOID MapViewOfFileExNuma(
  [in]           HANDLE hFileMappingObject,
  [in]           DWORD  dwDesiredAccess,
  [in]           DWORD  dwFileOffsetHigh,
  [in]           DWORD  dwFileOffsetLow,
  [in]           SIZE_T dwNumberOfBytesToMap,
  [in, optional] LPVOID lpBaseAddress,
  [in]           DWORD  nndPreferred
);

Parámetros

[in] hFileMappingObject

Identificador de un objeto de asignación de archivos. Las funciones CreateFileMappingNuma y OpenFileMapping devuelven este identificador.

[in] dwDesiredAccess

Tipo de acceso a un objeto de asignación de archivos, que determina la protección de páginas de las páginas. Este parámetro puede ser uno de los valores siguientes o una combinación OR bit a bit de varios valores cuando corresponda.

Valor	Significado
FILE_MAP_ALL_ACCESS	Se asigna una vista de lectura y escritura del archivo. El objeto de asignación de archivos debe haberse creado con PAGE_READWRITE o PAGE_EXECUTE_READWRITE protección. Cuando se usa con MapViewOfFileExNuma, FILE_MAP_ALL_ACCESS equivale a FILE_MAP_WRITE.
FILE_MAP_READ	Se asigna una vista de solo lectura del archivo. Un intento de escribir en la vista de archivos produce una infracción de acceso. El objeto de asignación de archivos debe haberse creado con protección de PAGE_READONLY, PAGE_READWRITE, PAGE_EXECUTE_READ o PAGE_EXECUTE_READWRITE .
FILE_MAP_WRITE	Se asigna una vista de lectura y escritura del archivo. El objeto de asignación de archivos debe haberse creado con PAGE_READWRITE o PAGE_EXECUTE_READWRITE protección. Cuando se usa con MapViewOfFileExNuma, `(FILE_MAP_WRITE \| FILE_MAP_READ)` equivale a FILE_MAP_WRITE.

Con OR bit a bit, puede combinar los valores anteriores con estos valores.

Valor	Significado
FILE_MAP_COPY	Se asigna una vista de copia en escritura del archivo. El objeto de asignación de archivos debe haberse creado con PAGE_READONLY, PAGE_READ_EXECUTE, PAGE_WRITECOPY, PAGE_EXECUTE_WRITECOPY, PAGE_READWRITE o protección PAGE_EXECUTE_READWRITE . Cuando un proceso escribe en una página de copia en escritura, el sistema copia la página original en una página nueva que es privada para el proceso. El archivo de paginación respalda la nueva página. La protección de la nueva página cambia de copiar en escritura a lectura y escritura. Cuando se especifica el acceso de copia en escritura, el sistema y el cargo de confirmación de proceso realizado es para toda la vista porque el proceso de llamada puede escribir potencialmente en todas las páginas de la vista, lo que hace que todas las páginas sean privadas. El contenido de la nueva página nunca se vuelve a escribir en el archivo original y se pierde cuando la vista no está asignada.
FILE_MAP_EXECUTE	Se asigna una vista ejecutable del archivo (la memoria asignada se puede ejecutar como código). El objeto de asignación de archivos debe haberse creado con PAGE_EXECUTE_READ, PAGE_EXECUTE_WRITECOPY o protección PAGE_EXECUTE_READWRITE .
FILE_MAP_LARGE_PAGES	A partir de Windows 10, versión 1703, esta marca especifica que la vista debe asignarse con compatibilidad con páginas grandes. El tamaño de la vista debe ser un múltiplo del tamaño de una página grande notificada por la función GetLargePageMinimum y el objeto de asignación de archivos debe haberse creado con la opción SEC_LARGE_PAGES . Si proporciona un valor distinto de null para lpBaseAddress, el valor debe ser un múltiplo de GetLargePageMinimum.
FILE_MAP_TARGETS_INVALID	Establece todas las ubicaciones del archivo asignado como destinos no válidos para control Flow Guard (CFG). Esta marca es similar a PAGE_TARGETS_INVALID. Use esta marca en combinación con el FILE_MAP_EXECUTE de acceso de ejecución. Cualquier llamada indirecta a ubicaciones de esas páginas producirá un error en las comprobaciones de CFG y se finalizará el proceso. El comportamiento predeterminado de las páginas ejecutables asignadas es marcar los destinos de llamada válidos para CFG.

En el caso de los objetos de asignación de archivos creados con el atributo SEC_IMAGE , el parámetro dwDesiredAccess no tiene ningún efecto y debe establecerse en cualquier valor válido, como FILE_MAP_READ.

Para obtener más información sobre el acceso a los objetos de asignación de archivos, vea Derechos de acceso y seguridad de asignación de archivos.

[in] dwFileOffsetHigh

DWORD de orden superior del desplazamiento del archivo donde se va a comenzar la vista.

[in] dwFileOffsetLow

DWORD de orden bajo del desplazamiento del archivo donde se va a comenzar la vista. La combinación de los desplazamientos altos y bajos debe especificar un desplazamiento dentro de la asignación de archivos. También deben coincidir con la granularidad de asignación de memoria del sistema. Es decir, el desplazamiento debe ser un múltiplo de la granularidad de asignación. Para obtener la granularidad de asignación de memoria del sistema, use la función GetSystemInfo , que rellena los miembros de una estructura de SYSTEM_INFO .

[in] dwNumberOfBytesToMap

Número de bytes de una asignación de archivos que se va a asignar a una vista. Todos los bytes deben estar dentro del tamaño máximo especificado por CreateFileMapping. Si este parámetro es 0 (cero), la asignación se extiende desde el desplazamiento especificado hasta el final de la asignación de archivos.

[in, optional] lpBaseAddress

Puntero a la dirección de memoria del espacio de direcciones del proceso de llamada donde comienza la asignación. Debe ser un múltiplo de la granularidad de asignación de memoria del sistema o se produce un error en la función. Para determinar la granularidad de asignación de memoria del sistema, use la función GetSystemInfo . Si no hay suficiente espacio de direcciones en la dirección especificada, se produce un error en la función.

Si el parámetro lpBaseAddress es NULL, el sistema operativo elige la dirección de asignación.

Aunque es posible especificar una dirección que es segura ahora (no utilizada por el sistema operativo), no hay ninguna garantía de que la dirección permanezca segura con el tiempo. Por lo tanto, es mejor permitir que el sistema operativo elija la dirección. En este caso, no almacenaría punteros en el archivo asignado de memoria; almacenaría desplazamientos de la base de la asignación de archivos para que la asignación se pueda usar en cualquier dirección.

[in] nndPreferred

Nodo NUMA donde debe residir la memoria física.

Valor	Significado
NUMA_NO_PREFERRED_NODE 0xffffffff	No se prefiere ningún nodo NUMA. Esto es lo mismo que llamar a la función MapViewOfFileEx .

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es la dirección inicial de la vista asignada.

Si la función no se realiza correctamente, el valor devuelto es NULL. Para obtener información ampliada de los errores, llame a la función GetLastError.

Comentarios

La asignación de un archivo hace que la parte especificada del archivo sea visible en el espacio de direcciones del proceso de llamada.

En el caso de los archivos que son mayores que el espacio de direcciones, solo puede asignar una pequeña parte de los datos del archivo a la vez. Una vez completada la primera vista, desasignación y asignación de una nueva vista.

Para obtener el tamaño de una vista, use la función VirtualQueryEx .

El contenido inicial de las páginas de un objeto de asignación de archivos respaldado por el archivo de página es 0 (cero).

Si se proporciona una dirección de asignación sugerida, el archivo se asigna en la dirección especificada (redondeado hacia abajo hasta el límite de 64 KB más cercano) si hay suficiente espacio de direcciones en la dirección especificada. Si no hay suficiente espacio de direcciones, se produce un error en la función.

Normalmente, la dirección sugerida se usa para especificar que se debe asignar un archivo en la misma dirección en varios procesos. Esto requiere que la región del espacio de direcciones esté disponible en todos los procesos implicados. No se puede realizar ninguna otra asignación de memoria en la región que se usa para la asignación, incluido el uso de la función VirtualAllocExNuma para reservar memoria.

Si el parámetro lpBaseAddress especifica un desplazamiento base, la función se realiza correctamente si la región de memoria especificada aún no está en uso por el proceso de llamada. El sistema no garantiza que la misma región de memoria esté disponible para el archivo asignado de memoria en otros procesos de 32 bits.

Varias vistas de un archivo (o un objeto de asignación de archivos y su archivo asignado) son coherentes si contienen datos idénticos en un momento especificado. Esto ocurre si las vistas de archivo se derivan del mismo objeto de asignación de archivos. Un proceso puede duplicar un identificador de objeto de asignación de archivos en otro proceso mediante la función DuplicateHandle u otro proceso puede abrir un objeto de asignación de archivos por nombre mediante la función OpenFileMapping .

Con una excepción importante, las vistas de archivo derivadas de cualquier objeto de asignación de archivos respaldado por el mismo archivo son coherentes o idénticos en un momento específico. Se garantiza la coherencia para las vistas dentro de un proceso y para las vistas asignadas por procesos diferentes.

La excepción está relacionada con los archivos remotos. Aunque MapViewOfFileExNuma funciona con archivos remotos, no los mantiene coherentes. Por ejemplo, si dos equipos asignan un archivo como grabable y cambian la misma página, cada equipo solo ve sus propias escrituras en la página. Cuando los datos se actualizan en el disco, no se combinan.

No se garantiza que una vista asignada de un archivo sea coherente con un archivo al que accede la función ReadFile o WriteFile .

Para protegerse contra las excepciones de EXCEPTION_IN_PAGE_ERROR , use el control de excepciones estructurados para proteger cualquier código que escriba en o lea desde una vista asignada de memoria de un archivo distinto del archivo de página. Para obtener más información, vea Lectura y escritura desde una vista de archivo.

Al modificar un archivo a través de una vista asignada, es posible que la última marca de tiempo de modificación no se actualice automáticamente. Si es necesario, el autor de la llamada debe usar SetFileTime para establecer la marca de tiempo.

Para tener un archivo con permisos ejecutables, una aplicación debe llamar a la función CreateFileMappingNuma con PAGE_EXECUTE_READWRITE o PAGE_EXECUTE_READ y, a continuación, llamar a la función MapViewOfFileExNuma con FILE_MAP_EXECUTE | FILE_MAP_WRITE o FILE_MAP_EXECUTE FILE_MAP_READ | .

En Windows Server 2012, esta función es compatible con las siguientes tecnologías.

Tecnología	Compatible
Protocolo Bloque de mensajes del servidor (SMB) 3.0	Sí
Conmutación por error transparente (TFO) de SMB 3.0	Sí
SMB 3.0 con recursos compartidos de archivos de escalabilidad horizontal (SO)	Sí
Sistema de archivos de Volumen compartido de clúster (CsvFS)	Sí
Sistema de archivos resistente a errores (ReFS)	Sí

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winbase.h (incluye Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll