From 4d63a89fa6611a69c1999328375f39afde1b1696 Mon Sep 17 00:00:00 2001 From: Daniel Playfair Cal Date: Thu, 12 Aug 2021 03:58:08 +1000 Subject: [PATCH] Merge pull request #20536 from hedgepigdaniel:fix/ocl-context-create-ownership docs(core/ocl): clarify ownership of arguments passed into OpenCL related functions * docs(core/ocl): clarify ownership in OpenCLExecutionContext::create Although it is technically true that OpenCLExecutionContext::create calls `clRetainContext` on its context argument, it is misleading because it does not increase the reference count overall. Clarify that the ownership of one reference of the passed context and device is taken. * docs(core/ocl): document ownership transfer in ocl::Device::fromHandle --- modules/core/include/opencv2/core/ocl.hpp | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/modules/core/include/opencv2/core/ocl.hpp b/modules/core/include/opencv2/core/ocl.hpp index f9cc9e019a..03666df517 100644 --- a/modules/core/include/opencv2/core/ocl.hpp +++ b/modules/core/include/opencv2/core/ocl.hpp @@ -235,7 +235,11 @@ public: /** * @param d OpenCL handle (cl_device_id). clRetainDevice() is called on success. - */ + * + * @note Ownership of the passed device is passed to OpenCV on success. + * The caller should additionally call `clRetainDevice` on it if it intends + * to continue using the device. + */ static Device fromHandle(void* d); struct Impl; @@ -826,11 +830,13 @@ public: OpenCLExecutionContext cloneWithNewQueue() const; /** @brief Creates OpenCL execution context - * OpenCV will check if available OpenCL platform has platformName name, then assign context to - * OpenCV and call `clRetainContext` function. The deviceID device will be used as target device and - * new command queue will be created. + * OpenCV will check if available OpenCL platform has platformName name, + * then assign context to OpenCV. + * The deviceID device will be used as target device and a new command queue will be created. * - * @note Lifetime of passed handles is transferred to OpenCV wrappers on success + * @note On success, ownership of one reference of the context and device is taken. + * The caller should additionally call `clRetainContext` and/or `clRetainDevice` + * to increase the reference count if it wishes to continue using them. * * @param platformName name of OpenCL platform to attach, this string is used to check if platform is available to OpenCV at runtime * @param platformID ID of platform attached context was created for (cl_platform_id)