C Specification

To create an OpenCL context, call the function:

cl_context clCreateContext(
    const cl_context_properties* properties,
    cl_uint num_devices,
    const cl_device_id* devices,
    void (CL_CALLBACK* pfn_notify)(const char* errinfo, const void* private_info, size_t cb, void* user_data),
    void* user_data,
    cl_int* errcode_ret);

Parameters

  • properties specifies a list of context property names and their corresponding values. Each property name is immediately followed by the corresponding desired value. The list is terminated with 0. The list of supported properties is described in the Context Properties table. properties can be NULL in which case the platform that is selected is implementation-defined.

  • num_devices is the number of devices specified in the devices argument.

  • devices is a pointer to a list of unique devices9 returned by clGetDeviceIDs or sub-devices created by clCreateSubDevices for a platform.

    9

    Duplicate devices specified in devices are ignored.

  • pfn_notify is a callback function that can be registered by the application. This callback function will be used by the OpenCL implementation to report information on errors during context creation as well as errors that occur at runtime in this context. This callback function may be called asynchronously by the OpenCL implementation. It is the applications responsibility to ensure that the callback function is thread-safe. If pfn_notify is NULL, no callback function is registered.

  • user_data will be passed as the user_data argument when pfn_notify is called. user_data can be NULL.

  • errcode_ret will return an appropriate error code. If errcode_ret is NULL, no error code is returned.

Description

The parameters to the callback function pfn_notify are:

  • errinfo is a pointer to an error string.

  • private_info and cb represent a pointer to binary data that is returned by the OpenCL implementation that can be used to log additional information helpful in debugging the error.

  • user_data is a pointer to user supplied data.

Contexts are used by the OpenCL runtime for managing objects such as command-queues, memory, program and kernel objects and for executing kernels on one or more devices specified in the context.

Table 1. List of supported context creation properties by https://www.khronos.org/registry/OpenCL/specs/2.2/html/OpenCL_API.html#clCreateContext
cl_context_properties enum Property value Description

CL_​CONTEXT_​PLATFORM

cl_platform_id

Specifies the platform to use.

CL_​CONTEXT_​INTEROP_​USER_​SYNC

Missing before version 1.2.

cl_bool

Specifies whether the user is responsible for synchronization between OpenCL and other APIs. Please refer to the specific sections in the OpenCL Extension Specification that describe sharing with other APIs for restrictions on using this flag.

If CL_​CONTEXT_​INTEROP_​USER_​SYNC is not specified, a default of CL_​FALSE is assumed.
There are a number of cases where error notifications need to be delivered due to an error that occurs outside a context. Such notifications may not be delivered through the pfn_notify callback. Where these notifications go is implementation-defined.

clCreateContext returns a valid non-zero context and errcode_ret is set to CL_​SUCCESS if the context is created successfully. Otherwise, it returns a NULL value with the following error values returned in errcode_ret:

  • CL_​INVALID_​PLATFORM if properties is NULL and no platform could be selected or if platform value specified in properties is not a valid platform.

  • CL_​INVALID_​PROPERTY if context property name in properties is not a supported property name, if the value specified for a supported property name is not valid, or if the same property name is specified more than once. This error code is missing before version 1.1.

  • CL_​INVALID_​VALUE if devices is NULL.

  • CL_​INVALID_​VALUE if num_devices is equal to zero.

  • CL_​INVALID_​VALUE if pfn_notify is NULL but user_data is not NULL.

  • CL_​INVALID_​DEVICE if any device in devices is not a valid device.

  • CL_​DEVICE_​NOT_​AVAILABLE if a device in devices is currently not available even though the device was returned by clGetDeviceIDs.

  • 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.

It is possible that a device(s) becomes unavailable after a context and command-queues that use this device(s) have been created and commands have been queued to command-queues. In this case the behavior of OpenCL API calls that use this context (and command-queues) are considered to be implementation-defined. The user callback function, if specified, when the context is created can be used to record appropriate information in the errinfo, private_info arguments passed to the callback function when the device becomes unavailable.

See Also

cl_context_properties, cl_device_id, cl_int, cl_uint

Document Notes

For more information, see the OpenCL Specification

This page is extracted from the OpenCL Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright (c) 2014-2020 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.