Fungsi MapViewOfFileExNuma (winbase.h)
Memetakan tampilan pemetaan file ke ruang alamat proses panggilan dan menentukan simpul NUMA untuk memori fisik.
Sintaks
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
);
Parameter
[in] hFileMappingObject
Handel ke objek pemetaan file. Fungsi CreateFileMappingNuma dan OpenFileMapping mengembalikan handel ini.
[in] dwDesiredAccess
Jenis akses ke objek pemetaan file, yang menentukan perlindungan halaman halaman. Parameter ini bisa menjadi salah satu nilai berikut, atau kombinasi bitwise OR dari beberapa nilai jika sesuai.
Dengan menggunakan bitwise OR, Anda dapat menggabungkan nilai di atas dengan nilai-nilai ini.
| Nilai | Makna |
|---|---|
|
Tampilan copy-on-write file dipetakan. Objek pemetaan file harus dibuat dengan perlindungan PAGE_READONLY, PAGE_READ_EXECUTE, PAGE_WRITECOPY, PAGE_EXECUTE_WRITECOPY, PAGE_READWRITE, atau PAGE_EXECUTE_READWRITE .
Saat proses menulis ke halaman copy-on-write, sistem menyalin halaman asli ke halaman baru yang bersifat privat untuk proses tersebut. Halaman baru didukung oleh file halaman. Perlindungan halaman baru berubah dari copy-on-write menjadi baca/tulis. Ketika akses copy-on-write ditentukan, sistem dan biaya penerapan proses yang diambil adalah untuk seluruh tampilan karena proses panggilan berpotensi menulis ke setiap halaman dalam tampilan, membuat semua halaman privat. Isi halaman baru tidak pernah ditulis kembali ke file asli dan hilang saat tampilan tidak dipetakan. |
|
Tampilan file yang dapat dieksekusi dipetakan (memori yang dipetakan dapat dijalankan sebagai kode). Objek pemetaan file harus dibuat dengan perlindungan PAGE_EXECUTE_READ, PAGE_EXECUTE_WRITECOPY, atau PAGE_EXECUTE_READWRITE . |
|
Dimulai dengan Windows 10, versi 1703, bendera ini menentukan bahwa tampilan harus dipetakan menggunakan dukungan halaman besar. Ukuran tampilan harus kelipatan ukuran halaman besar yang dilaporkan oleh fungsi GetLargePageMinimum , dan objek pemetaan file harus dibuat menggunakan opsi SEC_LARGE_PAGES . Jika Anda memberikan nilai non-null untuk lpBaseAddress, maka nilainya harus kelipatan GetLargePageMinimum. |
|
Mengatur semua lokasi dalam file yang dipetakan sebagai target yang tidak valid untuk Control Flow Guard (CFG). Bendera ini mirip dengan PAGE_TARGETS_INVALID. Gunakan bendera ini dalam kombinasi dengan akses eksekusi FILE_MAP_EXECUTE kanan. Setiap panggilan tidak langsung ke lokasi di halaman tersebut akan gagal pemeriksaan CFG, dan prosesnya akan dihentikan. Perilaku default untuk halaman yang dapat dieksekusi yang dialokasikan adalah ditandai dengan target panggilan yang valid untuk CFG. |
Untuk objek pemetaan file yang dibuat dengan atribut SEC_IMAGE , parameter dwDesiredAccess tidak berpengaruh, dan harus diatur ke nilai yang valid seperti FILE_MAP_READ.
Untuk informasi selengkapnya tentang akses ke objek pemetaan file, lihat Keamanan Pemetaan File dan Hak Akses.
[in] dwFileOffsetHigh
DWORD urutan tinggi dari offset file di mana tampilan akan dimulai.
[in] dwFileOffsetLow
DWORD berurutan rendah dari offset file di mana tampilan akan dimulai. Kombinasi offset tinggi dan rendah harus menentukan offset dalam pemetaan file. Mereka juga harus cocok dengan granularitas alokasi memori sistem. Artinya, offset harus kelipatan granularitas alokasi. Untuk mendapatkan granularitas alokasi memori sistem, gunakan fungsi GetSystemInfo , yang mengisi anggota struktur SYSTEM_INFO .
[in] dwNumberOfBytesToMap
Jumlah byte pemetaan file untuk dipetakan ke tampilan. Semua byte harus dalam ukuran maksimum yang ditentukan oleh CreateFileMapping. Jika parameter ini adalah 0 (nol), pemetaan diperluas dari offset yang ditentukan ke akhir pemetaan file.
[in, optional] lpBaseAddress
Penunjuk ke alamat memori di ruang alamat proses panggilan tempat pemetaan dimulai. Ini harus berupa kelipatan granularitas alokasi memori sistem, atau fungsi gagal. Untuk menentukan granularitas alokasi memori sistem, gunakan fungsi GetSystemInfo . Jika tidak ada cukup ruang alamat di alamat yang ditentukan, fungsi akan gagal.
Jika parameter lpBaseAddressadalah NULL, sistem operasi memilih alamat pemetaan.
Meskipun dimungkinkan untuk menentukan alamat yang aman sekarang (tidak digunakan oleh sistem operasi), tidak ada jaminan bahwa alamat akan tetap aman dari waktu ke waktu. Oleh karena itu, lebih baik membiarkan sistem operasi memilih alamat. Dalam hal ini, Anda tidak akan menyimpan pointer dalam file yang dipetakan memori; Anda akan menyimpan offset dari dasar pemetaan file sehingga pemetaan dapat digunakan di alamat apa pun.
[in] nndPreferred
Simpul NUMA tempat memori fisik harus berada.
| Nilai | Makna |
|---|---|
|
Tidak ada simpul NUMA yang disukai. Ini sama dengan memanggil fungsi MapViewOfFileEx . |
Mengembalikan nilai
Jika fungsi berhasil, nilai yang dikembalikan adalah alamat awal tampilan yang dipetakan.
Jika fungsi gagal, nilai yang dikembalikan adalah NULL. Untuk mendapatkan informasi kesalahan yang diperluas, panggil fungsi GetLastError .
Keterangan
Memetakan file membuat bagian file yang ditentukan terlihat di ruang alamat proses panggilan.
Untuk file yang lebih besar dari ruang alamat, Anda hanya dapat memetakan sebagian kecil data file pada satu waktu. Ketika tampilan pertama selesai, maka Anda membatalkan peta tampilan dan memetakan tampilan baru.
Untuk mendapatkan ukuran tampilan, gunakan fungsi VirtualQueryEx .
Konten awal halaman dalam objek pemetaan file yang didukung oleh file halaman adalah 0 (nol).
Jika alamat pemetaan yang disarankan disediakan, file dipetakan pada alamat yang ditentukan (dibulatkan ke batas 64-KB terdekat) jika ada cukup ruang alamat di alamat yang ditentukan. Jika ruang alamat tidak cukup, fungsi akan gagal.
Biasanya, alamat yang disarankan digunakan untuk menentukan bahwa file harus dipetakan pada alamat yang sama dalam beberapa proses. Ini mengharuskan wilayah ruang alamat tersedia dalam semua proses yang terlibat. Tidak ada alokasi memori lain yang dapat terjadi di wilayah yang digunakan untuk pemetaan, termasuk penggunaan fungsi VirtualAllocExNuma untuk memesan memori.
Jika parameter lpBaseAddress menentukan offset dasar, fungsi berhasil jika wilayah memori yang ditentukan belum digunakan oleh proses panggilan. Sistem tidak memastikan bahwa wilayah memori yang sama tersedia untuk file yang dipetakan memori dalam proses 32-bit lainnya.
Beberapa tampilan file (atau objek pemetaan file dan file yang dipetakan) berkoheren jika berisi data yang identik pada waktu yang ditentukan. Ini terjadi jika tampilan file berasal dari objek pemetaan file yang sama. Proses dapat menduplikasi handel objek pemetaan file ke proses lain dengan menggunakan fungsi DuplicateHandle , atau proses lain dapat membuka objek pemetaan file berdasarkan nama dengan menggunakan fungsi OpenFileMapping .
Dengan satu pengecualian penting, tampilan file yang berasal dari objek pemetaan file apa pun yang didukung oleh file yang sama koheren atau identik pada waktu tertentu. Koherensi dijamin untuk tampilan dalam proses dan untuk tampilan yang dipetakan oleh proses yang berbeda.
Pengecualian terkait dengan file jarak jauh. Meskipun MapViewOfFileExNuma berfungsi dengan file jarak jauh, MapViewOfFileExNuma tidak membuatnya tetap koheren. Misalnya, jika dua komputer memetakan file sebagai dapat ditulis, dan keduanya mengubah halaman yang sama, setiap komputer hanya melihat tulisannya sendiri ke halaman. Ketika data diperbarui pada disk, data tidak digabungkan.
Tampilan file yang dipetakan tidak dijamin koheren dengan file yang diakses oleh fungsi ReadFile atau WriteFile .
Untuk melindungi dari pengecualian EXCEPTION_IN_PAGE_ERROR , gunakan penanganan pengecualian terstruktur untuk melindungi kode apa pun yang menulis ke atau membaca dari tampilan file yang dipetakan memori selain file halaman. Untuk informasi selengkapnya, lihat Membaca dan Menulis Dari Tampilan File.
Saat memodifikasi file melalui tampilan yang dipetakan, tanda waktu modifikasi terakhir mungkin tidak diperbarui secara otomatis. Jika diperlukan, pemanggil harus menggunakan SetFileTime untuk mengatur tanda waktu.
Untuk memiliki file dengan izin yang dapat dieksekusi, aplikasi harus memanggil fungsi CreateFileMappingNuma dengan PAGE_EXECUTE_READWRITE atau PAGE_EXECUTE_READ lalu memanggil fungsi MapViewOfFileExNuma dengan FILE_MAP_EXECUTE | FILE_MAP_WRITE atau FILE_MAP_EXECUTE | FILE_MAP_READ.
Di Windows Server 2012, fungsi ini didukung oleh teknologi berikut.
| Teknologi | Didukung |
|---|---|
| Protokol Server Message Block (SMB) 3.0 | Ya |
| SMB 3.0 Transparent Failover (TFO) | Ya |
| SMB 3.0 dengan Scale-out File Shares (SO) | Ya |
| Sistem File Volume Bersama Kluster (CsvFS) | Ya |
| Sistem File Tangguh (ReFS) | Ya |
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows Vista [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows Server 2008 [hanya aplikasi desktop] |
| Target Platform | Windows |
| Header | winbase.h (termasuk Windows.h) |
| Pustaka | Kernel32.lib |
| DLL | Kernel32.dll |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk