Fungsi CreateSemaphoreA (winbase.h)

Artikel
06/10/2023

Membuat atau membuka objek semaphore bernama atau tidak bernama.

Untuk menentukan masker akses untuk objek, gunakan fungsi CreateSemaphoreEx .

Sintaks

HANDLE CreateSemaphoreA(
  [in, optional] LPSECURITY_ATTRIBUTES lpSemaphoreAttributes,
  [in]           LONG                  lInitialCount,
  [in]           LONG                  lMaximumCount,
  [in, optional] LPCSTR                lpName
);

Parameter

[in, optional] lpSemaphoreAttributes

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

Anggota lpSecurityDescriptor dari struktur menentukan deskriptor keamanan untuk semaphore baru. Jika parameter ini NULL, semaphore mendapatkan deskriptor keamanan default. ACL dalam deskriptor keamanan default untuk semaphore berasal dari token utama atau peniruan dari pembuat.

[in] lInitialCount

Jumlah awal untuk objek semaphore. Nilai ini harus lebih besar dari atau sama dengan nol dan kurang dari atau sama dengan lMaximumCount. Status semaphore disinyalir ketika jumlahnya lebih besar dari nol dan tidak bertanda ketika nol. Jumlah berkurang satu per satu setiap kali fungsi tunggu melepaskan utas yang menunggu semaphore. Jumlah ditingkatkan dengan jumlah tertentu dengan memanggil fungsi ReleaseSemaphore .

[in] lMaximumCount

Jumlah maksimum untuk objek semaphore. Nilai ini harus lebih besar dari nol.

[in, optional] lpName

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

Jika lpName cocok dengan nama objek bernama semaphore yang ada, fungsi ini meminta akses SEMAPHORE_ALL_ACCESS ke kanan. Dalam hal ini, parameter lInitialCount dan lMaximumCount diabaikan karena telah ditetapkan oleh proses pembuatan. Jika parameter lpSemaphoreAttributes bukan NULL, parameter menentukan apakah handel dapat diwariskan, tetapi anggota deskriptor keamanannya diabaikan.

Jika lpNameNULL, objek semaphore dibuat tanpa nama.

Jika lpName cocok dengan nama peristiwa, mutex, 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.

Menampilkan nilai

Jika fungsi berhasil, nilai yang dikembalikan adalah handel ke objek semaphore. Jika objek semaphore bernama ada sebelum panggilan fungsi, fungsi mengembalikan handel ke objek yang ada dan GetLastError mengembalikan ERROR_ALREADY_EXISTS.

Jika fungsi gagal, nilai yang dikembalikan adalah NULL. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

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

Status objek semaphore disinyalir ketika jumlahnya lebih besar dari nol, dan tidak ditandatangani ketika hitungannya sama dengan nol. Parameter lInitialCount menentukan jumlah awal. Jumlahnya tidak boleh kurang dari nol atau lebih besar dari nilai yang ditentukan dalam parameter lMaximumCount .

Setiap utas proses panggilan dapat menentukan handel semaphore-object 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. Setiap kali utas menyelesaikan tunggu objek semaphore, jumlah objek semaphore dikurangi satu. Setelah utas selesai, alur memanggil fungsi ReleaseSemaphore , yang menaikkan jumlah objek semaphore.

Beberapa proses dapat memiliki handel objek semaphore 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 semaphore jika parameter lpSemaphoreAttributes dari pewarisan yang diaktifkan CreateSemaphore.
Proses dapat menentukan handel semaphore-object dalam panggilan ke fungsi DuplicateHandle untuk membuat handel duplikat yang dapat digunakan oleh proses lain.
Proses dapat menentukan nama objek semaphore dalam panggilan ke fungsi [OpenSemaphore](/windows/win32/api/synchapi/nf-synchapi-opensemaphorew) atau CreateSemaphore.

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

Contoh

Untuk contoh yang menggunakan CreateSemaphore, lihat Menggunakan Objek Semaphore.

Persyaratan


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	winbase.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll