次の方法で共有

QueueUserWorkItem 関数 (threadpoollegacyapiset.h)

  • [アーティクル]

スレッド プール内のワーカー スレッドに作業項目をキューに入 れます。

構文

BOOL QueueUserWorkItem(
  [in]           LPTHREAD_START_ROUTINE Function,
  [in, optional] PVOID                  Context,
  [in]           ULONG                  Flags
);

パラメーター

[in] Function

スレッド プール内のスレッドによって実行される LPTHREAD_START_ROUTINE 型のアプリケーション定義コールバック関数へのポインター。 この値は、スレッドの開始アドレスを表します。 このコールバック関数は 、TerminateThread 関数を呼び出してはなりません。

コールバック関数の戻り値は使用されません。

詳細については、「 ThreadProc」を参照してください。

[in, optional] Context

スレッド関数に渡される 1 つのパラメーター値。

[in] Flags

実行を制御するフラグ。 このパラメーターには、次の 1 つ以上の値を指定できます。

値 意味
WT_EXECUTEDEFAULT
0x00000000
 既定では、コールバック関数は I/O 以外のワーカー スレッドにキューに入れられます。

コールバック関数は、I/O 完了ポートを使用するスレッドにキューに入れられます。つまり、警告可能な待機を実行できません。 したがって、I/O が完了して APC を生成すると、コールバックの完了後にスレッドがアラート可能な待機状態になる保証がないため、APC は無期限に待機する可能性があります。
WT_EXECUTEINIOTHREAD
0x00000001
 このフラグは使用されません。

Windows Server 2003 および Windows XP: コールバック関数は、I/O ワーカー スレッドにキューに入れられます。 このフラグは、警告可能な状態で待機するスレッドで関数を実行する必要がある場合に使用する必要があります。

I/O ワーカー スレッドは、Windows Vista および Windows Server 2008 以降で削除されました。
WT_EXECUTEINPERSISTENTTHREAD
0x00000080
 コールバック関数は、終了しないスレッドにキューに入れられます。 毎回同じスレッドが使用される保証はありません。 このフラグは、短いタスクにのみ使用するか、他のタイマー操作に影響する可能性があります。

スレッドが APC を使用する関数を呼び出す場合は、このフラグを設定する必要があります。 詳細については、「 非同期プロシージャ呼び出し」を参照してください。

現在、ワーカー スレッドは本当に永続的ではありませんが、保留中の I/O 要求がある場合、ワーカー スレッドは終了しません。
WT_EXECUTELONGFUNCTION
0x00000010
 コールバック関数は長い待機を実行できます。 このフラグは、システムが新しいスレッドを作成する必要があるかどうかを判断するのに役立ちます。
WT_TRANSFER_IMPERSONATION
0x00000100
 コールバック関数は、プロセスまたは偽装トークンのいずれであっても、現在のアクセス トークンを使用します。 このフラグを指定しない場合、コールバック関数はプロセス トークンでのみ実行されます。

Windows XP: このフラグは、Windows XP SP2 と Windows Server 2003 まではサポートされません。

戻り値

関数が成功すると、戻り値は 0 以外になります。

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

解説

DLL 内の関数がワーカー スレッドにキューに登録されている場合は、DLL がアンロードされる前に関数の実行が完了していることを確認してください。

既定では、スレッド プールにはプロセスあたり最大 512 個のスレッドがあります。 キューの制限を引き上げるには、WinNT.h で定義 されているWT_SET_MAX_THREADPOOL_THREAD マクロを使用します。

#define WT_SET_MAX_THREADPOOL_THREADS(Flags,Limit) \
    ((Flags)|=(Limit)<<16)

QueueUserWorkItem の呼び出しでこのマクロを使用して、Flags パラメーターを指定します。 マクロ パラメーターは、必要なフラグと新しい制限 (最大 (2<<16)-1 スレッド) です。 ただし、キューのサイズは、カーネル非ページ プールのサイズによって制限されます。 アプリケーションでは、ワーカー スレッドの数を少なくすることで、パフォーマンスを向上させることができます。

この関数を使用するアプリケーションをコンパイルするには、 _WIN32_WINNT を 0x0500 以降として定義します。 詳細については、「 Windows ヘッダーの使用」を参照してください。

要件

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

関連項目

プロセス関数とスレッド関数

スレッド プール

ThreadProc