Fungsi CreateIoCompletionPort
Membuat port penyelesaian input/output (I/O) dan mengaitkannya dengan handel file tertentu, atau membuat port penyelesaian I/O yang belum terkait dengan handel file, memungkinkan asosiasi di lain waktu.
Mengaitkan instans handel file yang dibuka dengan port penyelesaian I/O memungkinkan proses untuk menerima pemberitahuan penyelesaian operasi I/O asinkron yang melibatkan handel file tersebut.
Catatan
Istilah handel file seperti yang digunakan di sini mengacu pada abstraksi sistem yang mewakili titik akhir I/O yang tumpang tindih, tidak hanya file pada disk. Setiap objek sistem yang mendukung I/O yang tumpang tindih seperti titik akhir jaringan, soket TCP, pipa bernama, dan slot email dapat digunakan sebagai handel file. Untuk informasi tambahan, lihat bagian Keterangan.
Sintaks
HANDLE WINAPI CreateIoCompletionPort(
_In_ HANDLE FileHandle,
_In_opt_ HANDLE ExistingCompletionPort,
_In_ ULONG_PTR CompletionKey,
_In_ DWORD NumberOfConcurrentThreads
);
Parameter
-
FileHandle [in]
-
Handel file terbuka atau INVALID_HANDLE_VALUE.
Handel harus ke objek yang mendukung I/O yang tumpang tindih.
Jika handel disediakan, handel harus dibuka untuk penyelesaian I/O yang tumpang tindih. Misalnya, Anda harus menentukan bendera FILE_FLAG_OVERLAPPED saat menggunakan fungsi CreateFile untuk mendapatkan handel.
Jika INVALID_HANDLE_VALUE ditentukan, fungsi membuat port penyelesaian I/O tanpa mengaitkannya dengan handel file. Dalam hal ini, parameter ExistingCompletionPort harus NULL dan parameter CompletionKey diabaikan.
-
ExistingCompletionPort [in, opsional]
-
Handel ke port penyelesaian I/O yang ada atau NULL.
Jika parameter ini menentukan port penyelesaian I/O yang ada, fungsi mengaitkannya dengan handel yang ditentukan oleh parameter FileHandle . Fungsi mengembalikan handel port penyelesaian I/O yang ada jika berhasil; tidak membuat port penyelesaian I/O baru.
Jika parameter ini NULL, fungsi membuat port penyelesaian I/O baru dan, jika parameter FileHandle valid, kaitkan dengan port penyelesaian I/O baru. Jika tidak, tidak ada asosiasi handel file yang terjadi. Fungsi mengembalikan handel ke port penyelesaian I/O baru jika berhasil.
-
CompletionKey [in]
-
Kunci penyelesaian yang ditentukan pengguna per handel yang disertakan dalam setiap paket penyelesaian I/O untuk handel file yang ditentukan. Untuk informasi lebih lanjut, lihat bagian Keterangan.
-
NumberOfConcurrentThreads [in]
-
Jumlah maksimum utas yang dapat diizinkan sistem operasi untuk memproses paket penyelesaian I/O secara bersamaan untuk port penyelesaian I/O. Parameter ini diabaikan jika parameter ExistingCompletionPort bukan NULL.
Jika parameter ini nol, sistem memungkinkan alur yang berjalan bersamaan karena ada prosesor dalam sistem.
Menampilkan nilai
Jika fungsi berhasil, nilai yang dikembalikan adalah handel ke port penyelesaian I/O:
Jika parameter ExistingCompletionPort adalah NULL, nilai yang dikembalikan adalah handel baru.
Jika parameter ExistingCompletionPort adalah handel port penyelesaian I/O yang valid, nilai yang dikembalikan adalah handel yang sama.
Jika parameter FileHandle adalah handel yang valid, handel file tersebut sekarang dikaitkan dengan port penyelesaian I/O yang dikembalikan.
Jika fungsi gagal, nilai yang dikembalikan adalah NULL. Untuk mendapatkan informasi kesalahan yang diperluas, panggil fungsi GetLastError .
Keterangan
Sistem I/O dapat diinstruksikan untuk mengirim paket pemberitahuan penyelesaian I/O ke port penyelesaian I/O, di mana mereka diantrekan. Fungsi CreateIoCompletionPort menyediakan fungsionalitas ini.
Port penyelesaian I/O dan handelnya dikaitkan dengan proses yang membuatnya dan tidak dapat dibagi di antara proses. Namun, satu handel dapat dibagi antara utas dalam proses yang sama.
CreateIoCompletionPort dapat digunakan dalam tiga mode berbeda:
- Buat hanya port penyelesaian I/O tanpa mengaitkannya dengan handel file.
- Kaitkan port penyelesaian I/O yang ada dengan handel file.
- Lakukan pembuatan dan asosiasi dalam satu panggilan.
Untuk membuat port penyelesaian I/O tanpa mengaitkannya, atur parameter FileHandle ke INVALID_HANDLE_VALUE, parameter ExistingCompletionPort ke NULL, dan parameter CompletionKey ke nol (yang diabaikan dalam kasus ini). Atur parameter NumberOfConcurrentThreads ke nilai konkurensi yang diinginkan untuk port penyelesaian I/O baru, atau nol untuk default (jumlah prosesor dalam sistem).
Handel yang diteruskan dalam parameter FileHandle dapat menjadi handel apa pun yang mendukung I/O yang tumpang tindih. Paling umum, ini adalah handel yang dibuka oleh fungsi CreateFile menggunakan bendera FILE_FLAG_OVERLAPPED (misalnya, file, slot email, dan pipa). Objek yang dibuat oleh fungsi lain seperti soket juga dapat dikaitkan dengan port penyelesaian I/O. Untuk contoh menggunakan soket, lihat AcceptEx. Handel hanya dapat dikaitkan dengan satu port penyelesaian I/O, dan setelah asosiasi dibuat, handel tetap terkait dengan port penyelesaian I/O tersebut hingga ditutup.
Untuk informasi selengkapnya tentang teori, penggunaan, dan fungsi terkait penyelesaian I/O, lihat Port Penyelesaian I/O.
Beberapa handel file dapat dikaitkan dengan satu port penyelesaian I/O dengan memanggil CreateIoCompletionPort beberapa kali dengan handel port penyelesaian I/O yang sama dalam parameter ExistingCompletionPort dan handel file yang berbeda dalam parameter FileHandle setiap kali.
Gunakan parameter CompletionKey untuk membantu aplikasi Anda melacak operasi I/O mana yang telah selesai. Nilai ini tidak digunakan oleh CreateIoCompletionPort untuk kontrol fungsional; sebaliknya, itu dilampirkan ke handel file yang ditentukan dalam parameter FileHandle pada saat asosiasi dengan port penyelesaian I/O. Kunci penyelesaian ini harus unik untuk setiap handel file, dan menyertai handel file selama proses antrean penyelesaian internal. Ini dikembalikan dalam panggilan fungsi GetQueuedCompletionStatus saat paket penyelesaian tiba. Parameter CompletionKey juga digunakan oleh fungsi PostQueuedCompletionStatus untuk mengantre paket penyelesaian tujuan khusus Anda sendiri.
Setelah instans handel terbuka dikaitkan dengan port penyelesaian I/O, itu tidak dapat digunakan dalam fungsi ReadFileEx atau WriteFileEx karena fungsi ini memiliki mekanisme I/O asinkronnya sendiri.
Sebaiknya jangan berbagi handel file yang terkait dengan port penyelesaian I/O dengan menggunakan pewarisan handel atau panggilan ke fungsi DuplicateHandle . Operasi yang dilakukan dengan handel duplikat tersebut menghasilkan pemberitahuan penyelesaian. Pertimbangan yang cermat disarankan.
Handel port penyelesaian I/O dan setiap handel file yang terkait dengan port penyelesaian I/O tertentu dikenal sebagai referensi ke port penyelesaian I/O. Port penyelesaian I/O dirilis ketika tidak ada lagi referensi untuk itu. Oleh karena itu, semua handel ini harus ditutup dengan benar untuk merilis port penyelesaian I/O dan sumber daya sistem terkait. Setelah kondisi ini terpenuhi, tutup handel port penyelesaian I/O dengan memanggil fungsi CloseHandle .
Di Windows 8 dan 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 XP [aplikasi desktop | Aplikasi UWP] |
| Server minimum yang didukung |
Windows Server 2003 [aplikasi desktop | Aplikasi UWP] |
| Header |
|
| Pustaka |
|
| DLL |
|