clEnqueueTask
提供: Tommy6
cl_int clEnqueueTask (cl_command_queue command_queue, cl_kernel cl_kernel, cl_uint num_events_in_wait_list, const cl_event *event_wait_list, cl_event *event)
OpenCLデバイス上でカーネルを実行するコマンドを挿入します。カーネルは、ワークアイテムを1つ起用して実行されます。
clEnqueueTask() は、clEnqueueNDRangeKernel() を work_dim = 1, global_work_offset = NULL, global_work_size[0] = 1, local_work_size[0] = 1 で呼び出すのと等価です。
1.1 : OpenCL 1.1で追加
パラメータ
- command_queue
- 有効なコマンドキューを指定します。カーネルは、command_queue と関連付けられたOpenCLデバイス上での実行待ちに追加されます。
- kernel
- 有効なカーネルオブジェクトを指定します。kernel と関連付けられたOpenCLコンテキストと command_queue と関連付けられたOpenCLコンテキストは同じでなければなりません。
- num_events_in_wait_list
- event_wait_list で指定したイベントオブジェクトの数を指定します。
- event_wait_list
- このコマンドが実行される前に完了していなければならないイベントを指定します。event_wait_list が NULL のとき、num_events_in_wait_list は 0 でなければなりません。event_wait_list に指定したイベントは同期点としてふるまいます。event_wait_list 内のイベントと関連付けられたOpenCLコンテキストとcommand_queue と関連付けられたOpenCLコンテキストは同じでなければなりません。
- event
- このカーネル実行を識別するイベントオブジェクトが返されます。イベントオブジェクトは一意であり、後で特定のカーネル実行を識別するのに利用できます。event が NULL のとき、このカーネル実行に関するイベントは作成されず、アプリケーションがカーネル実行待ちを行えなくなります。
エラー
カーネル実行の挿入に成功すると、clEnqueueTask は CL_SUCCESS を返します。そうでない場合は以下のエラーのうちひとつを返します。
- CL_INVALID_PROGRAM_EXECUTABLE - command_queue と関連付けられたデバイス上で実行可能な、正常にビルドされたプログラムが一つもないとき。
- CL_INVALID_COMMAND_QUEUE - command_queue が有効なコマンドキューでないとき。
- CL_INVALID_KERNEL - kernel が有効なカーネルオブジェクトでないとき。
- CL_INVALID_CONTEXT - command_queue と関連付けられたコンテキストと kernel と関連付けられたコンテキストが同じでないとき、あるいは command_queue と関連付けられたコンテキストと event_wait_list 内のイベントと関連付けられたコンテキストが同じでないとき。
- CL_INVALID_KERNEL_ARGS - カーネル引数が指定されていないとき。
- CL_MISALIGNED_SUB_BUFFER_OFFSET - カーネルの引数にサブバッファオブジェクトを指定していて、そのサブバッファオブジェクトを作成する際に指定した offset が、command_queue と関連付けられたデバイスの CL_DEVICE_MEM_BASE_ADDR_ALIGN にアラインされていないとき。
- CL_INVALID_IMAGE_SIZE - カーネルの引数にイメージオブジェクトを指定していて、イメージの次元が command_queue と関連付けられたデバイスでサポートされていないとき。
- CL_OUT_OF_RESOURCES - カーネルを実行するのに必要なリソースが不足しているためにカーネル実行を挿入できないとき。
- CL_MEM_OBJECT_ALLOCATION_FAILURE - kernel の引数に指定されたバッファ/イメージオブジェクトに関連付けられたデータ保存のためのメモリ領域の確保に失敗したとき。
- CL_INVALID_EVENT_WAIT_LIST - event_wait_list が NULL で num_events_in_wait_list が 0 より大きいとき。あるいは event_wait_list が NULL でなく num_events_in_wait_list が 0 のとき。あるいは event_wait_list 内のイベントオブジェクトが有効なものでないとき。
- CL_OUT_OF_RESOURCES - デバイス上でのリソース確保に失敗したとき。
- CL_OUT_OF_HOST_MEMORY - ホスト上でのリソース確保に失敗したとき。
変更記録
- OpenCL 1.1
- エラー CL_MISALIGNED_SUB_BUFFER_OFFSET, CL_INVALID_IMAGE_SIZE の追加
脚注
―――― Version 1.1, The OpenCL Specification
より翻訳