CreateSemaphore

https://msdn.microsoft.com/ja-jp/library/aa379560.aspx https://msdn.microsoft.com/ja-jp/library/cc428944.aspx https://msdn.microsoft.com/ja-jp/library/cc428944.aspx https://msdn.microsoft.com/ja-jp/library/ms687069.aspx https://msdn.microsoft.com/ja-jp/library/cc429766.aspx https://msdn.microsoft.com/ja-jp/library/cc429605.aspx https://msdn.microsoft.com/ja-jp/library/cc429766.aspx https://msdn.microsoft.com/ja-jp/library/aa379560.aspx

名前付きまたは名前なしのセマフォオブジェクトを作成または開きます。

HANDLE CreateSemaphore(
  LPSECURITY_ATTRIBUTES lpSemaphoreAttributes, // セキュリティ記述子
  LONG lInitialCount,                          // 初期のカウント
  LONG lMaximumCount,                          // 最大カウント
  LPCTSTR lpName                               // オブジェクトの名前
);

パラメータ

lpSemaphoreAttributes
子プロセスが、取得したハンドルを継承できるかどうかを決定する、1 個の 構造体へのポインタを指定します。NULL を指定すると、子プロセスはそのハンドルを継承できません。

Windows NT/2000:SECURITY_ATTRIBUTES 構造体の lpSecurityDescriptor メンバで、新しいセマフォのセキュリティ記述子を設定します。NULL を指定すると、既定のセキュリティ記述子がそのセマフォに割り当てられます。

lInitialCount
セマフォオブジェクトの初期のカウントを指定します。0 以上、lMaximumCount 以下の値を指定します。セマフォは、カウントが 0 より大きい場合はシグナル状態になり、カウントが 0 の場合は非シグナル状態になります。待機関数(WaitForSingleObject 関数など)を使って、そのセマフォを待っていたスレッドを解放すると、カウントが 1 つ減ります。ReleaseSemaphore 関数を使うと、任意の数だけ増やすことができます。
lMaximumCount
セマフォオブジェクトの最大カウントを指定します。0 より大きい値を指定しなければなりません。
lpName
セマフォオブジェクトの名前を保持している、NULL で終わる文字列へのポインタを指定します。名前の最大の長さは、MAX_PATH 文字です。名前を比較する際に、大文字と小文字は区別されます。

lpName パラメータで指定した名前が既存のセマフォオブジェクトの名前と一致している場合、この関数を実行するには、既存のオブジェクトに対する SEMAPHORE_ALL_ACCESS アクセス権が必要です。この場合、lInitialCount パラメータと lMaximumCount パラメータは、オブジェクトを作成したプロセスによって既に設定されているため、無視されます。また、lpSemaphoreAttributes パラメータが NULL ではない場合、子プロセスがハンドルを継承できるかどうかの指定は有効ですが、セキュリティ記述子のメンバは無視されます。

lpName パラメータで NULL を指定すると、名前なしのセマフォオブジェクトが作成されます。

lpName パラメータで指定した名前が、既存のイベント、ミューテックス、待機可能なタイマ、ジョブ、ファイルマッピングオブジェクトのいずれかの名前と一致すると、この関数は失敗し、 関数は ERROR_INVALID_HANDLE を返します。これらのオブジェクトは、同じ名前空間を共有しているからです。

Terminal Services:グローバル名前空間またはセッション名前空間でオブジェクトを明示的に作成するために、「Global\」または「Local\」のプレフィックスを付けることができます。名前の残りの部分は、円記号(\)を除き、任意の文字を記述できます。詳細については、MSDN ライブラリの「」を参照してください。

Windows 2000:Terminal Services が動作していない Windows 2000 システムでは、「Global\」と「Local\」の各プレフィックスは無視されます。名前の残りの部分は、円記号(\)を除き、任意の文字を記述できます。

Windows NT 4.0 以前と Windows 95/98:名前は、円記号(\)を除き、任意の文字を記述できます。

戻り値

関数が成功すると、セマフォオブジェクトのハンドルが返ります。指定したセマフォオブジェクトが既に存在していた場合も、そのオブジェクトのハンドルが返ります。その場合、 関数は、ERROR_ALREADY_EXISTS を返します。

関数が失敗すると、NULL が返ります。拡張エラー情報を取得するには、GetLastError 関数を使います。

解説

CreateSemaphore 関数が返すハンドルには、新しいセマフォオブジェクトへの SEMAPHORE_ALL_ACCESS 権が割り当てられていて、セマフォオブジェクトのハンドルを要求する任意の関数で使うことができます。

呼び出し側プロセスの任意のスレッドは「」(待機関数)を呼び出す際に、セマフォオブジェクトのハンドルを指定できます。単一オブジェクトの待機関数は、指定されたオブジェクトがシグナル状態になると、制御を返します。複数オブジェクトの待機関数に対して、指定されたオブジェクトの 1 つ(またはすべて)がシグナル状態になったときに制御を返すよう指示できます。待機関数が制御を返すと、待機中のスレッドは解放され、実行が継続されます。

セマフォオブジェクトは、カウントが 0 より大きい場合はシグナル状態に、カウントが 0 の場合は非シグナル状態になります。待機関数を使って、セマフォを待っていたスレッドを解放すると、カウントが 1 つ減ります。ReleaseSemaphore 関数を使うと、任意の数だけ増やすことができます。カウントが負になったり、lMaximumCount パラメータで指定した値より大きくなることはありません。

複数のプロセスに同じセマフォオブジェクトのハンドルを割り当てて、プロセス間同期の目的でそのオブジェクトを使うことができます。次のようなオブジェクト共有メカニズムを利用できます。

CreateSemaphore 関数の lpSemaphoreAttributes パラメータで継承を有効にしておくと、CreateProcess 関数が作成した子プロセスは、セマフォオブジェクトのハンドルを継承できます。

•プロセスは、特定のイベントオブジェクトのハンドルを指定して 関数を呼び出すことにより、ハンドルを複製できます。他のプロセスは、そのハンドルを使うことができます。

•プロセスは、OpenSemaphore または CreateSemaphore 関数を呼び出す際に、イベントオブジェクトの名前を指定できます。

ハンドルを閉じるには、CloseHandle 関数を使います。プロセスが終了する際に、システムはそのプロセスが所有していたハンドルを自動的に閉じます。セマフォオブジェクトに対して 1 つまたは複数のハンドルが開いている場合、最後のハンドルが閉じた時点で、そのセマフォオブジェクトは破棄されます。

対応情報

Windows NT/2000:Windows NT 3.1 以降
Windows 95/98:Windows 95 以降
ヘッダー:Winbase.h 内で宣言、Windows.h をインクルード
インポートライブラリ:Kernel32.lib を使用
Unicode:Windows NT/2000 は Unicode 版と ANSI 版を実装

参照

, CreateProcess, , OpenSemaphore, ReleaseSemaphore,

表示: