Enqueues a command to indicate which device a set of memory objects should be associated with.
cl_int clEnqueueMigrateMemObjects(cl_command_queue command_queue, cl_uint num_mem_objects, const cl_mem *mem_objects, cl_mem_migration_flags flags, cl_uint num_events_in_wait_list, const cl_event *event_wait_list, cl_event *event)
A valid host command-queue. The specified set of memory objects in
mem_objectswill be migrated to the OpenCL device associated with
command_queueor to the host if the
CL_MIGRATE_MEM_OBJECT_HOSThas been specified.
The number of memory objects specified in
A pointer to a list of memory objects.
A bit-field that is used to specify migration options. The table below describes the possible values for flags.
cl_mem_migration flags Description
This flag indicates that the specified set of memory objects are to be migrated to the host, regardless of the target command-queue.
This flag indicates that the contents of the set of memory objects are undefined after migration. The specified set of memory objects are migrated to the device associated with
command_queuewithout incurring the overhead of migrating their contents.
Specify events that need to complete before this particular command can be executed. If
event_wait_listis NULL, then this particular command does not wait on any event to complete. If
num_events_in_wait_listmust be 0. If
event_wait_listis not NULL, the list of events pointed to by
event_wait_listmust be valid and
num_events_in_wait_listmust be greater than 0. The events specified in
event_wait_listact as synchronization points. The context associated with events in
command_queuemust be the same. The memory associated with
event_wait_listcan be reused or freed after the function returns.
Returns an event object that identifies this particular command and can be used to query or queue a wait for this particular command to complete.
eventcan be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete. If the
eventarguments are not NULL, the
eventargument should not refer to an element of the
This section describes a mechanism for assigning which device an OpenCL memory object resides. A user may wish to have more explicit control over the location of their memory objects on creation. This could be used to:
Ensure that an object is allocated on a specific device prior to usage.
Preemptively migrate an object from one device to another.
Typically, memory objects are implicitly migrated to a device for which enqueued commands, using the memory object, are targeted.
clEnqueueMigrateMemObjects allows this migration to be explicitly performed ahead of the dependent commands.
This allows a user to preemptively change the association of a memory object, through regular command queue scheduling, in order to prepare for another upcoming command.
This also permits an application to overlap the placement of memory objects with other unrelated operations before these memory objects are needed potentially hiding transfer latencies.
Once the event, returned from
clEnqueueMigrateMemObjects, has been marked
CL_COMPLETE the memory objects specified in
mem_objects have been successfully migrated to the device associated with
The migrated memory object shall remain resident on the device until another command is enqueued that either implicitly or explicitly migrates it away.
clEnqueueMigrateMemObjects can also be used to direct the initial placement of a memory object, after creation, possibly avoiding the initial overhead of instantiating the object on the first enqueued command to use it.
The user is responsible for managing the event dependencies, associated with this command, in order to avoid overlapping access to memory objects.
Improperly specified event dependencies passed to
clEnqueueMigrateMemObjects could result in undefined results.
CL_SUCCESS if the function is executed successfully.
Otherwise, it returns one of the following errors:
command_queueis not a valid host command_queue.
CL_INVALID_CONTEXTif the context associated with
command_queueand memory objects in
memobjare not the same or if the context associated with
command_queueand events in
event_wait_listare not the same.
CL_INVALID_MEM_OBJECTif any of the memory objects in
mem_objsis not a valid memory object.
num_mem_objectsis zero or if
flagsis not 0 or is not any of the values described in the table above.
event_wait_listis NULL and
num_events_in_wait_list> 0, or
event_wait_listis not NULL and
num_events_in_wait_listis 0, or if event objects in
event_wait_listare not valid events.
CL_MEM_OBJECT_ALLOCATION_FAILUREif there is a failure to allocate memory for the specified set of memory objects in
CL_OUT_OF_RESOURCESif there is a failure to allocate resources required by the OpenCL implementation on the device.
CL_OUT_OF_HOST_MEMORYif there is a failure to allocate resources required by the OpenCL implementation on the host.