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](http://www.jocl.org) for calling
native OpenCL drivers - the datastructures are therefore defined in JOCL.
They can be found in [`org.jocl`]
(http://www.jocl.org/doc/org/jocl/package-tree.html) 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 work with primitive arguments
and give primitive results. These functions are useful when you
already have primitive data and want to avoid unnecessary conversions.
You can find them in the [[uncomplicate.clojurecl.internal.impl]] namespace.
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
* resource management: [[with-release]], [[with-platform]], [[with-context]], [[with-queue]],
[[with-default]].
* [`cl_platform_id`](http://www.jocl.org/doc/org/jocl/cl_platform_id.html):
[[num-platforms]], [[platforms]], [[platform-info]], [[with-platform]].
* [`cl_device_id`](http://www.jocl.org/doc/org/jocl/cl_device_id.html):
[[devices]], [[num-devices]].
* [`cl_context`](http://www.jocl.org/doc/org/jocl/cl_context.html):
[[context]], [[context-info]], [[with-context]], [[context-properties]].
* [`cl_mem`](http://www.jocl.org/doc/org/jocl/cl_mem.html):
[[cl-buffer]], [[cl-sub-buffer]], [[cl-buffer*]], [[Mem]], [[CLMem]].
* [`cl_event`](http://www.jocl.org/doc/org/jocl/cl_event.html):
[[event]], [[host-event]], [[events]], [[register]], [[event-callback]], [[set-status!]].
* [`cl_program`](http://www.jocl.org/doc/org/jocl/cl_program.html):
[[program-with-source]], [[build-program!]].
* [`cl_kernel`](http://www.jocl.org/doc/org/jocl/cl_kernel.html):
[[num-kernels]], [[kernel]], [[set-arg!]], [[set-args!]], [[set-arg]].
* [`cl_command_queue`](http://www.jocl.org/doc/org/jocl/cl_kernel.html):
[[command-queue]], [[work-size]], [[enq-kernel!]],
[[enq-read!]], [[enq-write!]], [[enq-copy!]], [[enq-fill!]], [[enq-map-buffer!]], [[enq-unmap!]],
[[enq-svm-map!]], [[enq-svm-unmap!]], [[enq-marker!]], [[enq-wait!]], [[enq-barrier!]],
[[finish!]], [[flush!]] [[with-queue]].
*command-queue*
dynamic
Dynamic var for binding the default command queue.
*context*
dynamic
Dynamic var for binding the default context.
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 [[internal/CLProgram]] that contains the program
source or binary;
* `devices` (optional): an optional sequence of [[internal/CLDevice]] 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? 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)
command-queue
(command-queue ctx device x & properties)(command-queue ctx device)(command-queue device)(command-queue)
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. Otherwise, you will get an
UnsupportedOperationException erorr. 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-1
(command-queue-1 ctx device x & properties)(command-queue-1 ctx device)(command-queue-1 device)(command-queue-1)
Creates a host or device command queue on a specific device.
** If you need to support legacy OpenCL 1.2 or earlier platforms,
you MUST use this function instead of [command-queue], which is for
OpenCL 2.0 and higher. What is important is the version of the platform,
not the devices.**
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-1*]].
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,
https://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clCreateCommandQueue.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-
http://www.jocl.org/doc/org/jocl/CL.html#clCreateCommandQueue-org.jocl.cl_context-org.jocl.cl_device_id-long-int:A-
Examples:
(command-queue-1 ctx)
(command-queue-1 ctx dev)
(command-queue-1 ctx dev :profiling)
(command-queue-1 ctx dev 524288 :queue-on-device)
context
(context devices properties ch user-data)(context devices)(context)
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.
devices
(devices platform device-type & device-types)(devices x)(devices)
Queries `platform` for the devices of one or a combination of
several `device-type`s:
`:gpu`, `:cpu`, `:all`, `:accelerator`, `:custom`, `:default`,
and returns them in a vector containing [[internal/CLDevice]] 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]
(http://clojuredocs.org/clojure.core/ex-info). When called with an unknown
device type, throws `NullPointerException`
See also [[internal/devices*]].
Examples:
(devices)
(devices (first (platforms)))
(devices :gpu)
(devices (first (platforms)) :gpu :cpu :accelerator)
enq-barrier!
(enq-barrier! queue)(enq-barrier! queue ev)(enq-barrier! queue wait-events ev)
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)
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)
enq-kernel!
(enq-kernel! queue kernel work-size wait-events event)(enq-kernel! queue kernel work-size event)(enq-kernel! queue kernel work-size)(enq-kernel! kernel work-size)
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-marker!
(enq-marker! queue)(enq-marker! queue ev)(enq-marker! queue wait-events ev)
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-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)
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
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_event`s. Arrays of events are
used in enqueuing commands, not vectors or sequences.
finish!
(finish! queue)(finish!)
host-event
(host-event)(host-event ctx)
kernel
(kernel program name)(kernel program)
legacy?
(legacy? platform)
Checks whether the platform is 'legacy', less than OpenCL 2.0, or any
future version that is necessary for building ClojureCL.
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-type`s:
`: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]
(http://clojuredocs.org/clojure.core/ex-info). 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-kernels
(num-kernels program)
Returns the number of kernels in `program` (`cl_program`).
program-with-source
(program-with-source ctx source)(program-with-source 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))
release-context!
(release-context!)
Release global platform, context, and command queue (if any exists).
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:n
(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-context!
(set-context! ctx)(set-context!)
Sets the var root binding of [[*context*]] to the context `ctx` or the default context.
set-default!
(set-default!)
Sets the root bindings to the default platform, context and command queue.
set-default-1!
(set-default-1!)
Sets the root bindings to the default platform, context and command queue.
set-queue!
(set-queue! q)(set-queue!)
Sets the var root binding of [[*command-queue*]] to the queue `q` or the default command queue on
the default device in the default context.
set-status!
(set-status! ev status)(set-status! ev)
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? x)
Checks whether an object is an SVM buffer.
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.
If you're using OpenCL 1.2 or lower, use [[with-default-1]]
with-default-1
macro
(with-default-1 & body)
Dynamically binds [[*platform*]], [[*context*]] and [[*command-queue]]
to the first of the available platforms, the context containing the first
device of that platform, and the queue on the device in that context.
Supports pre-2.0 platforms.
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-kernel!]]
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)