CreateSemaphoreExA 関数 (winbase.h)

  • [アーティクル]

名前付きセマフォ オブジェクトまたは名前のないセマフォ オブジェクトを作成または開き、オブジェクトへのハンドルを返します。

構文

HANDLE CreateSemaphoreExA(
  [in, optional] LPSECURITY_ATTRIBUTES lpSemaphoreAttributes,
  [in]           LONG                  lInitialCount,
  [in]           LONG                  lMaximumCount,
  [in, optional] LPCSTR                lpName,
                 DWORD                 dwFlags,
  [in]           DWORD                 dwDesiredAccess
);

パラメーター

[in, optional] lpSemaphoreAttributes

SECURITY_ATTRIBUTES構造体へのポインター。 このパラメーターが NULL の場合、セマフォ ハンドルは子プロセスによって継承できません。

構造体の lpSecurityDescriptor メンバーは、新しいセマフォのセキュリティ記述子を指定します。 このパラメーターが NULL の場合、セマフォは既定のセキュリティ記述子を取得します。 セマフォの既定のセキュリティ記述子の ACL は、作成者のプライマリ トークンまたは偽装トークンから取得されます。

[in] lInitialCount

セマフォ オブジェクトの初期カウント。 この値は、0 以上で 、lMaximumCount 以下である必要があります。 セマフォの状態は、その数が 0 より大きい場合に通知され、0 の場合は非割り当てになります。 待機関数がセマフォを待機していたスレッドを解放するたびに、カウントは 1 ずつ減少します。 数は ReleaseSemaphore 関数を呼び出すことによって、指定した量だけ増加します。

[in] lMaximumCount

セマフォ オブジェクトの最大カウント。 これは、0 より大きい値である必要があります。

[in, optional] lpName

セマフォ オブジェクトの名前を指定する null で終わる文字列へのポインター。 名前は MAX_PATH 文字に制限されています。 名前の比較では大文字と小文字が区別されます。

lpName が既存の名前付きセマフォ オブジェクトの名前と一致する場合、lInitialCount パラメーターと lMaximumCount パラメーターは作成プロセスによって既に設定されているため、無視されます。 lpSemaphoreAttributes パラメーターが NULL でない場合は、ハンドルを継承できるかどうかを判断します。

lpName が NULL の場合、セマフォ オブジェクトは名前なしで作成されます。

lpName が既存のイベント、ミューテックス、待機可能タイマー、ジョブ、またはファイル マッピング オブジェクトの名前と一致する場合、関数は失敗し、GetLastError 関数はERROR_INVALID_HANDLEを返します。 これは、これらのオブジェクトが同じ名前空間を共有しているために発生します。

名前には、グローバル名前空間またはセッション名前空間にオブジェクトを明示的に作成するための "Global" または "Local" プレフィックスを付けることができます。 名前の残りの部分には、円記号 (\) を除く任意の文字を含めることができます。 詳細については、「 カーネル オブジェクトの名前空間」を参照してください。 ターミナル サービス セッションを使用して、高速ユーザー切り替えが実装されます。 カーネル オブジェクト名は、アプリケーションが複数のユーザーをサポートできるように、ターミナル サービスに関するガイドラインに従う必要があります。

オブジェクトは、プライベート名前空間に作成できます。 詳細については、「 オブジェクトの名前空間」を参照してください。

dwFlags

このパラメーターは予約済みであり、0 である必要があります。

[in] dwDesiredAccess

セマフォ オブジェクトのアクセス マスク。 アクセス権の一覧については、「 同期オブジェクトのセキュリティとアクセス権」を参照してください。

戻り値

関数が成功した場合、戻り値はセマフォ オブジェクトへのハンドルです。 関数呼び出しの前に名前付きセマフォ オブジェクトが存在する場合、関数は既存のオブジェクトへのハンドルを返し、GetLastError はERROR_ALREADY_EXISTSを返します。

関数が失敗した場合は、返される値は NULL です。 詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

セマフォ オブジェクトの状態は、カウントが 0 より大きい場合は通知され、カウントが 0 に等しい場合は非割り当てになります。 lInitialCount パラメーターは、初期カウントを指定します。 カウントを 0 より小さくしたり、 lMaximumCount パラメーターで指定された値より大きくしたりすることはできません。

呼び出し元プロセスのすべてのスレッドは、 待機関数の 1 つの呼び出しでセマフォ オブジェクト ハンドルを指定できます。 単一オブジェクト待機関数は、指定されたオブジェクトの状態が通知されると を返します。 複数オブジェクト待機関数は、いずれかの場合、または指定されたすべてのオブジェクトが通知されたときにを返すように指示できます。 待機関数が戻ると、待機中のスレッドが解放され、実行が続行されます。 スレッドがセマフォ オブジェクトの待機を完了するたびに、セマフォ オブジェクトの数が 1 ずつ減らされます。 スレッドが完了すると、 ReleaseSemaphore 関数が呼び出され、セマフォ オブジェクトのカウントがインクリメントされます。

複数のプロセスに同じセマフォ オブジェクトのハンドルを含めることができるため、プロセス間同期に オブジェクトを使用できます。 次のオブジェクト共有メカニズムを使用できます。

  • CreateSemaphoreEx のlpSemaphoreAttributes パラメーターで継承が有効になっている場合、CreateProcess 関数によって作成された子プロセスは、セマフォ オブジェクトへのハンドルを継承できます。
  • プロセスでは、 DuplicateHandle 関数の呼び出しでセマフォ オブジェクト ハンドルを指定して、別のプロセスで使用できる重複するハンドルを作成できます。
  • プロセスでは、[OpenSemaphore](.) の呼び出しでセマフォ オブジェクトの名前を指定できます。/synchapi/nf-synchapi-signalobjectandwait.md) または CreateSemaphoreEx 関数。
CloseHandle 関数を使用してハンドルを閉じます。 プロセスが終了すると、ハンドルが自動的に閉じられます。 セマフォ オブジェクトは、最後のハンドルが閉じられたときに破棄されます。

要件

要件 値
サポートされている最小のクライアント Windows Vista [デスクトップ アプリのみ | UWP アプリ]
サポートされている最小のサーバー Windows Server 2008 [デスクトップ アプリ | UWP アプリ]
対象プラットフォーム Windows
ヘッダー winbase.h (Windows.h を含む)
Library Kernel32.lib
[DLL] Kernel32.dll

関連項目

CloseHandle

セマフォ オブジェクト

同期関数