CLRETAINMEMOBJECT(3clc)

💖 CLRETAINMEMOBJECT 💖

okay bestie, welcome to the OpenCL Manual page for clRetainMemObject — yes the manual name is literally baked into the title, we're keeping it, it's iconic 🎀

---

✨ NAME ✨

clRetainMemObject — Increments the memory object reference count.

cl_int clRetainMemObject(cl_mem memobj);

like... it's giving "one more for the road" 🫶

---

🌸 PARAMETERS 🌸

• memobj — A valid memory object. that's it. that's the whole vibe check. it has to be valid, bestie, we're not playing games 💅

---

🦋 NOTES 🦋

okay so listen, this is important:

clCreateBuffer(3clc), clCreateSubBuffer(3clc), and clCreateImage(3clc), and perform an implicit retain.

translation: those three already did the retaining for you, no cap. you didn't even have to ask 👑

After the memobj reference count becomes zero and commands queued for execution on a command-queue(s) that use memobj have finished, the memory object is deleted. If memobj is a buffer object, memobj cannot be deleted until all sub-buffer objects associated with memobj are deleted.

lowkey this is the whole plot: count hits zero ➡️ wait for the queued commands to finish ➡️ then it's deleted. and if memobj is a buffer object? it cannot be deleted until all sub-buffer objects associated with memobj are deleted. the sub-buffers hold the main character hostage fr 😭

---

🔥 ERRORS 🔥

Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

• CL_INVALID_MEM_OBJECT — if memobj is a not a valid memory object (buffer or image object). not me passing a fake memory object 🙈
• CL_OUT_OF_RESOURCES — if there is a failure to allocate resources required by the OpenCL implementation on the device. the device said no 💀
• CL_OUT_OF_HOST_MEMORY — if there is a failure to allocate resources required by the OpenCL implementation on the host. and now the host said no 😭

---

📜 SPECIFICATION 📜

OpenCL Specification[1]

---

👀 SEE ALSO 👀

• clCreateBuffer(3clc)
• clEnqueueCopyBuffer(3clc)
• clEnqueueReadBuffer(3clc)
• clEnqueueWriteBuffer(3clc)
• clReleaseMemObject(3clc)

go read those too, iykyk 🌈

---

💜 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 following conditions:

wait, bestie, the original said "subject to the condition that this copyright notice and permission notice shall be included in all copies or substantial portions of the Materials." — so here it is, in full, keeping every word:

the condition is: this copyright notice and permission notice shall be included in all copies or substantial portions of the Materials. periodt 💅

---

📎 NOTES 📎 (the footnote ones)

1. OpenCL Specification — page 118, section 5.4.1 - Retaining and Releasing Memory Objects

---

and that's the whole page, bestie!! written by The Khronos Group, dated 01/14/2021, and it's the CLRETAINMEMOBJECT(3clc) page from the OpenCL Manual ✨ you ate that 🫶💖