Bagikan melalui

Fungsi CreateMutexA (synchapi.h)

Membuat atau membuka objek mutex bernama atau tanpa nama.

Untuk menentukan masker akses untuk objek, gunakan fungsi CreateMutexEx.

Sintaksis

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 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] 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 penelepon membuat mutex, lihat bagian Mengembalikan Nilai.

[in, optional] lpName

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

Jika lpName cocok dengan nama objek mutex bernama yang ada, fungsi ini meminta hak akses MUTEX_ALL_ACCESS. Dalam hal ini, parameter bInitialOwner diabaikan karena telah ditetapkan oleh proses pembuatan. Jika parameter lpMutexAttributes tidak null, itu menentukan apakah handel dapat diwariskan, tetapi anggota pendeskriptor keamanannya diabaikan.

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.

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

Handel yang dikembalikan oleh CreateMutex memiliki akses MUTEX_ALL_ACCESS dengan benar; 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 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 bendera bInitialOwner 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 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 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 [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.

Nota

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

Syarat Nilai
klien minimum yang didukung Windows XP [aplikasi desktop | Aplikasi UWP]
server minimum yang didukung Windows Server 2003 [aplikasi desktop | Aplikasi UWP]
Platform Target 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

Lihat juga

closeHandle

CreateMutexEx

CreateProcess

DuplicateHandle

Objek Mutex

Nama Objek

OpenMutex

ReleaseMutex

SECURITY_ATTRIBUTES

Fungsi Sinkronisasi

  • Last updated on