Fungsi CreateMutexExA (synchapi.h)
Membuat atau membuka objek mutex bernama atau tanpa nama dan mengembalikan handel ke objek .
Sintaks
HANDLE CreateMutexExA(
[in, optional] LPSECURITY_ATTRIBUTES lpMutexAttributes,
[in, optional] LPCSTR lpName,
[in] DWORD dwFlags,
[in] DWORD dwDesiredAccess
);
Parameter
[in, optional] lpMutexAttributes
Penunjuk ke struktur SECURITY_ATTRIBUTES . Jika parameter ini NULL, handel mutex tidak dapat diwariskan oleh proses turunan.
Anggota lpSecurityDescriptor dari struktur menentukan deskriptor keamanan untuk mutex baru. Jika lpMutexAttributes adalah NULL, mutex akan mendapatkan deskriptor keamanan default. ACL dalam deskriptor keamanan default untuk mutex berasal dari token utama atau peniruan dari pembuat. Untuk informasi selengkapnya, lihat Keamanan Objek Sinkronisasi dan Hak Akses.
[in, optional] lpName
Nama objek mutex. Nama ini terbatas pada MAX_PATH karakter. Perbandingan nama peka huruf besar/kecil.
Jika lpNameNULL, objek mutex dibuat tanpa nama.
Jika lpName cocok dengan nama peristiwa, semaphore, timer, pekerjaan, atau objek pemetaan file yang ada, fungsi gagal dan fungsi GetLastError mengembalikan ERROR_INVALID_HANDLE. Ini terjadi karena objek ini memiliki namespace yang sama.
Nama dapat memiliki awalan "Global" atau "Lokal" untuk secara eksplisit membuat objek di namespace layanan global atau sesi. Sisa nama dapat berisi karakter apa pun kecuali karakter garis miring terbelakang (\). Untuk informasi selengkapnya, lihat Namespace Objek Kernel. Peralihan pengguna cepat diimplementasikan menggunakan sesi Layanan Terminal. Nama objek kernel harus mengikuti panduan yang diuraikan untuk Layanan Terminal sehingga aplikasi dapat mendukung beberapa pengguna.
Objek dapat dibuat di namespace privat. Untuk informasi selengkapnya, lihat Namespace Objek.
[in] dwFlags
Parameter ini bisa 0 atau nilai berikut.
| Nilai | Makna |
|---|---|
|
Pembuat objek adalah pemilik awal mutex. |
[in] dwDesiredAccess
Masker akses untuk objek mutex. Untuk daftar hak akses, lihat Keamanan Objek Sinkronisasi dan Hak Akses.
Nilai kembali
Jika fungsi berhasil, nilai yang dikembalikan adalah handel ke objek mutex yang baru dibuat.
Jika fungsi gagal, nilai yang dikembalikan adalah NULL. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.
Jika mutex adalah mutex bernama dan objek ada sebelum panggilan fungsi ini, nilai yang dikembalikan adalah handel ke objek yang ada, dan fungsi GetLastError mengembalikan ERROR_ALREADY_EXISTS.
Keterangan
Jika Anda menggunakan mutex bernama untuk membatasi aplikasi Anda ke satu instans, pengguna berbahaya dapat membuat mutex ini sebelum Anda melakukannya dan mencegah aplikasi Anda dimulai. Untuk mencegah situasi ini, buat mutex bernama acak dan simpan nama sehingga hanya dapat diperoleh oleh pengguna yang berwenang. Atau, Anda dapat menggunakan file untuk tujuan ini. Untuk membatasi aplikasi Anda ke satu instans per pengguna, buat file terkunci di direktori profil pengguna.
Setiap utas proses panggilan dapat menentukan handel objek mutex dalam panggilan ke salah satu fungsi tunggu. Fungsi tunggu objek tunggal kembali saat status objek yang ditentukan diberi sinyal. Fungsi tunggu beberapa objek dapat diinstruksikan untuk kembali baik ketika salah satu atau ketika semua objek yang ditentukan diberi sinyal. Saat fungsi tunggu kembali, utas tunggu dirilis untuk melanjutkan eksekusinya.
Status objek mutex disinyalir ketika tidak dimiliki oleh utas apa pun. Alur pembuatan dapat menggunakan parameter dwFlags untuk meminta kepemilikan langsung atas mutex. Jika tidak, utas harus menggunakan salah satu fungsi tunggu untuk meminta kepemilikan. Ketika status mutex disinyalir, satu utas tunggu diberikan kepemilikan, status mutex berubah menjadi tidak bertanda, dan fungsi tunggu kembali. Hanya satu utas yang dapat memiliki mutex pada waktu tertentu. Utas pemilik menggunakan fungsi ReleaseMutex untuk merilis kepemilikannya.
Utas yang memiliki mutex dapat menentukan mutex yang sama dalam panggilan fungsi tunggu berulang tanpa memblokir eksekusinya. Biasanya, Anda tidak akan menunggu berulang kali untuk mutex yang sama, tetapi mekanisme ini mencegah utas dari kebuntuan itu sendiri sambil menunggu muteks yang sudah dimilikinya. Namun, untuk merilis kepemilikannya, utas harus memanggil ReleaseMutex sekali untuk setiap kali mutex memenuhi waktu tunggu.
Dua atau beberapa proses dapat memanggil CreateMutex untuk membuat mutex bernama yang sama. Proses pertama benar-benar membuat mutex, dan proses berikutnya dengan hak akses yang memadai hanya membuka handel ke mutex yang ada. Ini memungkinkan beberapa proses untuk menangani mutex yang sama, sambil menghilangkan tanggung jawab pengguna untuk memastikan bahwa proses pembuatan dimulai terlebih dahulu. Saat menggunakan teknik ini, Anda tidak boleh menggunakan bendera CREATE_MUTEX_INITIAL_OWNER ; jika tidak, mungkin sulit untuk memastikan proses mana yang memiliki kepemilikan awal.
Beberapa proses dapat memiliki handel objek mutex yang sama, memungkinkan penggunaan objek untuk sinkronisasi antarproses. Mekanisme berbagi objek berikut tersedia:
- Proses anak yang dibuat oleh fungsi CreateProcess dapat mewarisi handel ke objek mutex jika parameter lpMutexAttributes dari pewarisan yang diaktifkan CreateMutex . Mekanisme ini berfungsi untuk mutex bernama dan tanpa nama.
- Proses dapat menentukan handel ke objek mutex dalam panggilan ke fungsi DuplicateHandle untuk membuat handel duplikat yang dapat digunakan oleh proses lain. Mekanisme ini berfungsi untuk mutex bernama dan tanpa nama.
- Proses dapat menentukan mutex bernama dalam panggilan ke fungsi [OpenMutex](./nf-synchapi-openmutexw.md) atau CreateMutex untuk mengambil handel ke objek mutex.
Catatan
Header synchapi.h mendefinisikan CreateMutexEx sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows Vista [aplikasi desktop | Aplikasi UWP] |
| Server minimum yang didukung | Windows Server 2008 [aplikasi desktop | Aplikasi UWP] |
| Target Platform | Windows |
| Header | synchapi.h (termasuk Windows.h pada Windows 7, Windows Server 2008 Windows Server 2008 R2) |
| Pustaka | Kernel32.lib |
| DLL | Kernel32.dll |