uncomplicate.clojurecl.core

Core ClojureCL functions for OpenCL host programming. The kernels should be provided as strings (that may be stored in files), written in OpenCL C.

The OpenCL standard defines several datastructures (platform, device, etc.) that support the concepts defined in four OpenCL models (Platform Model, Memory Model, Execution Model, and Programming Model). ClojureCL uses a low-level JNI-based library JOCL for calling native OpenCL drivers - the datastructures are therefore defined in JOCL. They can be found in org.jocl package.

Some functions are available in two versions:

  • High-level, which works with clojure-friendly arguments - vectors, sequences, keywords, etc. These are preferred to low-level alternatives.
  • Low-level, suffexed by *, which works with primitive arguments and gives primitive results. These functions are useful when you already have primitive data and want to avoid unnecessary conversions

The documentation given here is only a quick reminder; it is necessary to grasp OpenCL and parallel computing concepts to be able to use the library. Also, each function’s doc entry have a link to much more detailed documentation available in OpenCL and JOCL reference - be sure to browse one of these documents wherever you are not sure about some of many important details.

Cheat Sheet

*command-queue*

dynamic

Dynamic var for binding the default command queue.

*context*

dynamic

Dynamic var for binding the default context.

*platform*

dynamic

Dynamic var for binding the default platform.

Argument

protocol

Object that can be argument in OpenCL kernels. Built-in implementations: CLBuffer, java numbers, primitive arrays and ByteBuffers.

members

set-arg

(set-arg arg kernel n)

Specific implementation of setting the kernel arguments.

build-program!

(build-program! program devices options ch user-data)(build-program! program devices options ch)(build-program! program options ch)(build-program! program ch)(build-program! program)

Builds (compiles and links) a program executable; returns the program changed with side effects on program argument.

Accepts the following arguments (nil is allowed for all optional arguments):

  • program: previously loaded cl_program that contains the program source or binary;
  • devices (optional): an optional sequence of cl_devices associated with the program (if not supplied, all devices are used);
  • options (optional): an optional string of compiler options (such as “-Dname=value”);
  • ch (optional): core.async channel for notifications. If supplied, the build will be asynchronous;
  • user-data (optional): passed as part of notification data.

In case of OpenCL errors during the program build, throws Exceptioninfo.

See https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clBuildProgram.html, http://www.jocl.org/doc/org/jocl/CL.html#clBuildProgram-org.jocl.cl_program-int-org.jocl.cl_device_id:A-java.lang.String-org.jocl.BuildProgramFunction-java.lang.Object-

Examples:

(build-program! program) ; synchronous
(build-program! program ch) ; asynchronous
(build-program! program "-cl-std=CL2.0" ch) ; asynchronous
(build-program! program [dev] "-cl-std=CL2.0" ch) ; async
(build-program! program [dev] "-cl-std=CL2.0" ch :my-data) ; async

cl-buffer

(cl-buffer ctx size flag & flags)(cl-buffer size flag)(cl-buffer size)

Creates a cl buffer object (CLBuffer) in ctx, given size in bytes and one or more memory allocation usage keyword flags: :read-write, :read-only, :write-only, :use-host-ptr, :alloc-host-ptr, :copy-host-ptr, :host-write-only, :host-read-only, :host-no-access.

If called with two arguments, uses the default *context* (see with-context).

Needs to be released after use.

If ctx is nil or the buffer size is invalid, throws ExceptionInfo. If some of the flags is invalid, throws IllegalArgumentexception.

See http://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clCreateBuffer.html, http://www.jocl.org/doc/org/jocl/CL.html#clCreateBuffer-org.jocl.cl_context-long-long-org.jocl.Pointer-int:A-

Examples:

(cl-buffer 32 :read-only) (cl-buffer ctx 24 :write-only)

cl-buffer*

(cl-buffer* ctx size flags)

Creates a cl buffer object in ctx, given size in bytes and a bitfield flags describing memory allocation usage.

Flags defined by the OpenCL standard are available as constants in the org.jocl.CL class.

Needs to be released after use.

This is a low-level alternative to cl-buffer If ctx is nil or the buffer size is invalid, throws ExceptionInfo.

See http://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clCreateBuffer.html, http://www.jocl.org/doc/org/jocl/CL.html#clCreateBuffer-org.jocl.cl_context-long-long-org.jocl.Pointer-int:A-

Example:

(cl-buffer* ctx 24 CL/CL_MEM_READ_ONLY)

cl-buffer?

(cl-buffer? x)

Checks whether an object is a CL buffer.

cl-sub-buffer

(cl-sub-buffer buffer origin size flag & flags)(cl-sub-buffer buffer origin size)

Creates a cl buffer object (CLBuffer) that shares data with an existing buffer object.

  • buffer has to be a valid CLBuffer object.
  • origin and size are numbers that denote offset and size of the region in the origin buffer.
  • flag and flags are memory allocation usage keywords same as in cl-buffer

Needs to be released after use.

See http://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clCreateSubBuffer.html, http://www.jocl.org/doc/org/jocl/CL.html#clCreateSubBuffer-org.jocl.cl_mem-long-int-org.jocl.cl_buffer_region-int:A-

Examples:

(def cl-buff (cl-buffer ctx 32 :write-only))
(cl-sub-buffer cl-buff 8 16 :write-only)
(cl-sub-buffer cl-buff 8 16)

cl-sub-buffer*

(cl-sub-buffer* buffer flags create-type region)(cl-sub-buffer* buffer flags region)

Creates a cl buffer object (CLBuffer) that shares data with an existing buffer object.

  • buffer has to be a valid BLBuffer buffer object.
  • flags is a bitfield that specifies allocation usage (see cl-buffer*).
  • create-type is a type of buffer object to be created (in OpenCL 2.0, only CL/CL_BUFFER_CREATE_TYPE_REGION is supported).
  • region is a cl_buffer_region that specifies offset and size of the subbuffer.

Needs to be released after use.

See http://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clCreateBuffer.html, http://www.jocl.org/doc/org/jocl/CL.html#clCreateBuffer-org.jocl.cl_context-long-long-org.jocl.Pointer-int:A-

Examples:

(def cl-buff (cl-buffer ctx 32 :write-only)) (def region (cl_buffer_region. 8 16)) (cl-sub-buffer* cl-buff CL/CL_MEM_READ_WRITE CL/CL_BUFFER_CREATE_TYPE_REGION region) (cl-sub-buffer* cl-buff CL/CL_MEM_READ_ONLY region)

CLMem

protocol

A wrapper for cl_mem objects, that also holds a Pointer to the cl mem object, context that created it, and size in bytes. It is useful in many functions that need that (redundant in Java) data because of the C background of OpenCL functions.

members

cl-mem

(cl-mem this)

The raw JOCL cl_mem object.

enq-copy*

(enq-copy* this queue dst src-offset dst-offset cb wait-events ev)

A specific implementation for copying this cl-mem object to another cl mem.

enq-fill*

(enq-fill* this queue pattern offset multiplier wait-events ev)

A specific implementation for filling this cl-mem object.

command-queue

(command-queue ctx device x & properties)(command-queue ctx device)(command-queue device)

Creates a host or device command queue on a specific device.

** If you need to support OpenCL 1.2 platforms, you MUST use the alternative [command-queue-1] function or or risk JVM crash. What is important is the version of the platform, not the devices. This function is for platforms (regardless of the devices) supporting OpenCL 2.0 and higher. **

Arguments are:

  • ctx - the cl_context for the queue;
  • device - the cl_device_id for the queue;
  • x - if integer, the size of the (on device) queue, otherwise treated as property;
  • properties - additional optional keyword properties: :profiling, :queue-on-device, :out-of-order-exec-mode, and queue-on-device-default;

Needs to be released after use.

See also command-queue*.

If called with invalid context or device, throws ExceptionInfo. If called with any invalid property, throws NullPointerexception.

See https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clCreateCommandQueueWithProperties.html, http://www.jocl.org/doc/org/jocl/CL.html#clCreateCommandQueueWithProperties-org.jocl.cl_context-org.jocl.cl_device_id-org.jocl.cl_queue_properties-int:A-

Examples:

 (command-queue ctx)
 (command-queue ctx dev)
 (command-queue ctx dev :profiling :queue-on-device :out-of-order-execution-mode)
 (command-queue ctx dev 524288 :queue-on-device)

command-queue*

(command-queue* ctx device properties)(command-queue* ctx device size properties)

Creates a host or device command queue on a specific device.

** If you need to support OpenCL 1.2 platforms, you MUST use the alternative [command-queue-1*] function or or risk JVM crash. What is important is the version of the platform, not the devices. This function is for platforms (regardless of the devices) supporting OpenCL 2.0 and higher. **

Arguments are:

  • ctx - the cl_context for the queue;
  • device - the cl_device_id for the queue;
  • size - the size of the (on device) queue;
  • properties - long bitmask containing properties, defined by the OpenCL standard are available as constants in the org.jocl.CL class.

This is a low-level version of command-queue.

If called with invalid context or device, throws ExceptionInfo.

See https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clCreateCommandQueueWithProperties.html, http://www.jocl.org/doc/org/jocl/CL.html#clCreateCommandQueueWithProperties-org.jocl.cl_context-org.jocl.cl_device_id-org.jocl.cl_queue_properties-int:A-

Examples: (command-queue* ctx dev 524288 (bit-or CL/CL_QUEUE_PROFILING_ENABLED CL/CL_QUEUE_ON_DEVICE)) (command-queue* ctx dev CL/CL_QUEUE_PROFILING_ENABLED)

context

(context devices properties ch user-data)(context devices)(context)

Creates cl_context for a vector of devices, with optional hashmap of properties, error reporting core.async channel ch and user data that should accompany the error report. If called with no arguments, creates a context using all devices of the default platform (*platform).

If devices is empty, throws ExceptionInfo.

Needs to be released after use. (see with-context).

See http://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clCreateContext.html , http://www.jocl.org/doc/org/jocl/CL.html#clCreateContext-org.jocl.cl_context_properties-int-org.jocl.cl_device_id:A-org.jocl.CreateContextFunction-java.lang.Object-int:A-

Examples:

  (context)
  (context (devices (first (platforms))))
  (context (devices (first (platforms))) {:platform p} (chan) :my-data)

context*

(context* devices properties ch user-data)

Creates cl_context for an array of devices, with optional cl_context_properties, error reporting core.async channel ch and user data that should accompany the error report.

If devices is empty, throws ExceptionInfo.

Needs to be released after use.

This is a low-level alternative to context.

See http://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clCreateContext.html See throws Illegalargumentexceptionhttp://www.jocl.org/doc/org/jocl/CL.html#clCreateContext-org.jocl.cl_context_properties-int-org.jocl.cl_device_id:A-org.jocl.CreateContextFunction-java.lang.Object-int:A-

context-info

(context-info)

Info of the default context (*context*). If *context* is unbound, throws Illegalargumentexception

See also: with-context

Example:

(with-context (context devices)
    (context-info))

context-properties

(context-properties props)

Creates cl_context_properties from a map of properties. Currently, this is not very useful, it is only here to support the full compatibility of context* function with the JOCL API.

Contextual

protocol

An object that has some dependency on a cl_context.

members

cl-context

(cl-context this)

Context that is related to this object.

devices

(devices platform device-type & device-types)(devices x)(devices)

Queries platform for the devices of one or a combination of several device-types: :gpu, :cpu, :all, :accelerator, :custom, :default, and returns them in a vector containing cl_device_id objects.

When called with only one argument x:

  • if x is a keyword, returns the devices of type x in *platform*;
  • otherwise returns all devices on the platform x.

When called with no arguments, returns all devices in *platform*.

Root level devices do not need to be explicitly released.

When called with an invalid platform, throws ExceptionInfo. When called with an unknown device type, throws NullPointerException

See also devices*.

Examples:

(devices)
(devices (first (platforms)))
(devices :gpu)
(devices (first (platforms)) :gpu :cpu :accelerator)

devices*

(devices* platform device-type)

Queries platform for the devices of device-types, and returns them as an array of cl_device_ids. The types are given as a bitfield, where each type is a number constant defined in the OpenCL standard. Available device types are accessible through org.jocl.CL/CL_DEVICE_TYPE_X constants. If there are no such devices, returns a zero-length array.

Root level devices do not need to be explicitly released.

NOTE: You should prefer a higher-level devices function, unless you already have a device-type in a long number form in your code, and/or you want to get resulting devices in an array rather than in a vector.

When called with an invalid platform, throws ExceptionInfo.

See http://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clGetDeviceIDs.html and http://www.jocl.org/doc/org/jocl/CL.html#clGetDeviceIDs-int-org.jocl.cl_device_id:A-int:A-

enq-barrier!

(enq-barrier! queue)(enq-barrier! queue ev)(enq-barrier! queue wait-events ev)

A synchronization point that enqueues a barrier operation. Returns the queue.

See https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clEnqueueBarrierWithWaitList, http://www.jocl.org/doc/org/jocl/CL.html#clEnqueueBarrierWithWaitList-org.jocl.cl_command_queue-int-org.jocl.cl_event:A-org.jocl.cl_event-

Examples:

(enq-barrier! queue (events ev-nd) ev-map) (enq-barrier! queue) (enq-barrier! queue ev-map)

enq-copy!

(enq-copy! queue cl-src cl-dst src-offset dst-offset size wait-events ev)(enq-copy! queue cl-src cl-dst size wait-events ev)(enq-copy! queue cl-src cl-dst wait-events ev)(enq-copy! queue cl-src cl-dst size)(enq-copy! queue cl-src cl-dst)(enq-copy! cl-src cl-dst)

Enqueues a command to copy from one CLMem memory object to another.

In case of OpenCL errors, throws an ExceptionInfo.

See https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clEnqueueCopyBuffer.html http://www.jocl.org/doc/org/jocl/CL.html#clEnqueueCopyBuffer-org.jocl.cl_command_queue-org.jocl.cl_mem-org.jocl.cl_mem-long-long-long-int-org.jocl.cl_event:A-org.jocl.cl_event-

Examples:

(enq-copy! my-queue cl-src cl-dst 4 8 32 (events) ev)

enq-fill!

(enq-fill! queue this pattern offset multiplier wait-events ev)(enq-fill! queue this pattern wait-events ev)(enq-fill! queue this pattern)(enq-fill! this pattern)

Enqueues a command to fill a buffer object with a Mem pattern.

In case of OpenCL errors, throws an ExceptionInfo.

See https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clEnqueueFillBuffer.html http://www.jocl.org/doc/org/jocl/CL.html#clEnqueueFillBuffer-org.jocl.cl_command_queue-org.jocl.cl_mem-org.jocl.Pointer-long-long-long-int-org.jocl.cl_event:A-org.jocl.cl_event-

Examples:

(enq-fill! my-queue cl-buf (float-array [1 2 3 4]) 2 (events) ev)

enq-map-buffer!

(enq-map-buffer! queue cl blocking offset req-size flags wait-events event)(enq-map-buffer! queue cl offset req-size flags wait-events event)(enq-map-buffer! queue cl flags wait-events event)(enq-map-buffer! queue cl flags event)(enq-map-buffer! queue cl flags)(enq-map-buffer! cl flags)

Enqueues a command to map a region of the cl buffer into the host address space. Returns the mapped java.nio.ByteBuffer. The result must be unmapped by calling enq-unmap! for the effects of working with the mapping byte buffer to be transfered back to the device memory.

Arguments:

  • queue (optional): the cl_command_queue that maps the object. If omitted, *command-queue* will be used.
  • cl: the CLMem that is going to be mapped to.
  • blocking: whether the operation is blocking or non-blocking.
  • offset: integer value of the memory offset in bytes.
  • req-size: integer value of the requested size in bytes (if larger than the available data, it will be shrinked).
  • flags: one keyword or a sequence of keywords that indicates memory mapping settings: :read, :write, and/or :write-invalidate-settings.
  • wait-events (optional): events array specifying the events (if any) that need to complete before this operation.
  • event (optional): if specified, the cl_event object tied to the execution of this operation.

If event is specified, the operation is asynchronous, otherwise it blocks the current thread until the data transfer completes. See also register.

See https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clEnqueueMapBuffer.html, http://www.jocl.org/doc/org/jocl/CL.html#clEnqueueMapBuffer-org.jocl.cl_command_queue-org.jocl.cl_mem-boolean-long-long-long-int-org.jocl.cl_event:A-org.jocl.cl_event-int:A-

Examples:

(enq-map-buffer! queue cl-data :write (events ev-nd) ev-map)
(enq-map-buffer! queue cl-data [:write :read])
(enq-map-buffer! cl-data :write)

enq-map-buffer*

(enq-map-buffer* queue cl blocking offset req-size flags wait-events event)

Enqueues a command to map a region of the cl buffer into the host address space. Returns the mapped java.nio.ByteBuffer. The result must be unmapped by calling enq-unmap! for the effects of working with the mapping byte buffer to be transfered back to the device memory.

Arguments:

  • queue (optional): the cl_command_queue that maps the object. If omitted, *command-queue* will be used.
  • cl: the CLMem that is going to be mapped to.
  • blocking: whether the operation is blocking (CL/CL_TRUE) or non-blocking (CL/CL_FALSE).
  • offset: integer value of the memory offset in bytes.
  • req-size: integer value of the requested size in bytes (if larger than the available data, it will be shrinked.).
  • flags: a bitfield that indicates whether the memory is mapped for reading (CL/CL_MAP_READ), writing (CL/CL_MAP_WRITE) or both (bit-or CL/CL_MAP_READ CL/CL_MAP_WRITE).
  • wait-events (optional): events array specifying the events (if any) that need to complete before this operation.
  • event (optional): if specified, the cl_event object tied to the execution of this operation.

This is a low-level version of enq-map-buffer!.

See https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clEnqueueMapBuffer.html, http://www.jocl.org/doc/org/jocl/CL.html#clEnqueueMapBuffer-org.jocl.cl_command_queue-org.jocl.cl_mem-boolean-long-long-long-int-org.jocl.cl_event:A-org.jocl.cl_event-int:A-

Examples:

(enq-map-buffer* queue cl-data true 0 CL/CL_WRITE (events ev-nd) ev-map)

enq-marker!

(enq-marker! queue)(enq-marker! queue ev)(enq-marker! queue wait-events ev)

Enqueues a marker command which waits for either a list of events to complete, or all previously enqueued commands to complete. Returns the queue.

See https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clEnqueueMarkerWithWaitList,

http://www.jocl.org/doc/org/jocl/CL.html#clEnqueueMarkerWithWaitList-org.jocl.cl_command_queue-int-org.jocl.cl_event:A-org.jocl.cl_event- Examples:

(enq-marker! queue (events ev-nd) ev-map) (enq-marker! queue) (enq-marker! queue ev-map)

enq-nd!

(enq-nd! queue kernel work-size wait-events event)(enq-nd! queue kernel work-size event)(enq-nd! queue kernel work-size)(enq-nd! kernel work-size)

Enqueues a command to asynchronously execute a kernel on a device. Returns the queue.

Arguments:

  • queue (optional): the cl_command_queue that executes the kernel. If omitted, *command-queue* will be used.
  • kernel: the cl_kernel that is going to be executed.
  • work-size: WorkSize containing the settings of execution (global work size, local work size, global work offset).
  • wait-events (optional): events array specifying the events (if any) that need to complete before this command can be executed.
  • event (optional): if specified, the cl_event object tied to the execution of this command.

If an OpenCL error occurs during the call, throws ExceptionInfo.

See https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clEnqueueNDRangeKernel.html, http://www.jocl.org/doc/org/jocl/CL.html#clEnqueueNDRangeKernel-org.jocl.cl_command_queue-org.jocl.cl_kernel-int-long:A-long:A-long:A-int-org.jocl.cl_event:A-org.jocl.cl_event-

Examples:

(enq-nd! my-kernel (work-size [8]))
(enq-nd! my-queue my-kernel (work-size [8]))
(enq-nd! my-queue my-kernel (work-size [8] (events event1 event2) my-event))

enq-read!

(enq-read! queue cl host blocking offset wait-events event)(enq-read! queue cl host wait-events event)(enq-read! queue cl host event)(enq-read! queue cl host)(enq-read! cl host)

Enqueues a command to read from a cl object to host memory. Returns the queue.

  • queue (optional): the cl_command_queue that reads the object. If omitted, *command-queue* will be used.
  • cl: the CLMem that is going to be read from.
  • host: Mem object on the host that the data is to be transferred to. Must be a direct buffer is the reading is asynchronous.
  • blocking: boolean indicator of synchronization.
  • offset: the offset in bytes in the buffer object to read from.
  • wait-events (optional): events array specifying the events (if any) that need to complete before this operation.
  • event (optional): if specified, the cl_event object tied to the execution of this operation.

If event is specified, the operation is asynchronous, otherwise it blocks the current thread until the data transfer completes, unless explicitly specifiend with blocking. See also register.

See https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clEnqueueReadBuffer.html, http://www.jocl.org/doc/org/jocl/CL.html#clEnqueueReadBuffer-org.jocl.cl_command_queue-org.jocl.cl_mem-boolean-long-long-org.jocl.Pointer-int-org.jocl.cl_event:A-org.jocl.cl_event-

Examples:

(let [host-data (direct-buffer 32)
      ev (event)
      notifications (chan)
      follow (register notifications)]
  (enq-read! my-queue cl-data host-data ev) ;; asynchronous
  (follow ev)
  (<!! notifications))

(enq-read! my-queu cl-data host-data) ;; blocking

enq-svm-map!

(enq-svm-map! queue svm flags wait-events event)(enq-svm-map! queue svm flags event)(enq-svm-map! queue svm flags)(enq-svm-map! svm flags)

Enqueues a command that will allow the host to update a region of a SVM buffer. . Returns the mapped java.nio.ByteBuffer (which is the same byte buffer that is already accessible through (byte-buffer svm)). Together with enq-svm-unmap!, works as a synchronization point.

Arguments:

  • queue (optional): the cl_command_queue that maps the object. If omitted, *command-queue* will be used.
  • svm: the SVMMem that is going to be mapped to.
  • offset (optional): integer value of the memory offset in bytes.
  • flags (optional): a bitfield that indicates whether the memory is mapped for reading :read, :write, and/or :write-invalidate-region.
  • wait-events (optional): events array specifying the events (if any) that need to complete before this operation.
  • event (optional): if specified, the cl_event object tied to the execution of this operation.

If event is specified, the operation is asynchronous, otherwise it blocks the current thread until the data transfer completes. See also register.

See also enq-svm-map*.

See https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clEnqueueSVMMap.html, http://www.jocl.org/doc/org/jocl/CL.html#clEnqueueSVMMap-org.jocl.cl_command_queue-boolean-long-org.jocl.Pointer-long-int-org.jocl.cl_event:A-org.jocl.cl_event-

Examples:

  (enq-svm-map queue svm-data 0 [:write :read] (events ev-nd) ev-map)
  (enq-svm-map queue svm-data [:write :read] (events ev-nd) ev-map)
  (enq-svm-map queue svm-data :write ev-map)
  (enq-svm-map queue svm-data :read)
  (enq-svm-map svm-data :write-invalidate-region)

enq-svm-map*

(enq-svm-map* queue svm blocking flags wait-events event)

Enqueues a command that will allow the host to update a region of a SVM buffer. . Returns the mapped java.nio.ByteBuffer (which is the same byte buffer that is already accessible through (byte-buffer svm)). Together with enq-svm-unmap!, works as a synchronization point.

Arguments:

  • queue (optional): the cl_command_queue that maps the object. If omitted, *command-queue* will be used.
  • svm: the SVMMem that is going to be mapped to.
  • blocking: whether the operation is blocking (CL/CL_TRUE) or non-blocking (CL/CL_FALSE).
  • flags: a bitfield that indicates whether the memory is mapped for reading (CL/CL_MAP_READ), writing (CL/CL_MAP_WRITE), both (bit-or CL/CL_MAP_READ CL/CL_MAP_WRITE) or CL_MAP_WRITE_INVALIDATE_REGION.
  • wait-events (optional): events array specifying the events (if any) that need to complete before this operation.
  • event (optional): if specified, the cl_event object tied to the execution of this operation.

This is a low-level version of enq-svm-map!.

See https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clEnqueueSVMMap.html, http://www.jocl.org/doc/org/jocl/CL.html#clEnqueueSVMMap-org.jocl.cl_command_queue-boolean-long-org.jocl.Pointer-long-int-org.jocl.cl_event:A-org.jocl.cl_event-

Examples:

  (enq-svm-map* queue svm-data false 0 CL/CL_WRITE (events ev-nd) ev-map)

enq-svm-unmap!

(enq-svm-unmap! queue svm wait-events event)(enq-svm-unmap! queue svm event)(enq-svm-unmap! queue svm)(enq-svm-unmap! svm)

Enqueues a command to indicate that the host has completed updating the region given by svm SVMMem and which was specified in a previous call to enq-svm-map!.

Arguments:

  • queue (optional): the cl_command_queue that unmaps the object. If omitted, *command-queue* will be used.
  • svm: the SVMMem that is going to be unmapped.
  • wait-events (optional): events array specifying the events (if any) that need to complete before this operation.
  • event (optional): if specified, the cl_event object tied to the execution of this operation.

If event is specified, the operation is asynchronous, otherwise it blocks the current thread until the data transfer completes. See also register.

See also enq-svm-map!.

See https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clEnqueueSVMUnmap, http://www.jocl.org/doc/org/jocl/CL.html#clEnqueueSVMUnmap-org.jocl.cl_command_queue-org.jocl.Pointer-int-org.jocl.cl_event:A-org.jocl.cl_event-

Examples:

(enq-svm-unmap! queue svm-data byte-buff (events ev-nd) ev-map)
(enq-svm-unmap! queue svm-data byte-buff ev-map)
(enq-svm-unmap! queue svm-data byte-buff)
(enq-svm-unmap! svm-data byte-buff)

enq-unmap!

(enq-unmap! queue cl host wait-events event)(enq-unmap! queue cl host event)(enq-unmap! queue cl host)(enq-unmap! cl host)

Enqueues a command to unmap a previously mapped memory region. Returns the queue.

Arguments:

  • queue (optional): the cl_command_queue that unmaps the object. If omitted, *command-queue* will be used.
  • cl: the CLMem that is going to be unmapped.
  • host: the host byte buffer that is going to be unmapped.
  • wait-events (optional): events array specifying the events (if any) that need to complete before this operation.
  • event (optional): if specified, the cl_event object tied to the execution of this operation.

If event is specified, the operation is asynchronous, otherwise it blocks the current thread until the data transfer completes. See also register.

See also enq-map-buffer!.

See https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clEnqueueUnmapMemObject, http://www.jocl.org/doc/org/jocl/CL.html#clEnqueueUnmapMemObject-org.jocl.cl_command_queue-org.jocl.cl_mem-java.nio.ByteBuffer-int-org.jocl.cl_event:A-org.jocl.cl_event-

Examples:

(enq-unmap! queue cl-data byte-buff (events ev-nd) ev-map)
(enq-unmap! queue cl-data byte-buff ev-map)
(enq-unmap! queue cl-data byte-buff)
(enq-unmap! cl-data byte-buff)

enq-write!

(enq-write! queue cl host blocking offset wait-events event)(enq-write! queue cl host wait-events event)(enq-write! queue cl host event)(enq-write! queue cl host)(enq-write! cl host)

Enqueues a command to write to a cl object from host memory. Returns the queue.

Arguments:

  • queue (optional): the cl_command_queue that writes the object. If omitted, *command-queue* will be used.
  • cl: the CLMem that is going to be written to.
  • host: Mem object on the host that the data is to be transferred from. Must be a direct buffer is the writing is asynchronous.
  • blocking: boolean indicator of synchronization.
  • offset: the offset in bytes in the buffer object to write to.
  • wait-events (optional): events array specifying the events (if any) that need to complete before this operation.
  • event (optional): if specified, the cl_event object tied to the execution of this operation.

If event is specified, the operation is asynchronous, otherwise it blocks the current thread until the data transfer completes, unless explicitly specifiend with blocking. See also register.

See https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clEnqueueWriteBuffer.html, http://www.jocl.org/doc/org/jocl/CL.html#clEnqueueWriteBuffer-org.jocl.cl_command_queue-org.jocl.cl_mem-boolean-long-long-org.jocl.Pointer-int-org.jocl.cl_event:A-org.jocl.cl_event-

Examples:

(let [host-data (direct-buffer 32)
      ev (event)
      notifications (chan)
      follow (register notifications)]
  (enq-write! my-queue cl-data host-data ev) ;; asynchronous
  (follow ev)
  (<!! notifications))

(enq-write! my-queu cl-data host-data) ;; blocking

event

(event)

event-callback

(event-callback ch)

Creates new EventCallbackFunction instance that puts EventCallbackInfo in the core.async channel when called.

See also set-event-callback* and register

events

(events)(events e)(events e0 e1)(events e0 e1 e2)(events e0 e1 e2 e3)(events e0 e1 e2 e3 e4)(events e0 e1 e2 e3 e4 & es)

Creates an array of cl_events. Arrays of events are used in enqueuing commands, not vectors or sequences.

finish!

(finish! queue)(finish!)

Blocks until all previously queued OpenCL commands in a command-queue are issued to the associated device and have completed. Returns the queue. If called with no arguments, works on the default [command-queue]

See https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clFinish.html, http://www.jocl.org/doc/org/jocl/CL.html#clFinish-org.jocl.cl_command_queue-

Example:

(finish! my-queue)

flush!

(flush! queue)

Issues all previously queued OpenCL commands in a command-queue to the device associated with the command-queue.

See https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clFlush.html, http://www.jocl.org/doc/org/jocl/CL.html#clFinish-org.jocl.cl_command_queue-

Example:

(flush! my-queue)

host-event

(host-event)(host-event ctx)

Creates new cl_event on the host (in OpenCL terminology, known as “user” event.

If called without ctx argument, uses *context*.

If ctx is nil, throws ExceptionInfo

See https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clCreateUserEvent.html, http://www.jocl.org/doc/org/jocl/CL.html#clCreateUserEvent-org.jocl.cl_context-int:A-

kernel

(kernel program name)(kernel program)

Creates cl_kernel objects for the kernel function specified by name, or, if the name is not specified, all kernel functions in a program.

Needs to be released after use.

In case of OpenCL errors during the program build, throws Exceptioninfo.

See https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clCreateKernel.html, https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clCreateKernelsInProgram.html, http://www.jocl.org/doc/org/jocl/CL.html#clCreateKernel-org.jocl.cl_program-java.lang.String-int:A- http://www.jocl.org/doc/org/jocl/CL.html#clCreateKernelsInProgram-org.jocl.cl_program-int-org.jocl.cl_kernel:A-int:A- Examples:

(kernel program "dumb_kernel") ; `cl_kernel` object
(kernel program) ; all kernels in a vector

legacy?

(legacy? platform)

Checks whether the platform is ‘legacy’, less than OpenCL 2.0, or any future version that is necessary for building ClojureCL.

Mem

protocol

An object that represents memory that participates in OpenCL operations. It can be on the device (CLMem), or on the host. Built-in implementations: cl buffer, Java primitive arrays and ByteBuffers.

members

ptr

(ptr this)

JOCL Pointer to this object.

size

(size this)

Memory size of this cl or host object in bytes.

num-devices

(num-devices platform device-type & device-types)(num-devices platform device-type)(num-devices x)(num-devices)

Queries platform for the number of devices of one or a combination of several device-types: :gpu, :cpu, :all, :accelerator, :custom, :default.

When called with only one argument x:

  • if x is a keyword, returns the number of devices of type x in *platform*;
  • otherwise returns the number of all devices on the platform x.

When called with no arguments, returns the number of all devices in *platform*.

When called with an invalid platform, throws ExceptionInfo. When called with an unknown device type, throws NullPointerException

See also num-devices*.

Examples:

(num-devices)
(num-devices (first (platforms)))
(num-devices :gpu)
(num-devices (first (platforms)) :gpu :cpu :accelerator)

num-devices*

(num-devices* platform device-type)

Queries platform for the number of devices of device-types. Device types are given as a bitfield, where each type is defined in the OpenCL standard. Available device types are accessible through org.jocl.CL/CL_DEVICE_TYPE_X constants. If there are no such devices, returns 0.

NOTE: You should prefer a higher-level num-devices function, unless you already have a device-type in a long number form in your code.

When called with an invalid platform, throws ExceptionInfo.

See http://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clGetDeviceIDs.html and http://www.jocl.org/doc/org/jocl/CL.html#clGetDeviceIDs-int-org.jocl.cl_device_id:A-int:A-

num-kernels

(num-kernels program)

Returns the number of kernels in program (cl_program).

num-platforms

(num-platforms)

platform-info

(platform-info)

Gets the info/info of the default platform *platform* (if it is bound). If *platform* is unbound, throws Illegalargumentexception.

platforms

(platforms)

Returns a vector of all available OpenCL platforms (cl_platform_ids). cl_platform_id objects do not need to be released explicitly.

Platforms are represented by the org.jocl.platform_id datastructure.

See http://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clGetPlatformIDs.html and http://www.jocl.org/doc/org/jocl/CL.html#clGetPlatformIDs-int-org.jocl.cl_platform_id:A-int:A-

program-with-source

(program-with-source ctx source)(program-with-source source)

Creates a cl_program for the context and loads the source code specified by the text strings given in the source sequence. When called with one argument, uses *context*.

In case of OpenCL errors during the program creation, throws Exceptioninfo.

Needs to be released after use.

See also build-program!

See https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clCreateProgramWithSource.html, http://www.jocl.org/doc/org/jocl/CL.html#clCreateProgramWithSource-org.jocl.cl_context-int-java.lang.String:A-long:A-int:A-

Example:

(def source (slurp "path-to-kernels/my_kernel.cl"))
(program-with-source ctx [source])

register

(register channel callback-type)(register channel)

Creates a convenience function that registers callbacks for events. It is a high-level alternative to set-event-callback*. MUST be called AFTER the event is used in the enqueue operation.

  • channel is a channel for communicating asynchronous notifications
  • callback-type is an optional keyword that specifies the command execution status that will be the default for the resulting function: :complete, :submitted, or running.

Returns a function with the following arguments:

  • e - user event that is being followed
  • callback-type - optional command execution status; if ommited, the default is used
  • data - optional notification data

When called, the created function returns channel with registered callback.

See event-callback, set-event-callback*, event. See https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clSetEventCallback.html, http://www.jocl.org/doc/org/jocl/CL.html#clSetEventCallback-org.jocl.cl_event-int-org.jocl.EventCallbackFunction-java.lang.Object-

Example:

(def notifications (chan))
(def follow (register notifications))
(def e (event))
(enq-read! comm-queue cl-object host-object e
(follow e)
(:event (<!! notifications))

set-arg!

(set-arg! kernel n value)

Sets the argument value for a specific positional argument of a kernel. Returns the changed cl_kernel object. value should implement Argument protocol.

The arguement can be a Mem (CLBuffer, CLImage, Java primitive arrays), or a number. In the case of Mem objects, the memory object will be set as an argument. In the case the argument is a number, its long value will be used as a size of the local memory to be allocated on the device.

In case of OpenCL errors during the program build, throws Exceptioninfo. if value is of the type that is not supported, throws IllegalArgumentexception.

See kernel, program, Argument, cl-buffer.

See https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clSetKernelArg.html, http://www.jocl.org/doc/org/jocl/CL.html#clSetKernelArg-org.jocl.cl_kernel-int-long-org.jocl.Pointer-

Examples:

(set-arg! my-kernel 0 cl-buffer0)
(set-arg! my-kernel 1 cl-buffer1)
(set-arg! my-kernel 2 (int-array 8))
(set-arg! my-kernel 3 42)

set-args!

(set-args! kernel x & values)

Sets all provided arguments of kernel, starting from optional index x, and returns the changed cl_kernel object. Equivalent to calling set-arg! for each provided argument.

Examples:

(set-args! my-kernel cl-buffer-0)
(set-args! my-kernel cl-buffer-0 cl-buffer-1 (int-array 8) 42)
(set-args! my-kernel 2 cl-buffer-2 cl-buffer-3 (int-array 8) 42)

set-event-callback*

(set-event-callback* e callback callback-type data)(set-event-callback* e callback)

Registers a callback function for an event and a specific command execution status. Returns the channel. MUST be called AFTER the event is used in the enqueue operation.

If called without callback-type and data, registers CL/CL_COMPLETE status.

See event-callback, register, event. See https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clSetEventCallback.html, http://www.jocl.org/doc/org/jocl/CL.html#clSetEventCallback-org.jocl.cl_event-int-org.jocl.EventCallbackFunction-java.lang.Object-

Example:

(set-event-callback* (user-event) (event-callback) CL/CL_COMPLETE :my-data)
(set-event-callback* (user-event) (event-callback))

set-status!

(set-status! ev status)(set-status! ev)

Sets the status of a host event to indicate whether it is complete or there is an error (a negative value). It can be called only once to change the status. If called with only the first argument, sets the status to CL/CL_COMPLETE. Returns the event.

See https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clSetUsereventstatus.html, http://www.jocl.org/doc/org/jocl/CL.html#clSetUserEventStatus-org.jocl.cl_event-int-

Examples:

(set-status! ev) ;; event's status will be CL_COMPLETE
(set-status! ev -12) ;; indicates and error code -12

sort-by-cl-version

(sort-by-cl-version devs)

Sorts a given sequence of devices by the OpenCL version they support. The devices with hihger versions come first. If some devices support the same version their order is not changed.

svm-buffer

(svm-buffer ctx size alignment & flags)(svm-buffer size flag)(svm-buffer size)

Creates a svm buffer object (SVMBuffer) in ctx, given size and alignment in bytes and one or more memory allocation usage keyword flags: :read-write, :read-only, :write-only, :fine-grain-buffer, and/or :atomics

If called with two arguments, uses the default alignment (platform dependent) and default *context* (see with-context). If called with one argument, use the default context, and alignment,and :read-write flag.

Needs to be released after use. If you rely on the release method, be sure that all enqueued processing that uses this buffer finishes prior to that (watch out for non-blocking enqueues!).

If ctx is nil or the buffer size is invalid, throws IllegalArgumentException. If some of the flags is invalid, throws NullPointerException.

See http://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clSVMAlloc.html, http://www.jocl.org/doc/org/jocl/CL.html#clSVMAlloc-org.jocl.cl_context-long-long-int-

Examples:

(svm-buffer 32 :read-only)
(svm-buffer ctx 24 0 :fine-grain-buffer :atomics)

svm-buffer*

(svm-buffer* ctx size flags alignment)

Creates a svm buffer object in ctx, given size in bytes, bitfield flags describing memory allocation usage, and alignment size.

Flags defined by the OpenCL standard are available as constants in the org.jocl.CL class.

Needs to be released after use.

This is a low-level alternative to svm-buffer! If ctx is nil or the buffer size is invalid, throws IllegalArgumentException.

See http://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clSVMAlloc.html, http://www.jocl.org/doc/org/jocl/CL.html#clSVMAlloc-org.jocl.cl_context-long-long-int-

Example:

(svm-buffer* ctx 24 (bit-or CL/CL_MEM_SVM_FINE_GRAIN_BUFFER CL/CL_MEM_SVM_ATOMICS) 0)

svm-buffer?

(svm-buffer? x)

Checks whether an object is an SVM buffer.

SVMMem

protocol

A wrapper for SVM Buffer objects, that also holds a context that created it, Pointer, size in bytes, and can create a ByteBuffer. It is useful in many functions that need that (redundant in Java) data because of the C background of OpenCL functions.

members

byte-buffer

(byte-buffer this)(byte-buffer this offset size)

Creates a Java ByteBuffer for this SVM memory.

enq-svm-copy

(enq-svm-copy this)

with-context

macro

(with-context context & body)

Dynamically binds context to the default context *context*. and evaluates the body with that binding. Releases the context in the finally block. Take care not to release that context in some other place; JVM might crash.

Example:

(with-context (context devices)
    (context-info))

with-default

macro

(with-default & body)

Dynamically binds *platform*, *context* and *command-queue* to the first of the available platforms, the context containing the first device of that platform that supports the highest OpenCL version, and the queue on the device in that context. Requires OpenCL 2.0 support in the platform.

with-platform

macro

(with-platform platform & body)

Dynamically binds platform to the default platform *platform* and evaluates the body with that binding.

with-queue

macro

(with-queue queue & body)

Dynamically binds queue to the default queue *command-queue*. and evaluates the body with that binding. Releases the queue in the finally block. Take care not to release that queue in some other place; JVM might crash.

Example:

(with-queue (command-queue dev)
  (enq-read cl-data data))

work-size

(work-size global local offset)(work-size global local)(work-size global)(work-size)

Creates a WorkSize record, that sets global, local and offset parameters in enqueuing ND kernels. All arguments are sequences, holding as many arguments, as there are dimensions in the appropriate ND kernel. In OpenCL 2.0, it is usually 1, 2, or 3, depending on the device.

See enq-nd! Examples:

(work-size [102400 25600] [1024 128] [4 8])
(work-size [1024 256] [16 16])
(work-size [256])
(work-size) ; same as (work-size [1])

work-size-1d

(work-size-1d global local offset)(work-size-1d global local)(work-size-1d global)(work-size-1d)

Creates a 1-dimensional WorkSize from the long numbers it receives. See also work-size.

Examples: (work-size-1d 1024) (work-size-1d 1024 256) (work-size-1d 1024 256 1)

work-size-2d

(work-size-2d global0 global1 local0 local1 offset0 offset1)(work-size-2d global0 global1 local0 local1)(work-size-2d global0 global1)(work-size-2d)

Creates a 2-dimensional WorkSize from the long numbers it receives. See also work-size.

Examples: (work-size-2d 1024 2048) (work-size-2d 1024 2048 16 16) (work-size-2d 1024 2048 16 16 8 0 2)

work-size-3d

(work-size-3d global0 global1 global2 local0 local1 local2 offset0 offset1 offset2)(work-size-3d global0 global1 global2 local0 local1 local2)(work-size-3d global0 global1 global2)(work-size-3d)

Creates a 3-dimensional WorkSize from the long numbers it receives. See also work-size.

Examples: (work-size-3d 1024 2048 512) (work-size-3d 1024 2048 256 16 16) (work-size-3d 1024 2048 128 16 4 4 16 0 2 512)