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 devices returned by clGetDeviceIDs or sub-devices created by clCreateSubDevices for a platform. [1]

  • 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 application’s 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 clCreateContext
Context Property 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

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 2014-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0


1. Duplicate devices specified in devices are ignored.