9.22. イベントオブジェクト

イベントイベントはコマンドの実行順序を整理する場合に使うことができます。

つまり一つのコマンドキューにコマンドが挿入されて、挿入順序で実行する場合は不要となります。

イベントオブジェクトが必要となる場面は、複数のコマンドが並行に実行して、パフォーマンスを向上させたい時です。

挿入したコマンドの実行ステータスはどの時点においても次の一つとなります。

ユーザーイベントを除くイベントオブジェクトの生成は複数の方法があります。例えば

カーネル実行コマンド
clEnqueueNDRangeKernel, clEnqueueTask, clEnqueueNativeKernel
読み込み、書き込み、マップ、複製コマンド
clEnqueue{Read|Write|Map}Buffer , clEnqueueUnmapMemObject , clEnqueue{Read|Write}BufferRect , clEnqueue{Read|Write|Map}Image , clEnqueueCopy{Buffer|Image} , clEnqueueCopyBufferRect , clEnqueueCopyBufferToImage , clEnqueueCopyImageToBuffer
同期点コマンド
clEnqueueMarkerWithWaitList, clEnqueueBarrierWithWaitList

等のコマンドは、コマンドキューにコマンドが挿入された時点でイベントオブジェクトを生成します。

9.22.1. clCreateUserEvent

clCreateUserEvent関数はユーザイベントオブジェクトを生成。ユーザイベントはコマンドがデバイスに実行される前に、アプリケーションがユーザーイベントを終了するまで待機するコマンドを挿入させることを可能とする。

注記

詳しくは「表:clCreateUserEvent」(表B.93「表:clCreateUserEvent」)を参照ください。

clCreateUserEventはユーザーイベントを生成したい場合に使います。ユーザーイベントはコマンドが生成するイベントオブジェクトと同じもので、唯一異なる点は明示的にホスト内で生成したことです。

cl_event org.jocl.CL.clCreateUserEvent( //(1)
    cl_context context, //(2)
    int[] errcode_ret) //(3)

(1)

生成したcl_eventオブジェクトを戻します。

(2)

OpenCLコンテキストを指定

(3)

エラーコードの戻り値を指すポインタ

生成したオブジェクトの実行ステータスは、CL_SUBMITTEDに初期化されます。

9.22.2. clSetUserEventStatus

clSetUserEventStatus関数はユーザイベントオブジェクトの実行状態を設定します。

注記

詳しくは「表:clSetUserEventStatus」(表B.94「表:clSetUserEventStatus」)を参照ください。

int org.jocl.CL.clSetUserEventStatus(
    cl_event event, //(1)
    int execution_status) //(2)

(1)

clCreateUserEventを使って生成したユーザイベントオブジェクトを指定。

(2)

設定される新たな実行状態を指定。CL_COMPLETEまたは、負の整数値でエラーを示すことができる。

重要

ユーザイベントオブジェクトと関連付けたメモリオブジェクトは以下のようにイベントステータスを完了してから解放してください。

evt = clCreateUserEvent(context, null);
clSetUserEventStatus(evt, CL_COMPLETE); clReleaseMemObject(mem);

9.22.3. clWaitForEvents

clWaitForEvents関数を呼び出すと、event_list内のイベントオブジェクトで識別されるコマンドのホストスレッドの完了を待機します。実行ステータスがCL_COMPLETEまたは負の値の場合、コマンドは完了とみなします。event_listで指定したイベントは同期点としても作用します。

注記

詳しくは「表:clWaitForEvents」(表B.95「表:clWaitForEvents」)を参照ください。

int org.jocl.CL.clWaitForEvents(
    int num_events, //(1)
    cl_event[] event_list) //(2)

(1)

待機するイベントの数を指定。

(2)

イベントオブジェクトのリストを指定。完了を待機。

9.22.4. clGetEventInfo

注記

詳しくは「表:clGetEventInfo」(表B.96「表:clGetEventInfo」)と「表:cl_event_info」(表B.97「表:cl_event_info」)を参照ください。

int org.jocl.CL.clGetEventInfo(
    cl_event event, //(1)
    int param_name, //(2)
    long param_value_size, //(3)
    Pointer param_value, //(4)
    long[] param_value_size_ret) //(5)

(1)

情報取得するイベントオブジェクトを指定。

(2)

取得する情報のパラメータの名称を指定。

(3)

取得する結果が戻されるメモリを指すポインタ。NULLの場合は無視。

(4)

param_valueを指すメモリのバイトサイズを指定。サイズは戻り値の型のサイズ以上となる必要がある。

(5)

param_valueに複製されるデータの実際のバイトサイズを戻す。NULLの場合は無視。

9.22.5. cl_event_info

注記

詳しくは「表:clGetEventInfo」(表B.96「表:clGetEventInfo」)と「表:cl_event_info」(表B.97「表:cl_event_info」)を参照ください。

取得できる情報のうちcl_command_typeは特に有用なので頭の隅にでも覚えておくようにするとよいでしょう。eventに関連付けられたコマンドを特定することが可能となります。戻り値は以下のような値があります。

  • CL_COMMAND_NDRANGE_KERNEL
  • CL_COMMAND_TASK
  • CL_COMMAND_NATIVE_KERNEL
  • CL_COMMAND_READ_BUFFER
  • CL_COMMAND_WRITE_BUFFER
  • CL_COMMAND_COPY_BUFFER
  • CL_COMMAND_READ_IMAGE
  • CL_COMMAND_WRITE_IMAGE
  • CL_COMMAND_COPY_IMAGE
  • CL_COMMAND_COPY_BUFFER_TO_IMAGE
  • CL_COMMAND_COPY_IMAGE_TO_BUFFER
  • CL_COMMAND_MAP_BUFFER
  • CL_COMMAND_MAP_IMAGE
  • CL_COMMAND_UNMAP_MEM_OBJECT
  • CL_COMMAND_MARKER
  • CL_COMMAND_ACQUIRE_GL_OBJECTS
  • CL_COMMAND_RELEASE_GL_OBJECTS
  • CL_COMMAND_READ_BUFFER_RECT
  • CL_COMMAND_WRITE_BUFFER_RECT
  • CL_COMMAND_COPY_BUFFER_RECT
  • CL_COMMAND_USER
  • CL_COMMAND_BARRIER
  • CL_COMMAND_MIGRATE_MEM_OBJECTS
  • CL_COMMAND_FILL_BUFFER
  • CL_COMMAND_FILL_IMAGE

Copyright 2018-2019, by Masaki Komatsu