CLRETAINCONTEXT(3clc)

💖 CLRETAINCONTEXT 💖

okay bestie, welcome to the 3clc corner of the OpenCL Manual, where we talk about the lil function that says "hey, don't delete that yet, i'm still using it 🫶". Yes, we're doing clRetainContext today and honestly? she's giving responsible roommate energy.

---

✨ NAME ✨

clRetainContext — increment the context reference count, aka ✨+1 bestie✨

cl_int clRetainContext(cl_context context);

---

🌸 PARAMETERS 🌸

• context — the context you wanna retain. that's it. that's the whole parameter list. she's low maintenance 💅

---

🎀 NOTES 🎀

okay so here's the tea 🍓 — clCreateContext(3clc) and clCreateContextFromType(3clc) do an implicit retain already. super helpful for 3rd party libraries, because those libraries typically just get a context handed to them by the application like "here, hold this 🫴".

but plot twist 😭 — the application might go and delete the context without telling the library. rude honestly. and then the library is out here holding a context that's no longer valid, which is not the vibe.

so letting functions attach to (i.e. retain) and release a context is literally the fix. it solves the whole problem of a context being used by a library no longer being valid. no cap 🧚

---

💀 ERRORS 💀

returns CL_SUCCESS if the function is executed successfully (slay). otherwise it returns one of these, and bestie you're gonna wanna read them:

• CL_INVALID_CONTEXT — if context is not a valid OpenCL context. it's giving fake ID at the club 🙈
• CL_OUT_OF_RESOURCES — if there is a failure to allocate resources required by the OpenCL implementation on the device. the device said "i'm full, no more 🍽️"
• CL_OUT_OF_HOST_MEMORY — if there is a failure to allocate resources required by the OpenCL implementation on the host. host memory said "not today 😭"

---

👑 SPECIFICATION 👑

OpenCL Specification[1]

---

🦋 SEE ALSO 🦋

• clCreateContext(3clc)
• clCreateContextFromType(3clc)
• clGetContextInfo(3clc)
• clReleaseContext(3clc)
• clGetContextInfo(3clc)

(yes, clGetContextInfo(3clc) is listed twice. the original said it twice, so we're saying it twice. that's just how she is 💖)

---

🌈 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 57, section 4.4 - Contexts

---

periodt 💅 that's the whole page. go forth and retain responsibly.

okay and one lil sign-off because i love you 🫶 — this whole thing comes from The Khronos Group, dated 01/14/2021, filed under CLRETAINCONTEXT(3clc). mwah 💋