1
<?xml version="1.0" encoding="UTF-8"?>
2
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
3
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
7
<keywordset><keyword>clSetMemObjectDestructorCallback</keyword></keywordset>
11
<refentrytitle>clSetMemObjectDestructorCallback</refentrytitle>
14
<year>2007-2011</year>
15
<holder>The Khronos Group Inc.
16
Permission is hereby granted, free of charge, to any person obtaining a
17
copy of this software and/or associated documentation files (the
18
"Materials"), to deal in the Materials without restriction, including
19
without limitation the rights to use, copy, modify, merge, publish,
20
distribute, sublicense, and/or sell copies of the Materials, and to
21
permit persons to whom the Materials are furnished to do so, subject to
22
the condition that this copyright notice and permission notice shall be included
23
in all copies or substantial portions of the Materials.</holder>
26
<manvolnum>3</manvolnum>
29
<!-- ================================ SYNOPSIS -->
31
<refnamediv id="clSetCommandQueueProperty">
32
<refname>clSetMemObjectDestructorCallback</refname>
34
Registers a user callback function with a memory object.
38
<refsynopsisdiv xmlns:xlink="http://www.w3.org/1999/xlink"><title></title>
41
<funcdef><link xlink:href="scalarDataTypes.html">cl_int</link>
42
<function>clSetMemObjectDestructorCallback</function>
44
<paramdef><link xlink:href="abstractDataTypes.html">cl_mem</link><parameter>memobj</parameter></paramdef>
45
<paramdef><link xlink:href="scalarDataTypes.html">void</link> (CL_CALLBACK <parameter>*pfn_notify</parameter>)
46
(<link xlink:href="abstractDataTypes.html">cl_mem</link> <varname>memobj</varname></paramdef>
47
<paramdef><link xlink:href="scalarDataTypes.html">void</link><parameter>*user_data</parameter>)</paramdef>
48
<paramdef><link xlink:href="scalarDataTypes.html">void</link><parameter>*user_data</parameter></paramdef>
53
<!-- ================================ PARAMETERS -->
55
<refsect1 id="parameters"><title>Parameters</title>
58
<term><varname>memobj</varname></term>
60
<para>A valid memory object.</para>
65
<term><varname>pfn_notify</varname></term>
68
The callback function that can be registered by the application. This
69
callback function may be called asynchronously by the OpenCL implementation.
70
It is the application's responsibility to ensure that the callback function
71
is thread-safe. The parameters to this callback function are:
74
<itemizedlist mark="disc">
76
<varname>memobj</varname>: the memory object being deleted.
77
When the user callback is called by the implementation, this memory object is
78
no longer valid. <varname>memobj</varname> is only provided for reference purposes.
82
<varname>user_data</varname>: a pointer to user supplied data.
89
<term><varname>user_data</varname></term>
92
Data which will be passed as the <varname>user_data</varname>
93
argument when <varname>pfn_notify</varname> is called. <varname>user_data</varname> can be NULL.
100
<!-- ================================ NOTES -->
101
<refsect1 id="notes"><title>Notes</title>
104
Each call to <function>clSetMemObjectDestructorCallback</function> registers
105
the specified user callback function on a callback stack associated with
106
<varname>memobj</varname>. The registered user callback functions are called in the
107
reverse order in which they were registered. The user callback functions are called
108
and then the memory object's resources are freed and the memory object is deleted. This
109
provides a mechanism for the application (and libraries) using <varname>memobj</varname>
110
to be notified when the memory referenced by <varname>host_ptr</varname>, specified
111
when the memory object is created and used as the storage bits for the memory object,
112
can be reused or freed.
116
When the user callback function is called by the implementation, the contents of
117
the memory region pointed to by <varname>host_ptr</varname> (if the memory object is
118
created with <constant>CL_MEM_USE_HOST_PTR</constant>) are undefined. The callback
119
function is typically used by the application to either free or reuse the memory
120
region pointed to by <varname>host_ptr</varname>.
124
The behavior of calling expensive system routines, OpenCL API calls to create contexts
125
or command-queues, or blocking OpenCL operations from the following list below,
126
in a callback is undefined.
129
<itemizedlist mark="disc">
131
<citerefentry><refentrytitle>clFinish</refentrytitle></citerefentry>
135
<citerefentry><refentrytitle>clWaitForEvents</refentrytitle></citerefentry>
140
<citerefentry><refentrytitle>clEnqueueReadBuffer</refentrytitle></citerefentry>,
141
<citerefentry><refentrytitle>clEnqueueReadBufferRect</refentrytitle></citerefentry>,
142
<citerefentry><refentrytitle>clEnqueueWriteBuffer</refentrytitle></citerefentry>,
143
<citerefentry><refentrytitle>clEnqueueWriteBufferRect</refentrytitle></citerefentry>
148
<citerefentry><refentrytitle>clEnqueueReadImage</refentrytitle></citerefentry> and
149
<citerefentry><refentrytitle>clEnqueueWriteImage</refentrytitle></citerefentry>
154
<citerefentry><refentrytitle>clEnqueueMapBuffer</refentrytitle></citerefentry> and
155
<citerefentry><refentrytitle>clEnqueueMapImage</refentrytitle></citerefentry>
160
<citerefentry><refentrytitle>clBuildProgram</refentrytitle></citerefentry>,
161
<citerefentry><refentrytitle>clCompileProgram</refentrytitle></citerefentry>, or
162
<citerefentry><refentrytitle>clLinkProgram</refentrytitle></citerefentry>
167
If an application needs to wait for completion of a routine from the above list in a
168
callback, please use the non-blocking form of the function, and assign a completion
169
callback to it to do the remainder of your work. Note that when a callback (or other
170
code) enqueues commands to a command-queue, the commands are not required to begin
171
execution until the queue is flushed. In standard usage, blocking enqueue calls serve
172
this role by implicitly flushing the queue. Since blocking calls are not permitted in
173
callbacks, those callbacks that enqueue commands on a command queue should either
174
call <citerefentry><refentrytitle>clFlush</refentrytitle></citerefentry>
175
on the queue before returning or arrange for
176
<citerefentry><refentrytitle>clFlush</refentrytitle></citerefentry> to be called
177
later on another thread.
181
The user callback function may not call OpenCL APIs with the memory object for which
182
the callback function is invoked and for such cases the behavior of OpenCL APIs is
183
considered to be undefined.
187
<!-- ================================ ERRORS -->
189
<refsect1 id="errors"><title>Errors</title>
191
Returns <errorname>CL_SUCCESS</errorname> if the function is executed
192
successfully. Otherwise, it returns one of the following errors:
195
<itemizedlist mark="disc">
197
<errorname>CL_INVALID_MEM_OBJECT</errorname> if <varname>memobj</varname> is not a valid memory object.
201
<errorname>CL_INVALID_VALUE</errorname> if <varname>pfn_notify</varname> is NULL.
205
<errorname>CL_OUT_OF_RESOURCES</errorname> if there is a failure to allocate resources required by the
206
OpenCL implementation on the device.
210
<errorname>CL_OUT_OF_HOST_MEMORY</errorname> if there is a failure to allocate resources required by the
211
OpenCL implementation on the host.
216
<!-- ================================ EXAMPLE -->
217
<!-- DO NOT DELETE IN CASE AN EXAMPLE IS ADDED IN THE FUTURE -->
219
<refsect2 id="example1">
224
<informaltable frame="none">
225
<tgroup cols="1" align="left" colsep="0" rowsep="0">
226
<colspec colname="col1" colnum="1" />
230
Example goes here - it will be set in "code" type with white space preserved.
239
<!-- ================================ SPECIFICATION -->
240
<!-- Set the "uri" attribute in the <olink /> element to the "named destination" for the PDF page
242
<refsect1 id="specification"><title>Specification</title>
243
<para><imageobject><imagedata fileref="pdficon_small1.gif" format="gif" /></imageobject>
244
<olink uri="clSetMemObjectDestructorCallback">OpenCL Specification</olink>
248
<!-- ================================ ALSO SEE -->
250
<refsect1 id="seealso"><title>Also see</title>
252
<citerefentry><refentrytitle>clCreateCommandQueue</refentrytitle></citerefentry>,
253
<citerefentry><refentrytitle>clGetCommandQueueInfo</refentrytitle></citerefentry>,
254
<citerefentry><refentrytitle>clReleaseCommandQueue</refentrytitle></citerefentry>,
255
<citerefentry><refentrytitle>clRetainCommandQueue</refentrytitle></citerefentry>
259
<!-- ============================== COPYRIGHT -->
260
<!-- Content included from copyright.inc.xsl -->
262
<refsect3 id="Copyright"><title></title>
264
<imagedata fileref="KhronosLogo.jpg" format="jpg" />
added
removed
clSetMemObjectDestructorCallback.xml
