Fungsi CreateMutexA (synchapi.h)

Artikel
08/26/2023

Membuat atau membuka objek mutex bernama atau tanpa nama.

Untuk menentukan masker akses untuk objek, gunakan fungsi CreateMutexEx .

Sintaks

HANDLE CreateMutexA(
  [in, optional] LPSECURITY_ATTRIBUTES lpMutexAttributes,
  [in]           BOOL                  bInitialOwner,
  [in, optional] LPCSTR                lpName
);

Parameter

[in, optional] lpMutexAttributes

Penunjuk ke struktur SECURITY_ATTRIBUTES . Jika parameter ini NULL, handel tidak dapat diwariskan oleh proses anak.

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] bInitialOwner

Jika nilai ini TRUE dan pemanggil membuat mutex, utas panggilan mendapatkan kepemilikan awal objek mutex. Jika tidak, utas panggilan tidak mendapatkan kepemilikan mutex. Untuk menentukan apakah pemanggil membuat mutex, lihat bagian Mengembalikan Nilai.

[in, optional] lpName

Nama objek mutex. Nama terbatas pada karakter MAX_PATH . Perbandingan nama peka huruf besar/kecil.

Jika lpName cocok dengan nama objek mutex bernama yang sudah ada, fungsi ini meminta akses MUTEX_ALL_ACCESS ke kanan. Dalam hal ini, parameter bInitialOwner diabaikan karena telah ditetapkan oleh proses pembuatan. Jika parameter lpMutexAttributes bukan NULL, parameter menentukan apakah handel dapat diwariskan, tetapi anggota pendeskripsi keamanannya diabaikan.

Jika lpName adalah NULL, 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. Pengalihan pengguna cepat diimplementasikan menggunakan sesi Layanan Terminal. Nama objek kernel harus mengikuti pedoman yang diuraikan untuk Layanan Terminal sehingga aplikasi dapat mendukung beberapa pengguna.

Objek dapat dibuat di namespace privat. Untuk informasi selengkapnya, lihat Namespace Objek.

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

Handel yang dikembalikan oleh CreateMutex memiliki hak akses MUTEX_ALL_ACCESS ; ini dapat digunakan dalam fungsi apa pun yang memerlukan handel ke objek mutex, asalkan pemanggil telah diberikan akses. Jika mutex dibuat dari layanan atau utas yang meniru pengguna lain, Anda dapat menerapkan pendeskripsi keamanan ke mutex saat membuatnya, atau mengubah deskriptor keamanan default untuk proses pembuatan dengan mengubah DACL defaultnya. Untuk informasi selengkapnya, lihat Keamanan Objek Sinkronisasi dan Hak Akses.

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 disinyalkan. Fungsi tunggu beberapa objek dapat diinstruksikan untuk mengembalikan 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 disinyalkan ketika tidak dimiliki oleh utas apa pun. Utas pembuatan dapat menggunakan bendera bInitialOwner untuk meminta kepemilikan segera atas mutex. Jika tidak, utas harus menggunakan salah satu fungsi tunggu untuk meminta kepemilikan. Ketika status mutex diberi sinyal, satu utas tunggu diberikan kepemilikan, status mutex berubah menjadi nonsignaled, 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 mutex yang sudah dimilikinya. Namun, untuk merilis kepemilikannya, utas harus memanggil ReleaseMutex sekali untuk setiap kali mutex memenuhi waktu tunggu.

Dua proses atau lebih 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 mendapatkan handel dari mutex yang sama, sambil meringankan pengguna dari tanggung jawab untuk memastikan bahwa proses pembuatan dimulai terlebih dahulu. Saat menggunakan teknik ini, Anda harus mengatur bendera bInitialOwner ke FALSE; 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 [OpenMutex](./nf-synchapi-openmutexw.md) atau CreateMutex untuk mengambil handel ke objek mutex.

Gunakan fungsi CloseHandle untuk menutup handel. Sistem menutup handel secara otomatis ketika proses berakhir. Objek mutex dihancurkan ketika handel terakhirnya telah ditutup.

Contoh

Lihat Menggunakan Objek Mutex untuk contoh CreateMutex.

Catatan

Header synchapi.h mendefinisikan CreateMutex 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 XP [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2003 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	synchapi.h (termasuk Windows.h pada Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Pustaka	Kernel32.lib
DLL	Kernel32.dll