Fungsi CreateMutexExA (synchapi.h)

Membuat atau membuka objek mutex bernama atau tanpa nama dan mengembalikan handel ke objek.

Sintaksis

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.

lpSecurityDescriptor anggota struktur menentukan deskriptor keamanan untuk mutex baru. Jika lpMutexAttributesNULL, muteks mendapatkan deskriptor keamanan default. ACL dalam deskriptor keamanan default untuk mutex berasal dari token utama atau peniruan pembuat. Untuk informasi selengkapnya, lihat Keamanan Objek Sinkronisasi dan Hak Akses.

[in, optional] lpName

Nama objek mutex. Nama ini terbatas pada karakter MAX_PATH. 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 Object Namespaces.

[in] dwFlags

Parameter ini bisa 0 atau nilai berikut.

Nilai Arti
CREATE_MUTEX_INITIAL_OWNER
0x00000001
 Pembuat objek adalah pemilik awal mutex.

[in] dwDesiredAccess

Masker akses untuk objek mutex. Untuk daftar hak akses, lihat Synchronization Object Security and Access Rights.

Mengembalikan nilai

Jika fungsi berhasil, nilai pengembalian adalah handel ke objek mutex yang baru dibuat.

Jika fungsi gagal, nilai yang dikembalikan adalah NULL. Untuk mendapatkan informasi kesalahan yang diperluas, panggil 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.

Komentar

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 ketika status objek yang ditentukan disinyalir. 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 ditandai ketika tidak dimiliki oleh utas apa pun. Utas pembuatan dapat menggunakan parameter dwFlags untuk meminta kepemilikan segera atas mutex. Jika tidak, utas harus menggunakan salah satu fungsi tunggu untuk meminta kepemilikan. Ketika status mutex disinyalir, satu alur 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 muteks yang sudah dimilikinya. Namun, untuk merilis kepemilikannya, utas harus memanggil ReleaseMutex sekali untuk setiap kali mutex memenuhi penantian.

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 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 turunan yang dibuat oleh fungsi CreateProcess dapat mewarisi handel ke objek mutex jika parameter lpMutexAttributes pewarisan CreateMutex diaktifkan. 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.
Gunakan fungsi CloseHandle untuk menutup handel. Sistem menutup handel secara otomatis ketika proses berakhir. Objek mutex dihancurkan ketika handel terakhirnya telah ditutup.

Nota

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

Syarat Nilai
klien minimum yang didukung Windows Vista [aplikasi desktop | Aplikasi UWP]
server minimum yang didukung Windows Server 2008 [aplikasi desktop | Aplikasi UWP]
Platform Target Windows
Header synchapi.h (termasuk Windows.h pada Windows 7, Windows Server 2008 Windows Server 2008 R2)
Pustaka Kernel32.lib
DLL Kernel32.dll

Lihat juga

closeHandle

Objek Mutex

Fungsi Sinkronisasi

  • Last updated on