CLENQUEUETASK(3clc)

💖 NAME 💖

clEnqueueTask — bestie, this is the one that drops a kernel onto a device and says go, girl, go.

cl_int clEnqueueTask(cl_command_queue command_queue, cl_kernel kernel,
                     cl_uint num_events_in_wait_list,
                     const cl_event *event_wait_list, cl_event *event);

This is page 3clc of the OpenCL manual, and we're about to make queueing a kernel make so much sense. 🎀

---

🌸 PARAMETERS 🌸

• command_queue — a valid command-queue, no cap. Your kernel gets queued for execution on the device that's associated with command_queue. That's the whole vibe.
• kernel — a valid kernel object. And listen: the OpenCL context associated with kernel and the one associated with command_queue must be the same. Same context or it's not happening, fr fr.
• num_events_in_wait_list, event_wait_list — these two specify events that need to finish before this particular command can even be executed. The rules, bestie, are very specific:
  • if event_wait_list is NULL, then this particular command does not wait on any event to complete.
  • if event_wait_list is NULL, then num_events_in_wait_list must be 0.
  • if event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0.
  • the events specified in event_wait_list act as synchronization points — that's their whole job, their main character moment.
  • the context associated with the events in event_wait_list and the context associated with command_queue must be the same.
  • the memory associated with event_wait_list can be reused or freed after the function returns. So you don't have to keep it around, she's free. 🦋
• event — this returns an event object that identifies this particular kernel execution instance. Event objects are unique, and you can use them later to identify that specific kernel execution instance. But if event is NULL, no event gets created for this kernel execution instance at all — which means your application literally cannot query it or queue a wait for that particular kernel execution instance. So like, no receipts. 💀

---

✨ NOTES ✨

The kernel is executed using a single work-item. That's it. One. Solo. Main character energy.

clEnqueueTask is equivalent to calling clEnqueueNDRangeKernel(3clc) with:

• work_dim = 1
• global_work_offset = NULL
• global_work_size[0] set to 1
• local_work_size[0] set to 1

So if you already know clEnqueueNDRangeKernel, you already know her. 👑

---

🔥 ERRORS 🔥

Returns CL_SUCCESS if the kernel execution was successfully queued. Slay. Otherwise you get one of these below:

• CL_INVALID_PROGRAM_EXECUTABLE — there is no successfully built program executable available for the device associated with command_queue. Nothing to run, bestie. 😭
• CL_INVALID_COMMAND_QUEUE — command_queue is not a valid command-queue.
• CL_INVALID_KERNEL — kernel is not a valid kernel object.
• CL_INVALID_CONTEXT — the context associated with command_queue and kernel is not the same, or the context associated with command_queue and the events in event_wait_list are not the same.
• CL_INVALID_KERNEL_ARGS — the kernel argument values have not been specified. Feed her, she's hungry. 🍓
• CL_INVALID_WORK_GROUP_SIZE — a work-group size is specified for kernel using the functionQualifiers(3clc) ((reqd_work_group_size(X, Y, Z))) qualifier in the program source, and it is not (1, 1, 1).
• CL_MISALIGNED_SUB_BUFFER_OFFSET — a sub-buffer object is specified as the value for an argument that is a buffer object, and the offset specified when the sub-buffer object is created is not aligned to the CL_DEVICE_MEM_BASE_ADDR_ALIGN value for the device associated with the queue.
• CL_INVALID_IMAGE_SIZE — an image object is specified as an argument value, and the image dimensions (image width, height, specified or compute row and/or slice pitch) are not supported by the device associated with the queue.
• CL_INVALID_IMAGE_FORMAT — an image object is specified as an argument value, and the image format (image channel order and data type) is not supported by the device associated with the queue.
• CL_OUT_OF_RESOURCES — there is a failure to queue the execution instance of kernel on the command-queue because of insufficient resources needed to execute the kernel.
• CL_MEM_OBJECT_ALLOCATION_FAILURE — there is a failure to allocate memory for the data store associated with image or buffer objects specified as arguments to kernel.
• CL_INVALID_EVENT_WAIT_LIST — event_wait_list is NULL and num_events_in_wait_list > 0, or event_wait_list is not NULL and num_events_in_wait_list is 0, or the event objects in event_wait_list are not valid events.
• CL_OUT_OF_RESOURCES — there is a failure to allocate resources required by the OpenCL implementation on the device.
• CL_OUT_OF_HOST_MEMORY — there is a failure to allocate resources required by the OpenCL implementation on the host.

Yes, CL_OUT_OF_RESOURCES shows up twice, once for the device and once for the host. That's not a typo, that's just the lore. 🙈

---

📜 SPECIFICATION 📜

OpenCL Specification[1]

---

👀 SEE ALSO 👀

clEnqueueNDRangeKernel(3clc), clEnqueueNativeKernel(3clc)

---

💜 AUTHORS 💜

The Khronos Group

---

🌈 COPYRIGHT 🌈

Copyright © 2007-2011 The Khronos Group Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and/or associated documentation files (the "Materials"), to deal in the Materials without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Materials, and to permit persons to whom the Materials are furnished to do so, subject to the condition that this copyright notice and permission notice shall be included in all copies or substantial portions of the Materials.

---

🧚 NOTES 🧚

1. OpenCL Specification — page 172, section 5.8 - Executing Kernels (updated for 1.2 rev 14)

---

okay that's the whole page bestie, mwah 💅 — this was CLENQUEUETASK(3clc), brought to you by The Khronos Group and dated 01/14/2021. Go queue something iconic. 🫶✨