CLWAITFOREVENTS(3clc)

💖 CLWAITFOREVENTS 💖 (that's CLWAITFOREVENTS(3clc), bestie — straight out of the OpenCL Manual)

okay so picture this: you got a bunch of commands out there doing their thing on the device, and you — the host thread — are just standing there. This is the function that makes you stand there on purpose. No cap.

---

✨ NAME ✨

clWaitForEvents — waits on the host thread for commands identified by event objects to complete. It's giving "girl, sit down and wait for your friends."

cl_int clWaitForEvents(cl_uint num_events, const cl_event *event_list);

---

🎀 PARAMETERS 🎀

• event_list — the events you drop in here act as synchronization points. They're literally the little checkpoints your host thread is waiting at. 👑

---

🦋 NOTES 🦋

So here's the tea: clWaitForEvents blocks the host thread until the commands identified by the event objects in event_list are done. And what counts as "done"? An event is considered complete if its execution status is CL_COMPLETE or a negative value. (yes, a negative value counts as complete — wild, I know, but that's what it says 🫶). The events you put in event_list act as synchronization points.

And if the cl_khr_gl_event(3clc) extension is enabled, event objects can also be used to reflect the status of an OpenGL sync object. That sync object in turn refers to a fence command executing in an OpenGL command stream. Which means: ✨ another method of coordinating sharing of buffers and images between OpenGL and OpenCL ✨. Iconic crossover episode, honestly.

---

💀 ERRORS 💀

It returns CL_SUCCESS if the execution status of all the events in event_list is CL_COMPLETE. Otherwise? Bestie, it returns one of these:

• CL_INVALID_VALUE — if num_events is zero or event_list is NULL.
• CL_INVALID_CONTEXT — if the events specified in event_list do not belong to the same context. (they gotta be in the same group chat, periodt.)
• CL_INVALID_EVENT — if the event objects specified in event_list are not valid event objects.
• CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST — if the execution status of any of the events in event_list is a negative integer value.
• CL_OUT_OF_RESOURCES — if there is a failure to allocate resources required by the OpenCL implementation on the device.
• CL_OUT_OF_HOST_MEMORY — if there is a failure to allocate resources required by the OpenCL implementation on the host.

not me having six different ways to fail. the range, honestly. 🙈

---

📜 SPECIFICATION 📜

OpenCL Specification[1]

---

👀 SEE ALSO 👀

clGetEventInfo(3clc), clReleaseEvent(3clc), clRetainEvent(3clc), cl_khr_gl_event(3clc)

like, go read your sisters. they get it.

---

🌸 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 179, section 5.9 - Event Objects

---

and that's the whole page, bestie!! 💅 this lil' rewrite is brought to you by The Khronos Group, dated 01/14/2021, and it's the CLWAITFOREVENTS(3clc) page in all its glory. go wait for your events. slay. ✨🦋💖