CLRELEASEEVENT(3clc)

💖 CLRELEASEEVENT (3clc) 💖

okay bestie, gather round, because today we're talking about clReleaseEvent from the OpenCL Manual — yes the whole manual, and yes it's iconic. This is the function that ✨decrements the event reference count✨. That's it. That's the vibe. Let's get into it. 🦋

cl_int clReleaseEvent(cl_event event);

---

🌸 PARAMETERS 🌸

• event — the event object you're releasing, babe. let it go. 🫶

---

✨ NOTES ✨

So, like, the whole thing this function does is decrement the event reference count. simple. elegant. no cap.

But here's where it gets real: the event object gets deleted once all three of these things are true, fr fr:

• the reference count becomes zero, AND
• the specific command identified by this event has completed (or terminated), AND
• there are no commands in the command-queues of a context that require a wait for this event to complete.

⚠️ okay this is the important part, bestie, pls read it ⚠️

Developers should be careful when releasing their last reference count on events created by clCreateUserEvent(3clc) that have not yet been set to status of CL_COMPLETE or an error. like, genuinely careful. 🙈

Here's the scenario: if the user event was used in the event_wait_list argument passed to a clEnqueue*** API, or another application host thread is waiting for it in clWaitForEvents(3clc), then those commands and host threads will continue to wait for the event status to reach CL_COMPLETE or error — even after the user has released the object. 😭

And since in this scenario the developer has released their last reference count to the user event, it would, in principle, no longer be valid for them to change the status of the event to unblock all the other machinery. So as a result: the waiting tasks will wait forever, and associated events, cl_mem objects, command queues and contexts are likely to leak. 💀

And it gets worse — in-order command queues caught up in this deadlock may cease to do any work. straight up not having a good time. 🧚

---

🔥 ERRORS 🔥

Returns CL_SUCCESS if the function executed successfully. otherwise, it returns one of these:

• CL_INVALID_EVENT — if event is not a valid event object. 👎
• 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.

---

👑 SPECIFICATION 👑

OpenCL Specification[1]

---

🌈 SEE ALSO 🌈

• clGetEventInfo(3clc)
• clRetainEvent(3clc)
• clWaitForEvents(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 185, section 5.9 - Event Objects

---

and that's the whole page, bestie!! 💖✨ this was brought to you by The Khronos Group, dated 01/14/2021, and it lives under the name CLRELEASEEVENT(3clc) in the OpenCL Manual. go forth and release your events responsibly, and pls pls pls don't create the deadlock. i'm begging. 🦋🌸🎀🫶