clSetMemObjectDestructorCallback
cl_int clSetMemObjectDestructorCallback (cl_mem memobj, void (CL_CALLBACK *pfn_notify)(cl_mem memobj, void *user_data), void *user_data)
メモリオブジェクトが削除されそのリソースが解放されるときに呼び出されるユーザコールバック関数を登録します。clSetMemObjectDestructorCallback を呼び出すたびに、指定したユーザコールバック関数が memobj と関連付けられたコールバックスタックに登録されます。登録したユーザコールバック関数は、登録順の逆順に呼び出されます。ユーザコールバック関数が呼び出され、またメモリオブジェクトのリソースの解放とメモリオブジェクトの削除が行われます。これにより、アプリケーション（やライブラリ）は memobj を作成する際に指定しメモリオブジェクトの保存領域としていた host_ptr が指すメモリが、再利用もしくは開放できるようになったときに通知を受け取れるようになります。
パラメータ
- memobj
- 有効なメモリオブジェクトを指定します。
- pfn_notify
- 登録するコールバック関数を指定します。OpenCL実装はこのコールバック関数を非同期的に呼び出せます。コールバック関数がスレッドセーフであることを保証するのは、アプリケーションの責任です。このコールバック関数に対するパラメータは以下のとおりです。
- memobj
- 削除されるメモリオブジェクトです。
- user_data
- ユーザが与えたデータへのポインタです。
- user_data
- pfn_notify が呼び出されるときに user_data 引数として渡されます。NULL を指定することもできます。
注記
（メモリオブジェクトが CL_MEME_USE_HOST_PTR を指定して作成されたものであるとき、）実装がユーザコルバック関数を呼び出したときの host_ptr が指すメモリ領域の内容は未定義です。コールバック関数は一般的に、host_ptr が指すメモリ領域の解放や再利用を行うためにアプリケーションが使用するものです。
高負荷なシステムルーチン―コンテキストやコマンドキューの作成を行うOpenCL APIの呼び出し、以下の一覧にあるブロッキングOpenCL操作―をコールバック内で呼び出したときの振る舞いは未定義です。
- clFinish
- clWaitForEvents
- clEnqueueReadBuffer、clEnqueueReadBufferRect、clEnqueueWriteBuffer、clEnqueueWriteBufferRect のブロッキング呼び出し
- clEnqueueReadImage、clEnqueueWriteImage のブロッキング呼び出し
- clEnqueueMapBuffer、clEnqueueMapImage のブロッキング呼び出し
- clBuildProgram のブロッキング呼び出し
コールバック内で上記の一覧に掲載されているルーチンの完了を待つ必要があるときは、その関数をノンブロッキング方式で使用し完了コールバックを割り当ててください。コールバック（もしくはそれ以外のコード）がコマンドキューにコマンドを挿入するとき、キューがフラッシュされるまでコマンドの実行は始まっていなくてもよいことに注意してください。標準的な使用法では、ブロッキングモードで呼び出すと、暗黙的にキューがフラッシュされますが、コールバック内でのブロッキング呼び出しは認められてないため、コールバックが帰る前に clFlush を呼び出すか、clFlush が後で他のスレッドで呼び出されるようにしてください。
ユーザコールバック関数内では、そのコールバック関数呼び出しの契機となるメモリオブジェクトに対してOpenCL APIの呼び出しを行うべきではなく、そのような操作を行った場合のOpenCL APIの振る舞いは未定義です。
エラー
実行が成功した場合、clSetMemObjectDestructorCallback は CL_SUCCESS を返します。そうでない場合は以下のエラーのうちひとつを返します。
- CL_INVALID_MEM_OBJECT - memobj が有効なメモリオブジェクトでないとき。
- CL_INVALID_VALUE - pfy_notify が NULL のとき。
- CL_OUT_OF_RESOURCES - デバイス上でのリソース確保に失敗したとき。
- CL_OUT_OF_HOST_MEMORY - ホスト上でのリソース確保に失敗したとき。
変更記録
- OpenCL 1.1
- 追加
脚注
